namei: Update documentation.
ClosedPublic
Actions

Authored by des on May 16 2025, 2:57 PM.

Details

Reviewers

mjg
kib
markj

Group Reviewers

Klara

Commits

rG747efc2aeeab: namei: Update documentation.
rG68bc635cc9b0: namei: Update documentation.
rGee84b4e2fdf0: namei: Update documentation.

Summary

This should have been done 2+ years ago when the td argument was dropped
from NDINIT() and the NDFREE() macro and the SAVENAME and SAVESTART
flags were retired.

MFC after: 3 days
Fixes: 7e1d3eefd410 ("vfs: remove the unused thread argument from NDINIT*")
Fixes: 269c564b90d3 ("vfs: retire NDFREE")
Sponsored by: NetApp, Inc.

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

des created this revision.May 16 2025, 2:57 PM

Herald added subscribers: ziaee, imp. · View Herald TranscriptMay 16 2025, 2:57 PM

des requested review of this revision.May 16 2025, 2:57 PM

Harbormaster completed remote builds in B64219: Diff 155563.May 16 2025, 2:57 PM

des added reviewers: mjg, kib.May 16 2025, 3:00 PM

Please use standard trailer format for Fixes (one commit per line) for the sake of existing and/or new tooling

Fixes: 7e1d3eefd410 ("vfs: remove the unused thread argument from NDINIT*")
Fixes: 269c564b90d3 ("vfs: retire NDFREE")

des added inline comments.May 16 2025, 6:34 PM

share/man/man9/namei.9
236–237	turns out we no longer have `SAVENAME`, so still needs a little more work

SAVENAME and SAVESTART are no more

Harbormaster completed remote builds in B64226: Diff 155576.May 16 2025, 6:45 PM

des edited the summary of this revision. (Show Details)May 16 2025, 6:45 PM

des edited the summary of this revision. (Show Details)

markj accepted this revision as: markj.May 16 2025, 8:38 PM

markj added a subscriber: markj.

markj added inline comments.

share/man/man9/namei.9
80	There is also NDINIT_AT, NDINIT_ATRIGHTS, NDINIT_ATVP.

This revision is now accepted and ready to land.May 16 2025, 8:38 PM

NDINIT_AT

This revision now requires review to proceed.May 16 2025, 10:17 PM

Harbormaster completed remote builds in B64237: Diff 155591.May 16 2025, 10:17 PM

des marked an inline comment as done.May 16 2025, 10:17 PM

des added inline comments.

share/man/man9/namei.9
80	I'll add `NDINIT_AT` as it's pretty important these days. I have no idea what the others do, though, and I don't want to speculate.

markj accepted this revision as: markj.May 17 2025, 12:03 AM

markj added inline comments.

share/man/man9/namei.9
129	The NDINIT_ATRIGHTS macros is equivalent to NDINIT_AT, but additionally takes a set of Capsicum rights and verifies that the directory file descriptor carries those rights before proceeding the with the lookup, otherwise ENOTCAPABLE is returned. NDINIT_ATVP takes a vnode instead of a file descriptor for the starting directory.

This revision is now accepted and ready to land.May 17 2025, 12:03 AM

kib added inline comments.May 17 2025, 3:57 AM

share/man/man9/namei.9
50–51	The flags are no longer u_long, it is uint64_t
143	I think the most useful bit from this manpage for most casual readers would be an example for the simple NDINIT with corresponding NDFREE_PNBUF() and error handling. Just such code struct nameidata nd; NDINIT(&nd, LOOKUP, FOLLOW \| LOCKLEAF \| AUDITVNODE1, UIO_USERSPACE, uap->path); if ((error = namei(&nd)) != 0) return (error); NDFREE_PNBUF(&nd); would be a huge step in describing the interface.

des marked 2 inline comments as done.May 17 2025, 7:02 AM

des added inline comments.

share/man/man9/namei.9
129	Thank you, I'll add these later as I'm pressed for time.
143	The current text does not describe `AUDITVNODE1` and again, I don't like to speculate. If you can describe the missing flags, I'll add them and your example in a subsequent commit.