Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Gregory McGarry.
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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``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 FOUNDATION OR CONTRIBUTORS
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.
.Dd June 29, 2009 .Dt NAMEI 9 .Os .Sh NAME .Nm namei , .Nm lookup_for_nfsd , .Nm lookup_for_nfsd_index , .Nm relookup , .Nm NDINIT , .Nm namei_simple_kernel , .Nm namei_simple_user .Nd pathname lookup .Sh SYNOPSIS n sys/namei.h n sys/uio.h n sys/vnode.h .Ft int .Fn namei "struct nameidata *ndp" .Ft int .Fn lookup_for_nfsd "struct nameidata *ndp" .Ft int .Fn lookup_for_nfsd_index "struct nameidata *ndp" .Ft int .Fn relookup "struct vnode *dvp" "struct vnode **vpp" \ "struct componentname *cnp" .Ft void .Fn NDINIT "struct nameidata *ndp" "u_long op" "u_long flags" \ "enum uio_seg segflg" "const char *namep" .Ft int .Fn namei_simple_kernel "const char *path" "namei_simple_flags_t sflags" \ "struct vnode **ret" .Ft int .Fn namei_simple_user "const char *path" "namei_simple_flags_t sflags" \ "struct vnode **ret" .Sh DESCRIPTION The .Nm interface is used to convert pathnames to file system vnodes. The name of the interface is actually a contraction of the words .Em name and .Em inode for name-to-inode conversion, in the days before the .Xr vfs 9 interface was implemented.
p Except for the simple forms, the arguments passed to the functions are encapsulated in the .Em nameidata structure. It has the following structure: d -literal struct nameidata { /* * Arguments to namei/lookup. */ const char *ni_dirp; /* pathname pointer */ enum uio_seg ni_segflg; /* location of pathname */ /* * Arguments to lookup. */ struct vnode *ni_startdir; /* starting directory */ struct vnode *ni_rootdir; /* logical root directory */ /* * Results: returned from/manipulated by lookup */ struct vnode *ni_vp; /* vnode of result */ struct vnode *ni_dvp; /* vnode of intermediate dir */ /* * Shared between namei and lookup/commit routines. */ size_t ni_pathlen; /* remaining chars in path */ const char *ni_next; /* next location in pathname */ u_long ni_loopcnt; /* count of symlinks encountered */ /* * Lookup parameters */ struct componentname { /* * Arguments to lookup. */ u_long cn_nameiop; /* namei operation */ u_long cn_flags; /* flags to namei */ kauth_cred_t cn_cred; /* credentials */ /* * Shared between lookup and commit routines. */ char *cn_pnbuf; /* pathname buffer */ const char *cn_nameptr; /* pointer to looked up name */ long cn_namelen; /* length of looked up component */ u_long cn_hash; /* hash value of looked up name */ long cn_consume; /* chars to consume in lookup() */ } ni_cnd; }; .Ed
p The .Nm interface accesses vnode operations by passing arguments in the partially initialised .Em componentname structure .Em ni_cnd . This structure describes the subset of information from the nameidata structure that is passed through to the vnode operations. See .Xr vnodeops 9 for more information. The details of the componentname structure are not absolutely necessary since the members are initialised by the helper macro .Fn NDINIT . It is useful to know the operations and flags as specified in .Xr vnodeops 9 .
p The .Nm interface overloads .Em ni_cnd.cn_flags with some additional flags. These flags should be specific to the .Nm interface and ignored by vnode operations. However, due to the historic close relationship between the .Nm interface and the vnode operations, these flags are sometimes used (and set) by vnode operations, particularly .Fn VOP_LOOKUP . The additional flags are:
p l -tag -offset indent -width NOCROSSMOUNT -compact t Dv NOCROSSMOUNT do not cross mount points t Dv RDONLY lookup with read-only semantics t Dv HASBUF caller has allocated pathname buffer .Em ni_cnd.cn_pnbuf t Dv SAVENAME save pathname buffer t Dv SAVESTART save starting directory t Dv ISDOTDOT current pathname component is .. t Dv MAKEENTRY add entry to the name cache t Dv ISLASTCN this is last component of pathname t Dv ISSYMLINK symlink needs interpretation t Dv ISWHITEOUT found whiteout t Dv DOWHITEOUT do whiteouts t Dv REQUIREDIR must be a directory t Dv CREATEDIR trailing slashes are ok t Dv PARAMASK mask of parameter descriptors .El
p If the caller of .Fn namei sets the SAVENAME flag, then it must free the buffer. If .Fn VOP_LOOKUP sets the flag, then the buffer must be freed by either the commit routine or the .Fn VOP_ABORT routine. The .Dv SAVESTART flag is set only by the callers of .Fn namei . It implies .Dv SAVENAME plus the addition of saving the parent directory that contains the name in .Em ni_startdir . It allows repeated calls to .Fn lookup for the name being sought. The caller is responsible for releasing the buffer and for invoking .Fn vrele on .Em ni_startdir .
p All access to the .Nm interface must be in process context. Pathname lookups cannot be done in interrupt context. .Sh FUNCTIONS l -tag -width compact t Fn namei "ndp" Convert a pathname into a pointer to a vnode. The pathname is specified by .Em ndp-\*[Gt]ni_dirp and is of length .Em ndp-\*[Gt]ni_pathlen . The .Em ndp-\*[Gt]segflg flags defines whether the name in .Em ndp-\*[Gt]ni_dirp is an address in kernel space
q Dv UIO_SYSSPACE or an address in user space
q Dv UIO_USERSPACE .
p The vnode for the pathname is returned in .Em ndp-\*[Gt]ni_vp . The parent directory is returned locked in .Em ndp-\*[Gt]ni_dvp iff .Dv LOCKPARENT is specified.
p If .Em ndp-\*[Gt]ni_cnd.cn_flags has the .Dv FOLLOW flag set then symbolic links are followed when they occur at the end of the name translation process. Symbolic links are always followed for all other pathname components other than the last.
p Historically .Nm had a sub-function called .Fn lookup . This function processed a pathname until either running out of material or encountering a symbolic link. .Nm worked by first setting up the start directory .Em ndp-\*[Gt]ni_startdir and then calling .Fn lookup repeatedly.
p The semantics of .Nm are altered by the operation specified by .Em ndp-\*[Gt]ni_cnd.cn_nameiop . When .Dv CREATE , .Dv RENAME , or .Dv DELETE is specified, information usable in creating, renaming, or deleting a directory entry may be calculated.
p If the target of the pathname exists and LOCKLEAF is set, the target is returned locked in .Em ndp-\*[Gt]ni_vp , otherwise it is returned unlocked.
p As of this writing the internal function .Fn do_lookup is comparable to the historic .Fn lookup but this code is slated for refactoring. t Fn lookup_for_nfsd "ndp" This is a private entry point into .Nm used by the NFS server code. Its semantics are similar to the historic .Fn lookup function described above. It should not be used by new code. t Fn lookup_for_nfsd_index "ndp" This is a (second) private entry point into .Nm used by the NFS server code. Its semantics are similar to the historic .Fn lookup function described above. It should not be used by new code. (For now it differs from the preceding private entry point in that it has a different call site with a different context and different custom initialization of what ought to be private namei state.) t Fn relookup "dvp" "vpp" "cnp" Reacquire a path name component is a directory. This is a quicker way to lookup a pathname component when the parent directory is known. The locked parent directory vnode is specified by .Fa dvp and the pathname component by .Fa cnp . The vnode of the pathname is returned in the address specified by .Fa vpp . t Fn NDINIT "ndp" "op" "flags" "segflg" "namep" Initialise a nameidata structure pointed to by .Fa ndp for use by the .Nm interface. It saves having to deal with the componentname structure inside .Fa ndp . The operation and flags are specified by .Fa op and .Fa flags respectively. These are the values to which .Em ndp-\*[Gt]ni_cnd.cn_nameiop and .Em ndp-\*[Gt]ni_cnd.cn_flags are respectively set. The segment flags which defines whether the pathname is in kernel address space or user address space is specified by .Fa segflag . The argument .Fa namep is a pointer to the pathname that .Em ndp-\*[Gt]ni_dirp is set to.
p This routine stores the credentials of the calling thread .Va ( curlwp ) in .Fa ndp . In the rare case that another set of credentials is required for the namei operation, .Em ndp-\*[Gt]ni_cnd.cn_cred must be set manually. t Fn namei_simple_kernel "path" "sflags" "ret" Look up the path .Fa path and translate it to a vnode, returned in .Fa ret . The .Fa path argument must be a kernel
q Dv UIO_SYSSPACE pointer. The .Fa sflags argument chooses the precise behavior. It may be set to one of the following symbols: l -tag -offset indent -width NSM_NOFOLLOW_TRYEMULROOT -compact t Dv NSM_NOFOLLOW_NOEMULROOT t Dv NSM_NOFOLLOW_TRYEMULROOT t Dv NSM_FOLLOW_NOEMULROOT t Dv NSM_FOLLOW_TRYEMULROOT .El These select (or not) the .Dv FOLLOW/NOFOLLOW and .Dv TRYEMULROOT flags. Other flags are not available through this interface, which is nonetheless sufficient for more than half the .Fn namei usage in the kernel. Note that the encoding of .Fa sflags has deliberately been arranged to be type-incompatible with anything else. This prevents various possible accidents while the .Fn namei interface is being rototilled. t Fn namei_simple_user "path" "sflags" "ret" This function is the same as .Fn namei_simple_kernel except that the .Fa path argument shall be a user pointer
q Dv UIO_USERSPACE rather than a kernel pointer. .El .Sh CODE REFERENCES This section describes places within the .Nx source tree where actual code implementing or using the name lookup subsystem can be found. All pathnames are relative to
p The name lookup subsystem is implemented within the file
a sys/kern/vfs_lookup.c . .Sh SEE ALSO .Xr intro 9 , .Xr namecache 9 , .Xr vfs 9 , .Xr vnode 9 , .Xr vnodeops 9 .Sh BUGS It is unfortunate that much of the .Nm interface makes assumptions on the underlying vnode operations. These assumptions are an artefact of the introduction of the vfs interface to split a file system interface which was historically designed as a tightly coupled module.
Indexes created Wed Oct 22 13:09:56 GMT 2025