Man page for capsicum helpers.
ClosedPublic
Actions

Authored by oshogbo on Oct 5 2016, 1:33 PM.

Details

Reviewers

emaste
cem
allanjude

Commits

rS306726: Add man pages for Capsicum helpers.

Summary

My try to document capsicum helpers.

Diff Detail

Lint

Lint Skipped

Unit

Tests Skipped

Event Timeline

oshogbo updated this revision to Diff 21065.Oct 5 2016, 1:33 PM

oshogbo retitled this revision from to Man page for capsicum helpers..

oshogbo updated this object.

oshogbo edited the test plan for this revision. (Show Details)

oshogbo added a subscriber: manpages.

cem added a subscriber: cem.Oct 5 2016, 3:50 PM

cem added inline comments.

lib/libcapsicum/capsicum_helpers.3
65	no need for "the"
67	linking -> link But I might remove the clause about linking entirely.
71	.Fn caph_limit_stream restricts capabilities on .Fa fd to only those needed by POSIX stream objects (that is, FILEs).
72–73	Implementation details. I think this should be omitted from the page. If users rely upon these specific rights, their applications may break if we ever change those rights.
74–77	Same. (Implementation detail subject to change.) I think this should be removed.
83	error -> an error, descriptors -> descriptor
94	functions limit standard descriptors using .Fn caph_limit_stream .
99	s/ using standard method// The preceding sentence, the names, and the remainder of this sentence makes this clear.
101–103	.Fn caph_cache_tzdata precaches all timezone data needed to use .Li libc local time functions.
107–109	`The .Nm foo function` -> `.Fn foo` here, too. .Fn caph_cache_catpages caches Native Language Support (NLS) data.
110	NLS data is used for localized error printing by .Xr strerror 3 and .Xr err 3 , among others.
115–116	These two (fcntl, ioctl) can be removed.

Fix as @cem suggested.
Some more Fn fixes.
Add Makefile change.

cem added inline comments.Oct 5 2016, 4:32 PM

lib/libcapsicum/capsicum_helpers.3
66	I would just remove the clause. We intend to make this into a library that requires linking, so the current header-only status is a temporary implementation detail.
99	precaches :-)
103–105	The .Fn caph_cache_catpages function can just be .Fn caph_cache_catpages

cem added reviewers: allanjude, emaste.Oct 5 2016, 4:32 PM

emaste added inline comments.Oct 5 2016, 4:37 PM

lib/libcapsicum/capsicum_helpers.3
66	What about a overall comment about this being in flux and that implementation details may change? I think we want to suggest that these are somewhat experimental at the moment. Obviously "we" will take care of all in-tree consumers, but external consumers should know they may have to do some rework.

I'm still not sure how libcapsicum will look like but I would love to see that capsicum helpers don't need additional library.

Remove function word.
Remove all my preaches.

cem accepted this revision.Oct 5 2016, 7:08 PM

cem added a reviewer: cem.

cem added inline comments.

lib/libcapsicum/capsicum_helpers.3
104	No "The" needed either. :)

This revision is now accepted and ready to land.Oct 5 2016, 7:08 PM

@cem what about caph_cache_tzdata, caph_limit_{stdin,stderr,stdout} and caph_limit_stream, should I remove all "function(s)" and "the"?

In D8154#169174, @oshogbo wrote:

@cem what about caph_cache_tzdata, caph_limit_{stdin,stderr,stdout} and caph_limit_stream, should I remove all "function(s)" and "the"?

When using .Fn, yeah, I think so. If referred to by .Nm instead, maybe not.

Closed by commit rS306726: Add man pages for Capsicum helpers. (authored by oshogbo). · Explain WhyOct 5 2016, 8:02 PM

This revision was automatically updated to reflect the committed changes.

wblock added a subscriber: wblock.Oct 7 2016, 3:45 PM

wblock added inline comments.

head/lib/libcapsicum/capsicum_helpers.3
60 ↗	(On Diff #21085)	Probably not necessary to capitalize "Capsicumizing". There is a little ambiguity in whether these functions simplify capsicumizing (modifying) some programs, or whether they simplify "capsicumizing programs" (programs which are used to capsicumize other programs). The first meaning is certainly intended, so maybe just switch it to say "...simplify modifying programs to use Capsicum."
73 ↗	(On Diff #21085)	s/The following/These/