git: 747efc2aeeab - releng/14.3 - namei: Update documentation.
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Wed, 21 May 2025 17:37:26 UTC
The branch releng/14.3 has been updated by des:
URL: https://cgit.FreeBSD.org/src/commit/?id=747efc2aeeabf5e56716c150ecc5f06d67b0b18a
commit 747efc2aeeabf5e56716c150ecc5f06d67b0b18a
Author: Dag-Erling Smørgrav <des@FreeBSD.org>
AuthorDate: 2025-05-17 07:43:02 +0000
Commit: Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2025-05-21 17:37:10 +0000
namei: Update documentation.
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.
Approved by: re (cperciva)
MFC after: 3 days
Fixes: 7e1d3eefd410 ("vfs: remove the unused thread argument from NDINIT*")
Fixes: 269c564b90d3 ("vfs: retire NDFREE")
Sponsored by: NetApp, Inc.
Reviewed by: markj
Differential Revision: https://reviews.freebsd.org/D50375
(cherry picked from commit ee84b4e2fdf09f9a6dfa43e0931d8671cc15ebf9)
(cherry picked from commit 68bc635cc9b099fb03cfcd519046c385af0c5355)
---
ObsoleteFiles.inc | 3 +++
share/man/man9/Makefile | 3 ++-
share/man/man9/namei.9 | 69 ++++++++++++++++++++++++++++++++-----------------
3 files changed, 50 insertions(+), 25 deletions(-)
diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc
index e1c50607abb4..439df5e89377 100644
--- a/ObsoleteFiles.inc
+++ b/ObsoleteFiles.inc
@@ -51,6 +51,9 @@
# xargs -n1 | sort | uniq -d;
# done
+# 20250521: NDFREE(9) -> NDFREE_PNBUF(9)
+OLD_FILES+=usr/share/man/man9/NDFREE.9.gz
+
# 20250419: removal of iwlwifi firmware files
OLD_FILES+=usr/share/doc/legal/intel_iwlwifi_firmware.LICENCE
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 6993b34e5b4a..e424692fbdee 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1630,7 +1630,8 @@ MLINKS+=mutex.9 mtx_assert.9 \
mutex.9 mtx_unlock_flags.9 \
mutex.9 mtx_unlock_spin.9 \
mutex.9 mtx_unlock_spin_flags.9
-MLINKS+=namei.9 NDFREE.9 \
+MLINKS+=namei.9 NDFREE_PNBUF.9 \
+ namei.9 NDINIT_AT.9 \
namei.9 NDINIT.9
MLINKS+=netisr.9 netisr_clearqdrops.9 \
netisr.9 netisr_default_flow2cpu.9 \
diff --git a/share/man/man9/namei.9 b/share/man/man9/namei.9
index 63a6d3b11f6f..1703faaeee99 100644
--- a/share/man/man9/namei.9
+++ b/share/man/man9/namei.9
@@ -31,13 +31,14 @@
.\" If you integrate this manpage in another OS, I'd appreciate a note
.\" - eivind@FreeBSD.org
.\"
-.Dd December 17, 2024
+.Dd May 16, 2025
.Dt NAMEI 9
.Os
.Sh NAME
.Nm namei ,
.Nm NDINIT ,
-.Nm NDFREE
+.Nm NDINIT_AT ,
+.Nm NDFREE_PNBUF
.Nd pathname translation and lookup operations
.Sh SYNOPSIS
.In sys/param.h
@@ -47,11 +48,16 @@
.Fn namei "struct nameidata *ndp"
.Ft void
.Fo NDINIT
-.Fa "struct nameidata *ndp" "u_long op" "u_long flags"
-.Fa "enum uio_seg segflg" "const char *namep" "struct thread *td"
+.Fa "struct nameidata *ndp" "enum nameiop op" "u_int64_t flags"
+.Fa "enum uio_seg segflg" "const char *namep"
.Fc
.Ft void
-.Fn NDFREE "struct nameidata *ndp" "const uint flags"
+.Fo NDINIT_AT
+.Fa "struct nameidata *ndp" "enum nameiop op" "u_int64_t flags"
+.Fa "enum uio_seg segflg" "const char *namep" "int dirfd"
+.Fc
+.Ft void
+.Fn NDFREE_PNBUF "struct nameidata *ndp"
.Sh DESCRIPTION
The
.Nm
@@ -71,13 +77,13 @@ flag was specified or not.
.Pp
The
.Fn NDINIT
-function is used to initialize
+macro is used to initialize
.Nm
components.
It takes the following arguments:
.Bl -tag -width ".Fa segflg"
.It Fa ndp
-The
+A pointer to the
.Vt "struct nameidata"
to initialize.
.It Fa op
@@ -95,7 +101,7 @@ will not result in
.Fn VOP_RENAME
being called.
.It Fa flags
-Operation flags.
+Operation flags, described in the next section.
Several of these can be effective at the same time.
.It Fa segflg
UIO segment indicator.
@@ -106,10 +112,35 @@ or in the kernel address space
.It Fa namep
Pointer to the component's pathname buffer
(the file or directory name that will be looked up).
-.It Fa td
-The thread context to use for
-.Nm
-operations and locks.
+.El
+.Pp
+The
+.Fn NDINIT_AT
+macro is similar to
+.Fn NDINIT ,
+but takes one extra argument:
+.Bl -tag -width ".Fa segflg"
+.It Fa dirfd
+File descriptor referencing a directory, or the special value
+.Dv AT_FDCWD
+meaning the calling thread's current working directory.
+Lookups will be performed relative to this directory.
+.El
+.Pp
+The
+.Fn NDFREE_PNBUF
+macro is used to free the pathname buffer.
+It must be called exactly once for each successful
+.Fn namei
+call.
+It takes the following argument:
+.Bl -tag -width ".Fa segflg"
+.It Fa ndp
+A pointer to a
+.Vt "struct nameidata"
+that was used in a successful
+.Fn namei
+call.
.El
.Sh NAMEI OPERATION FLAGS
The
@@ -203,17 +234,6 @@ This flag is not looked for by the actual code, which looks for
.Dv NOFOLLOW
is used to indicate to the source code reader that symlinks
are intentionally not followed.
-.It Dv SAVENAME
-Do not free the pathname buffer at the end of the
-.Fn namei
-invocation; instead, free it later in
-.Fn NDFREE
-so that the caller may access the pathname buffer.
-See below for details.
-.It Dv SAVESTART
-Retain an additional reference to the parent directory; do not free
-the pathname buffer.
-See below for details.
.El
.Sh ALLOCATED ELEMENTS
The
@@ -307,7 +327,8 @@ An attempt is made to modify a file or directory on a read-only file system.
.Xr VFS 9 ,
.Xr vnode 9 ,
.Xr vput 9 ,
-.Xr vref 9
+.Xr vref 9 ,
+.Xr vrele 9
.Sh AUTHORS
.An -nosplit
This manual page was written by