cr_canseeothergids(9): Revamp, mark as internal

[olce]

Summary

Significantly clarify. Replace references to cr_canseeotheruids(9) by ones to
cr_bsd_visible(9).

[olce]

Change the one-line description. New sentences on new lines.

[olce]

Wrong previous diff.

[pauamma_gundo.com]

English LGTM.

[olce]

Rename cr_bsd_visibility() to cr_bsd_visible().

[olce]

And also addressed similar issues as reported in https://reviews.freebsd.org/D40639.

[olce]

'cr_see*' => 'cr_cansee*' (suppressed a rename in the stack).

[olce]

Fix inverted description of when the policy is enabled.

[mhorne]

It is unusual to have a man page for a static function; I cannot think of any other example. Given the history of this page and its siblings, I think it is fine to keep it, but an argument could be made to only keep cr_bsd_visible(9).

share/man/man9/cr_canseeothergids.9

51

Only a suggestion.

52

71–77

I see the inaccuracy of the previous description, but what you have written is not a complete sentence. Even though it is a sensible short-hand, the prevailing style for this section is to be explicit.

My suggestion:

The
.Fn cr_canseeothergids
function returns 0 if the policy is disabled, the credentials share at least one common group, or if
.Fa u1
has privilege exempting it from the policy.
Otherwise, it returns
.Er ESRCH .

[olce]

Address (most) @mhorne's comments.

Updating D40633: cr_canseeothergids(9): Revamp, mark as internal

Significantly clarify. Replace references to cr_canseeotheruids(9) by ones to
cr_bsd_visible(9).

[olce]

In D40633#941566, @mhorne wrote:

It is unusual to have a man page for a static function; I cannot think of any other example. Given the history of this page and its siblings, I think it is fine to keep it, but an argument could be made to only keep cr_bsd_visible(9).

I understand, but given that these man pages have been around for 20+ years, maybe keeping them for now is the less disruptive path. We could remove them in a few releases.

share/man/man9/cr_canseeothergids.9

51

I'd prefer to leave that out, for several reasons. First, static is a C implementation detail, rather than the intent itself. Second, it works only for functions defined and used in the same translation unit, so applies almost always to functions defined and used in a single one. If that state changes, we would need to change the manpage as well. Granted, that's not a big one, but given the frequency with which this page has been updated in the past...