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: .Sh SANDBOXING On .Ox , the .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. Thoughts? Kristaps