Details
- Reviewers
bapt emaste ziaee - Group Reviewers
manpages - Commits
- rGb6f4027ad9a2: setcred(2): Add manual page
Diff Detail
- Repository
- rG FreeBSD src repository
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
This is beautiful! Just a few grammar polish suggestions from me. Many thanks for tagging manpages.
| lib/libsys/setcred.2 | ||
|---|---|---|
| 29 | What is this exclamation mark? It renders as a space on console. | |
| 33–40 | Maybe move this third paragraph to SECURITY CONSIDERATIONS for structure and flow, with this Sx link (which is clickable on man.freebsd.org or GUIs like gnome-help)? | |
| 117 | ||
| 122 | ||
| 123–126 | ||
| 128–133 | mac_text(3) is mlinked to mac_from_text(3), so it can be written cleaner by just linking to that. | |
| 216 | This just eliminates a linter warning. | |
Apply (most) suggestions. Tiny word additions to HISTORY and SECURITY CONSIDERATIONS.
| lib/libsys/setcred.2 | ||
|---|---|---|
| 29 | It's a non-breakable space, to avoid (0) being split from super-user in its own line. | |
| 33–40 | Mmm... It's regular practice to evoke in which circumstances a call can be made in DESCRIPTION, and in particular required privileges/permissions. I have not seen SECURITY CONSIDERATIONS to be used for that purpose. It rather seems to be a section about the effects of the call and impacts on other parts of the application/system, where in particular the user is warned about common/reasonable assumptions that could be violated or specific points to watch for. It seems it is currently unusual to mention the effect of the MAC framework and policies on system calls in their manual pages. I suspect the main reason is simply that most credentials-changing calls existed before MAC was introduced. Also, setcred()'s creation was prompted by work on the mac_do(4) policy, and although using it independently certainly has value, it is first going to be used in mdo(1), so in conjunction with mac_do(4). Going forward, I'd also like to give more visibility to the MAC framework in general, and its potential effects. I'm not sure a new, specific MAC section is warranted though. For the time being, it thus may be preferable to leave this text here instead of moving it to SECURITY CONSIDERATIONS. | |
| 123–126 | by contrast with is also fine, as in fact any combination from by/in contrast with/to, but I agree that in contrast to seems much more used in modern usage. Changed. | |
| 128–133 | Yes, I know. Just wanted to link to the original page mac_text(3), but that was probably silly. | |
| 216 | Ok. Just FYI, mdoc(7) says "Format the FreeBSD version provided as an argument, or a default value if no argument is provided.". Not knowing what this "default value" is, and inferring it could be the version of the running system, I chose to use "FreeBSD" directly. If this standalone .Fx usage is indeed the norm, I think mdoc(7) should be updated accordingly. | |
| lib/libsys/setcred.2 | ||
|---|---|---|
| 29 | The latter. I've reworked that passage. Is it OK now? | |
LGTM from a manpages standpoint (not a programmer).
I wonder if it would be good to .Nd set current process credentials atomically for people who use narrower console widths/straightforwardness. That doesn't remove any search keywords.
| lib/libsys/setcred.2 | ||
|---|---|---|
| 29 | TIL, thank you. | |
Yes, there was no real need to be that nuanced in the title, I've changed the herald description as suggested. Thanks!