feat: Added FreeBSD man pages

1 files changed, 551 insertions, 0 deletions

diff --git a/static/freebsd/man9/namei.9 b/static/freebsd/man9/namei.9
new file mode 100644
index 00000000..d920f4e9
--- /dev/null
+++ b/static/freebsd/man9/namei.9
@@ -0,0 +1,551 @@
+.\"
+.\" Copyright (c) 1998, 1999 Eivind Eklund
+.\" Copyright (c) 2003 Hiten M. Pandya
+.\" Copyright (c) 2005 Robert N. M. Watson
+.\"
+.\" All rights reserved.
+.\"
+.\" This program is free software.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\"
+.\" If you integrate this manpage in another OS, I'd appreciate a note
+.\"	- eivind@FreeBSD.org
+.\"
+.Dd September 30, 2025
+.Dt NAMEI 9
+.Os
+.Sh NAME
+.Nm namei ,
+.Nm NDINIT ,
+.Nm NDINIT_AT ,
+.Nm NDFREE_PNBUF
+.Nd pathname translation and lookup operations
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/fcntl.h
+.In sys/namei.h
+.Ft int
+.Fn namei "struct nameidata *ndp"
+.Ft void
+.Fo NDINIT
+.Fa "struct nameidata *ndp" "enum nameiop op" "u_int64_t flags"
+.Fa "enum uio_seg segflg" "const char *namep"
+.Fc
+.Ft void
+.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
+facility allows the client to perform pathname translation and lookup
+operations.
+The
+.Nm
+functions will increment the reference count for the vnode in question.
+The reference count has to be decremented after use of the vnode, by
+using either
+.Xr vrele 9
+or
+.Xr vput 9 ,
+depending on whether the
+.Dv LOCKLEAF
+flag was specified or not.
+.Pp
+The
+.Fn NDINIT
+macro is used to initialize
+.Nm
+components.
+It takes the following arguments:
+.Bl -tag -width ".Fa segflg"
+.It Fa ndp
+A pointer to the
+.Vt "struct nameidata"
+to initialize.
+.It Fa op
+The operation which
+.Fn namei
+will perform.
+The following operations are valid:
+.Dv LOOKUP , CREATE , DELETE ,
+and
+.Dv RENAME .
+The latter three are just setup for those
+effects; just calling
+.Fn namei
+will not result in
+.Fn VOP_RENAME
+being called.
+.It Fa flags
+Operation flags, described in the next section.
+Several of these can be effective at the same time.
+.It Fa segflg
+UIO segment indicator.
+This indicates if the name of the object is in userspace
+.Pq Dv UIO_USERSPACE
+or in the kernel address space
+.Pq Dv UIO_SYSSPACE .
+.It Fa namep
+Pointer to the component's pathname buffer
+(the file or directory name that will be looked up).
+.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
+.Fn namei
+function takes the following set of
+.Dq "operation flags"
+that influence its operation:
+.Bl -tag -width NC_KEEPPOSENTRY
+.It Dv NC_NOMAKEENTRY
+An alias for
+.Dv NOCACHE .
+.It Dv NC_KEEPPOSENTRY
+Keep the positive-caching entry in cache.
+This flag is typically combined with
+.Dv NOCACHE
+to not cache a new entry,
+but keep existing one, or with
+.Dv MAKEENTRY .
+.It Dv NOCACHE
+Avoid
+.Fn namei
+creating this entry in the namecache if it is not
+already present.
+Normally,
+.Fn namei
+will add entries to the name cache
+if they are not already there.
+.It Dv LOCKLEAF
+Lock vnode on return with
+.Dv LK_EXCLUSIVE
+unless
+.Dv LOCKSHARED
+is also set.
+.Xr VOP_UNLOCK 9
+should be used
+to release the lock (or
+.Xr vput 9
+which is equivalent to calling
+.Xr VOP_UNLOCK 9
+followed by
+.Xr vrele 9 ,
+all in one).
+.It Dv LOCKPARENT
+This flag lets the
+.Fn namei
+function return the parent (directory) vnode,
+.Va ni_dvp
+in locked state, unless it is identical to
+.Va ni_vp ,
+in which case
+.Va ni_dvp
+is not locked per se (but may be locked due to
+.Dv LOCKLEAF ) .
+If a lock is enforced, it should be released using
+.Xr vput 9
+or
+.Xr VOP_UNLOCK 9
+and
+.Xr vrele 9 .
+.It Dv WANTPARENT
+This flag allows the
+.Fn namei
+function to return the parent (directory) vnode in an unlocked state.
+The parent vnode must be released separately by using
+.Xr vrele 9 .
+.It Dv FAILIFEXISTS
+Makes the
+.Nm
+operation fail if the target exists.
+It requires that the
+.Dv LOCKPARENT
+flag is set and
+.Dv LOCKLEAF
+is not.
+.It Dv FOLLOW
+With this flag,
+.Fn namei
+will follow the symbolic link if the last part
+of the path supplied is a symbolic link (i.e., it will return a vnode
+for whatever the link points at, instead for the link itself).
+.It Dv EMPTYPATH
+For
+.Nm
+call initialized with
+.Fn NDINIT_AT ,
+allow the
+.Fa namep
+path to be empty.
+In this case, the
+.Fa dirfd
+file descriptor may reference a file of arbitrary type, not
+necessary a directory, and lookup returns the vnode for this file.
+.It Dv LOCKSHARED
+Lock vnode on return with
+.Dv LK_SHARED ,
+if permitted by the file system that owns the vnode.
+The file system must explicitly permit this by setting
+.Dv MNTK_LOOKUP_SHARED
+in
+.Dv mp->mnt_kern_flag
+during mount and by calling
+.Fn VN_LOCK_ASHARE
+when allocating the vnode.
+If
+.Dv LOCKLEAF
+is specified but shared locking is not permitted, then the vnode will be
+returned with
+.Dv LK_EXCLUSIVE .
+.Xr VOP_UNLOCK 9
+should be used
+to release the lock (or
+.Xr vput 9
+which is equivalent to calling
+.Xr VOP_UNLOCK 9
+followed by
+.Xr vrele 9 ,
+all in one).
+.It Dv NOFOLLOW
+Do not follow symbolic links (pseudo).
+This flag is not looked for by the actual code, which looks for
+.Dv FOLLOW .
+.Dv NOFOLLOW
+is used to indicate to the source code reader that symlinks
+are intentionally not followed.
+.It Dv RBENEATH
+Requires that
+.Nm
+did not cross the
+.Fa dirfd
+directory.
+The flag is used to implement
+.Dv O_RESOLVE_BENEATH
+flag for
+.Xr openat 2 .
+.It Dv NAMEILOOKUP
+The component is embedded in a
+.Nm
+lookup structure, and the
+.Fn vfs_lookup_nameidata
+function can be used to obtain that structure.
+This can be useful in
+.Xr VOP_LOOKUP 9
+implementations which need to obtain extra lookup metadata.
+.El
+.Sh PARAMETERS DESCRIPTORS FLAGS
+These flags are used for several purposes.
+Some of them affects the global
+.Nm
+operation, some provide information for processing of the specific
+path element, for instance, by the
+.Dv VOP_LOOKUP
+implementation of the involved filesystem.
+.Bl -tag -width IGNOREWHITEOUT
+.It Dv RDONLY
+Specifies that the lookup should act as if the final node is located on
+read-only mount.
+The flag is typically used by file servers, e.g. NFS,
+to handle read-only exports.
+.It Dv ISRESTARTED
+The
+.Nm
+was restarted with
+.Fn NDRESTART .
+This is used internally for double-root lookups used by ABI subsystems,
+after the lookup with native root failed.
+The components are reset to the original values, and lookup is repeated
+with different root, once.
+.It Dv IGNOREWHITEOUT
+Ignore whiteouts, e.g. when checking if a directory is empty.
+.It Dv ISWHITEOUT
+The result of lookup is whiteout.
+.It Dv DOWHITEOUT
+Handle whiteouts, the instruction for the
+.Fn VOP_LOOKUP
+filesystem methods.
+.It Dv WILLBEDIR
+The lookup is done for creating a new entry that will be directory.
+It allows the trailing slash in the path string.
+.It Dv ISOPEN
+The caller is the code that opens a file.
+This allows to weaken the lock mode of the return vnode, if the
+mount point indicates extended shared lock support.
+.It Dv NOCROSSMOUNT
+Do not cross mount points during lookup.
+.Pp
+For
+.Dq ..
+lookup leading to mount root, returns the root vnode of
+the mount instead of the covered vnode of the filesystem where
+the mount was placed.
+.Pp
+For other lookups passing over mount, do not jump into the mounted
+filesystem.
+This allows to descend into the file hierarchy otherwise shadowed
+by the mount point.
+.It Dv NOMACCHECK
+Do not perform MAC checks during lookup.
+.It Dv AUDITVNODE1
+Audit the looked up vnode information, use the first slot for audit information.
+.It Dv AUDITVNODE2
+Same as
+.Dv AUDITVNODE1
+but use the second slot.
+.It Dv NOCAPCHECK
+Do not perform capability checks.
+If the calling process is in capability mode, lookup is denied outright.
+.It Dv OPENREAD
+The lookup was for open and file will be opened for read.
+.It Dv OPENWRITE
+The lookup was for open and file will be opened for write.
+.It Dv WANTIOCTLCAPS
+Leave ioctl caps for the caller.
+See the description of
+.Nm
+results.
+.It Dv OPENNAMED
+Opening a named attribute (directory).
+.It Dv NOEXECCHECK
+Do not perform check for allowed execution on the starting directory.
+It is used to implement the POSIX-required semantic for
+.Xr openat 2
+lookups that must use the permissions from time the directory was
+opened, and not when used for lookup.
+.It Dv MAKEENTRY
+Looked-up entry is to be added to name cache.
+.It Dv ISSYMLINK
+Current component is symlink, and it needs the interpretation
+according to the
+.Dv FOLLOW
+or
+.Dv NOFOLLOW
+flags.
+.It Dv ISLASTCN
+This is last component of pathname.
+It is handled specially, many flags augment its processing.
+.It Dv ISDOTDOT
+Current component name is
+.Dq .. .
+Usually implies a need to specially handle the vnode locking
+for instantiation of the target vnode.
+The generic
+.Fn vn_vget_ino_gen
+function and its more specialized variant
+.Fn vn_vget_ino
+might be useful.
+.It Dv TRAILINGSLASH
+Path ended in a slash.
+.It Dv CREATENAMED
+Create a named attribute dir.
+.El
+.Sh ALLOCATED ELEMENTS
+The
+.Vt nameidata
+structure is composed of the following fields:
+.Bl -tag -width ".Va ni_cnd.cn_pnbuf"
+.It Va ni_startdir
+In the normal case, this is either the current directory or the root.
+It is the current directory if the name passed in does not start with
+.Ql /
+and we have not gone through any symlinks with an absolute path, and
+the root otherwise.
+.Pp
+In this case, it is only used by
+.Fn vfs_lookup ,
+and should not be
+considered valid after a call to
+.Fn namei .
+.It Va ni_dvp
+Vnode pointer to directory of the object on which lookup is performed.
+This is available on successful return if
+.Dv LOCKPARENT
+or
+.Dv WANTPARENT
+is set.
+It is locked if
+.Dv LOCKPARENT
+is set.
+.It Va ni_vp
+Vnode pointer to the resulting object,
+.Dv NULL
+otherwise.
+The
+.Va v_usecount
+field of this vnode is incremented.
+If
+.Dv LOCKLEAF
+is set, it is also locked.
+.Pp
+.It Va ni_cnd.cn_pnbuf
+The pathname buffer contains the location of the file or directory
+that will be used by the
+.Nm
+operations.
+It is managed by the
+.Xr uma 9
+zone allocation interface.
+.El
+.Sh RESULTS
+The
+.Vt struct namei
+member
+.Dv ni_resflags
+returns the following flags giving some details of the successful operation:
+.Bl -tag -width NIRES_EMPTYPATH
+.It Dv NIRES_ABS
+The path passed was absolute.
+.It Dv NIRES_STRICTREL
+Restricted lookup result.
+Only relative lookups were done to resolve the path to vnode.
+.It Dv NIRES_EMPTYPATH
+The
+.Dv EMPTYPATH
+flag was provided and used.
+In particular, the passed path was empty.
+.El
+.Pp
+If the
+.Dv WANTIOCTLCAPS
+flag was specified, on return the
+.Va ni_filecaps
+member of the
+.Vt struct namei
+contains the capabilities of the file descriptor used as
+the lookup starting point
+.Pq Va dirfd .
+.Sh RETURN VALUES
+If successful,
+.Fn namei
+will return 0, otherwise it will return an error.
+.Sh FILES
+.Bl -tag -width Pa
+.It Pa src/sys/kern/vfs_lookup.c
+.El
+.Sh EXAMPLES
+Assuming the
+.Dv path
+variable contains a pointer to userspace path string, the following
+example looks up the file named by it, and performs required error
+and resource handling:
+.Bd -literal
+	char *path;
+	struct nameidata nd;
+	int error;
+
+	NDINIT(&nd, LOOKUP, FOLLOW | LOCKLEAF | AUDITVNODE1, UIO_USERSPACE,
+	    path);
+	if ((error = namei(&nd)) != 0)
+		return (error);
+	NDFREE_PNBUF(&nd);
+	... use nd.ni_vp vnode
+.Ed
+.Sh ERRORS
+Errors which
+.Fn namei
+may return:
+.Bl -tag -width Er
+.It Bq Er ENOTDIR
+A component of the specified pathname is not a directory when a directory is
+expected.
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeded 255 characters,
+or an entire pathname exceeded 1023 characters.
+.It Bq Er ENOENT
+A component of the specified pathname does not exist,
+or the pathname is an empty string.
+.It Bq Er EACCES
+An attempt is made to access a file in a way forbidden by its file access
+permissions.
+.It Bq Er ELOOP
+Too many symbolic links were encountered in translating the pathname.
+.It Bq Er EISDIR
+An attempt is made to open a directory with write mode specified.
+.It Bq Er EINVAL
+The last component of the pathname specified for a
+.Dv DELETE
+or
+.Dv RENAME
+operation is
+.Ql \&. .
+.It Bq Er EROFS
+An attempt is made to modify a file or directory on a read-only file system.
+.El
+.Sh SEE ALSO
+.Xr uio 9 ,
+.Xr uma 9 ,
+.Xr VFS 9 ,
+.Xr vnode 9 ,
+.Xr vput 9 ,
+.Xr vref 9 ,
+.Xr vrele 9
+.Sh AUTHORS
+.An -nosplit
+This manual page was written by
+.An Eivind Eklund Aq Mt eivind@FreeBSD.org
+and later significantly revised by
+.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org .
+.Sh BUGS
+The
+.Dv LOCKPARENT
+flag does not always result in the parent vnode being locked.
+This results in complications when the
+.Dv LOCKPARENT
+is used.
+In order to solve this for the cases where both
+.Dv LOCKPARENT
+and
+.Dv LOCKLEAF
+are used, it is necessary to resort to recursive locking.