Op 04/06/18 om 16:57 schreef Kristaps Dzonsons:
Hi folks,

Short: what do you recommend for documenting an external library's
pledge(2) requirements?

Longer: https://bsd.network/@florian/99802355448571943

The question raised in this... um... toot?... is which promises are
required by an external library call, in this case khttp_parse(3) in
kcgi.  Sure, we can always just run the program, look in
/var/log/messages for failure, and edit our promises.  But just... no.

In this particular case, I've documented this function's requirements
unofficially here and there---tutorials and such.  But it's not
canonical.  What I'd like is to put these directly into the manpages.

Something like:

.Ox ,
.Fn khttp_parse
function requires the
.Qq stdio proc
promises to
.Xr pledge 2 .

This encourages developers to use the tightest possible promises.  And
as mdoc(7) is meant not to be system-specific, this might also include
information on, say, .Fx's Capsicum, or maybe whatever Linux uses this
week.  It already has "SECURITY CONSIDERATIONS", but that just doesn't
seem quite right.



What about having some sort of function yourlib_pledge_set_promises() that sets up these requirements ? I think this also has the advantage of automatically separating pledge specific code (and a man page) from generic code as well as lessening the chance of users of your library setting up incorrect promises for your library. Or in light of updates to your library, users may not need to change their program's pledges since the updated yourlib_pledge_set_promises function will hopefully be sufficient to take care of that.

Reply via email to