Page MenuHomeFreeBSD

Man page for capsicum helpers.
ClosedPublic

Authored by oshogbo on Oct 5 2016, 1:33 PM.
Tags
None
Referenced Files
Unknown Object (File)
Tue, Dec 10, 5:29 PM
Unknown Object (File)
Tue, Dec 3, 10:50 PM
Unknown Object (File)
Nov 8 2024, 5:38 PM
Unknown Object (File)
Nov 8 2024, 5:38 PM
Unknown Object (File)
Nov 8 2024, 5:38 PM
Unknown Object (File)
Oct 1 2024, 8:37 PM
Unknown Object (File)
Oct 1 2024, 8:37 PM
Unknown Object (File)
Oct 1 2024, 8:37 PM

Details

Summary

My try to document capsicum helpers.

Diff Detail

Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

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 inline comments.
lib/libcapsicum/capsicum_helpers.3
64

no need for "the"

66

linking -> link

But I might remove the clause about linking entirely.

70
.Fn caph_limit_stream
restricts capabilities on
.Fa fd
to only those needed by POSIX stream objects (that is, FILEs).
71–72

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.

73–76

Same. (Implementation detail subject to change.) I think this should be removed.

82

error -> an error, descriptors -> descriptor

93
functions limit standard descriptors using
.Fn caph_limit_stream .
98

s/ using standard method//

The preceding sentence, the names, and the remainder of this sentence makes this clear.

100–102
.Fn caph_cache_tzdata
precaches all timezone data needed to use
.Li libc
local time functions.
106–108

The .Nm foo function -> .Fn foo here, too.

.Fn caph_cache_catpages
caches Native Language Support (NLS) data.
109
NLS data is used for localized error printing by
.Xr strerror 3
and
.Xr err 3 ,
among others.
114–115

These two (fcntl, ioctl) can be removed.

oshogbo changed the visibility from "All Users" to "Public (No Login Required)".

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

lib/libcapsicum/capsicum_helpers.3
67

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.

100

precaches :-)

104–106

The .Fn caph_cache_catpages function

can just be

.Fn caph_cache_catpages

lib/libcapsicum/capsicum_helpers.3
67

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 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"?

@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.

This revision was automatically updated to reflect the committed changes.
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/