NAMEI(9)               NetBSD Kernel Developer's Manual               NAMEI(9)

     namei, NDINIT, NDAT, namei_simple_kernel, namei_simple_user relookup,
     lookup_for_nfsd, lookup_for_nfsd_index, -- pathname lookup

     #include <sys/namei.h>
     #include <sys/uio.h>
     #include <sys/vnode.h>

     NDINIT(struct nameidata *ndp, u_long op, u_long flags,
         struct pathbuf *pathbuf);

     NDAT(struct nameidata *ndp, struct vnode *dvp);

     namei(struct nameidata *ndp);

     namei_simple_kernel(const char *path, namei_simple_flags_t sflags,
         struct vnode **ret);

     namei_simple_user(const char *path, namei_simple_flags_t sflags,
         struct vnode **ret);

     relookup(struct vnode *dvp, struct vnode **vpp,
         struct componentname *cnp);

     lookup_for_nfsd(struct nameidata *ndp, struct vnode *startdir,
         int neverfollow);

     lookup_for_nfsd_index(struct nameidata *ndp);

     The namei interface is used to convert pathnames to file system vnodes.
     The name of the interface is actually a contraction of the words name and
     inode for name-to-inode conversion, in the days before the vfs(9) inter-
     face was implemented.

     Except for the simple forms, the arguments passed to the functions are
     encapsulated in the nameidata structure.  The public interface to this
     structure is as follows.
     It contains a member ni_erootdir that may be set to the emulation root
     directory before the call if the EMULROOTSET flag is also set and
     TRYEMULROOT is in effect.  This is only necessary (or allowed) if the
     emulation root is not yet set in the current process.
     It contains a member ni_vp that upon successful return contains the
     result vnode.
     It contains a member ni_dvp that upon successful return contains the
     vnode of the directory containing the result vnode or NULL.  If the
     LOCKPARENT flag is set, the containing vnode is returned; otherwise this
     field is left set to NULL.
     It contains a member ni_cnd that is a componentname structure (described
     in just a moment).  This may be used by callers to pass to certain vnode
     operations that operate on pathnames.

   The other fields in the structure should not be examined or altered
   directly.  Note that the nfs(4) code misuses the nameidata structure and
   currently has an incestuous relationship with the namei code.  This is
   gradually being cleaned up.  Other code should initialize the nameidata
   structure with the NDINIT() macro and perhaps also the NDAT() macro.

   The componentname structure has the following layout:

   struct componentname {
            * Arguments to VOP_LOOKUP and directory VOP routines.
           uint32_t        cn_nameiop;     /* namei operation */
           uint32_t        cn_flags;       /* flags to namei */
           kauth_cred_t    cn_cred;        /* credentials */
           const char      *cn_nameptr;    /* pointer to looked up name */
           size_t          cn_namelen;     /* length of looked up comp */
            * Side result from VOP_LOOKUP.
           size_t          cn_consume;     /* chars to consume in lookup */
   This structure contains the information about a single directory component
   name, along with certain other information required by vnode operations.
   See vnodeops(9) for more information about these vnode operations.

   The members:
         cn_nameiop    The type of operation in progress; indicates the basic
                       operating mode of namei.  May be one of LOOKUP, CREATE,
                       DELETE, or RENAME.  These modes are described below.
         cn_flags      Additional flags affecting the operation of namei.
                       These are described below as well.
         cn_cred       The credentials to use for the lookup or other opera-
                       tion the componentname is passed to.  This may match
                       the credentials of the current process or it may not,
                       depending on where the original operation request came
                       from and how it has been routed.
         cn_nameptr    The name of this directory component, followed by the
                       rest of the path being looked up.
         cn_namelen    The length of the name of this directory component.
                       The name is not in general null terminated, although
                       the complete string (the full remaining path) always
         cn_consume    This field starts at zero; it may be set to a larger
                       value by implementations of VOP_LOOKUP(9) to indicate
                       how many more characters beyond cn_namelen are being
                       consumed.  New uses of this feature are discouraged and
                       should be discussed.

 Operating modes
   The LOOKUP mode is the baseline behavior, for all ordinary lookups that
   simply return a vnode.  In this mode, if the requested object does not
   exist, ENOENT is returned.

   The CREATE mode is used when doing the lookup for operations that create
   names in the file system namespace, such as mkdir(2).  In this mode, if the
   requested name already exists, EEXIST is returned.  Otherwise if the
   requested name does not exist, the lookup succeeds and the returned vnode
   ni_vp is set to NULL.

   The DELETE mode is used when doing the lookup for operations that remove
   names from the file system namespace, such as rmdir(2); and the RENAME mode
   is used when doing (one of the) lookups for rename(2).

   The mode may affect both the VOP_LOOKUP(9) implementation of the file sys-
   tem involved and the internal operation of namei, such as interactions with
   the namecache(9).  In ffs(4), for example, the VOP_LOOKUP(9) implementation
   reacts to CREATE, DELETE, and RENAME by computing additional information
   needed to operate on directory entries.  This information is consumed by
   the vnode operations expected to be called subsequently.  If one of these
   modes is used (and owing to failure or whatever other circumstances) the
   eventual vnode operation is not called, VOP_ABORTOP(9) should be used to
   ensure the state involved is cleaned up correctly.

   The following flags may appear.  Some are set by namei; some are set by
   VOP_LOOKUP(9); some are set by the caller in the flags argument of
   NDINIT().  Not all possible combinations are sensible or legal.
         FOLLOW        Follow symbolic links encountered as the last path com-
                       ponent.  Used by operations that do not address sym-
                       bolic links directly, e.g.  stat(2).  Does not affect
                       symbolic links found in the middle of a path.  Set by
                       the caller.  Used internally.
         NOFOLLOW      Do not follow symbolic links encountered as the last
                       path component.  Used by operations that address sym-
                       bolic links explicitly, such as lstat(2).  Set by the
                       caller.  Used internally.  Note: the value of NOFOLLOW
                       is 0; it exists on the grounds that every namei call
                       should explicitly choose either FOLLOW or NOFOLLOW.
         LOCKLEAF      Upon successful completion, the resultant named vnode
                       ni_vp is to be left locked.  (Otherwise, the vnode is
                       unlocked before namei returns.)  Set by the caller;
                       used internally.
         LOCKPARENT    Upon successful completion, the parent directory con-
                       taining the named vnode is left locked and returned in
                       ni_dvp as described above.  Otherwise, ni_dvp is set to
                       NULL.  Set by the caller; used internally.
         TRYEMULROOT   If set, the path is looked up in emulation root of the
                       current process first.  If that fails, the system root
                       is used.  Set by the caller; used internally.
         EMULROOTSET   As described above, indicates that the caller has set
                       ni_erootdir prior to calling namei.  This is only use-
                       ful or permitted when the emulation in the current
                       process is partway through being set up.  Set by the
                       caller; used internally.
         NOCHROOT      Bypass normal chroot(8) handling for absolute paths.
                       Set by the caller and used internally.
         NOCROSSMOUNT  Do not cross mount points.  Set by the caller and used
         RDONLY        Enforce read-only behavior.  Set by the caller and used
                       internally.  May also be used by file-system-level
                       vnode functions.
         DOWHITEOUT    Allow whiteouts to be seen as objects instead of func-
                       tioning as ``nothing there''.  Set by the caller; used
                       by vnode functions.
         ISWHITEOUT    The current path component is a whiteout.  Set by
                       VOP_LOOKUP(9) implementations and consumed by other
                       vnode functions and the namecache(9).
         ISDOTDOT      The current pathname component is ``..''.  Set inter-
                       nally; used by vnode operations.
         ISLASTCN      The current path component is the last component found
                       in the pathname.  Set internally; used by vnode func-
         REQUIREDIR    The current object to be looked up must be a directory.
                       Set and used internally; any external references are
         CREATEDIR     Accept slashes after a component name that does not
                       exist.  This only makes sense in CREATE mode and when
                       creating a directory.  Set by the caller and used
         NOCACHE       The name looked up should not be entered in the
                       namecache(9).  Set and used internally.  (Currently
                       sometimes set by callers, but most likely this is
                       improper/incorrect.)  May also be used by file-system-
                       level vnode functions.
         MAKEENTRY     The current pathname component should be added to the
                       namecache(9).  Set and used internally.  Also abused by
                       the nfs(4) code.

   The following additional historic flags have been removed from NetBSD and
   should be handled as follows if porting code from elsewhere:
         INRENAME      Part of a misbegotten and incorrect locking scheme.
                       Any file-system-level code using this is presumptively
                       incorrect.  File systems should use the genfs_rename(9)
                       interface to handle locking in VOP_RENAME().
         INRELOOKUP    Used at one point for signaling to puffs(3) to work
                       around a protocol deficiency that was later rectified.
         ISSYMLINK     Useless internal state.
         SAVESTART     Unclean setting affect vnode reference counting.  Now
                       effectively never in effect.  Any code referring to
                       this is suspect.
         SAVENAME      Unclean setting relating to responsibility for freeing
                       pathname buffers in the days before the pathbuf struc-
                       ture.  Now effectively always in effect; the caller of
                       namei owns the pathbuf structure and is always respon-
                       sible for destroying it.
         HASBUF        Related to SAVENAME.  Any uses can be replaced with
   All access to the namei interface must be in process context.  Pathname
   lookups cannot be done in interrupt context.

     NDINIT(ndp, op, flags, pathbuf)
              Initialise a nameidata structure pointed to by ndp for use by
              the namei interface.  The operating mode and flags (as docu-
              mented above) are specified by op and flags respectively.  The
              pathname is passed as a pathbuf structure, which should be ini-
              tialized using one of the pathbuf(9) operations.  Destroying the
              pathbuf is the responsibility of the caller; this must not be
              done until the caller is finished with all of the namei results
              and all of the nameidata contents except for the result vnode.

              This routine stores the credentials of the calling thread
              (curlwp) in ndp.  NDINIT() sets the credentials using
              kauth_cred_get(9).  In the rare case that another set of creden-
              tials is required for the namei operation, ndp->ni_cnd.cn_cred
              must be set manually after NDINIT().

     NDAT(ndp, dvp)
              This macro is used after NDINIT() to set the starting directory.
              This supersedes the current process's current working directory
              as the initial point of departure for looking up relative paths.
              This mechanism is used by openat(2) and related calls.

              Convert a pathname into a pointer to a vnode.  The nameidata
              structure pointed to by ndp should be initialized with the
              NDINIT() macro, and perhaps also the NDAT() macro.  Direct ini-
              tialization of members of struct nameidata is not supported and
              may (will) break silently in the future.

              The vnode for the pathname is returned in ndp->ni_vp.  The par-
              ent directory is returned locked in ndp->ni_dvp iff LOCKPARENT
              is specified.

              Any or all of the flags documented above as set by the caller
              can be enabled by passing them (OR'd together) as the flags
              argument of NDINIT().  As discussed above every such call should
              explicitly contain either FOLLOW or NOFOLLOW to control the
              behavior regarding final symbolic links.

     namei_simple_kernel(path, sflags, ret)
              Look up the path path and translate it to a vnode, returned in
              ret.  The path argument must be a kernel (UIO_SYSSPACE) pointer.
              The sflags argument chooses the precise behavior.  It may be set
              to one of the following symbols:
              These select (or not) the FOLLOW/NOFOLLOW and TRYEMULROOT flags.
              Other flags are not available through this interface, which is
              nonetheless sufficient for more than half the namei() usage in
              the kernel.  Note that the encoding of sflags has deliberately
              been arranged to be type-incompatible with anything else.  This
              prevents various possible accidents while the namei() interface
              is being rototilled.

     namei_simple_user(path, sflags, ret)
              This function is the same as namei_simple_kernel() except that
              the path argument shall be a user pointer (UIO_USERSPACE) rather
              than a kernel pointer.

     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 speci-
              fied by dvp and the pathname component by cnp.  The vnode of the
              pathname is returned in the address specified by vpp.  Note that
              one may only use relookup() to repeat a lookup of a final path
              component previously done by namei, and one must use the same
              componentname structure that call produced.  Otherwise the
              behavior is undefined and likely adverse.

     lookup_for_nfsd(ndp, startdir, neverfollow)
              This is a private entry point into namei used by the NFS server
              code.  It looks up a path starting from startdir.  If
              neverfollow is set, any symbolic link (not just at the end of
              the path) will cause an error.  Otherwise, it follows symlinks
              normally.  It should not be used by new code.

              This is a (second) private entry point into namei used by the
              NFS server code.  It looks up a single path component.  It
              should not be used by new code.

     The nameidata structure has the following layout:

     struct nameidata {
              * Arguments to namei.
             struct vnode *ni_atdir;         /* startup dir, cwd if null */
             struct pathbuf *ni_pathbuf;     /* pathname container */
             char *ni_pnbuf;                 /* extra pathname buffer ref (XXX) */
              * Internal starting state. (But see notes.)
             struct  vnode *ni_rootdir;      /* logical root directory */
             struct  vnode *ni_erootdir;     /* emulation root directory */
              * Results from namei.
             struct  vnode *ni_vp;           /* vnode of result */
             struct  vnode *ni_dvp;          /* vnode of intermediate directory */
              * Internal current state.
             size_t          ni_pathlen;     /* remaining chars in path */
             const char      *ni_next;       /* next location in pathname */
             unsigned int    ni_loopcnt;     /* count of symlinks encountered */
              * Lookup parameters: this structure describes the subset of
              * information from the nameidata structure that is passed
              * through the VOP interface.
             struct componentname ni_cnd;

     These fields are:
           ni_atdir      The directory to use for the starting point of rela-
                         tive paths.  If null, the current process's current
                         directory is used.  This is initialized to NULL by
                         NDINIT() and set by NDAT().
           ni_pathbuf    The abstract path buffer in use, passed as an argu-
                         ment to NDINIT().  The name pointers that appear
                         elsewhere, such as in the componentname structure,
                         point into this buffer.  It is owned by the caller
                         and must not be destroyed until all namei operations
                         are complete.  See pathbuf(9).
           ni_pnbuf      This is the name pointer used during namei.  It
                         points into ni_pathbuf.  It is not initialized until
                         entry into namei.
           ni_rootdir    The root directory to use as the starting point for
                         absolute paths.  This is retrieved from the current
                         process's current root directory when namei starts
                         up.  It is not initialized by NDINIT().
           ni_erootdir   The root directory to use as the emulation root, for
                         processes running in emulation.  This is retrieved
                         from the current process's emulation root directory
                         when namei starts up and not initialized by NDINIT().
                         As described elsewhere, it may be set by the caller
                         if the EMULROOTSET flag is used, but this should only
                         be done when the current process's emulation root
                         directory is not yet initialized.  (And ideally in
                         the future things would be tidied so that this is not
           ni_dvp        Returned vnodes, as described above.  These only con-
                         tain valid values if namei returns successfully.
           ni_pathlen    The length of the full current remaining path string
                         in ni_pnbuf.  This is not initialized by NDINIT() and
                         is used only internally.
           ni_next       The remaining part of the path, after the current
                         component found in the componentname structure.  This
                         is not initialized by NDINIT() and is used only
           ni_loopcnt    The number of symbolic links encountered (and tra-
                         versed) so far.  If this exceeds a limit, namei fails
                         with ELOOP.  This is not initialized by NDINIT() and
                         is used only internally.
           ni_cnd        The componentname structure holding the current
                         directory component, and also the mode, flags, and
                         credentials.  The mode, flags, and credentials are
                         initialized by NDINIT(); the rest is not initialized
                         until namei runs.

     There is also a namei_state structure that is hidden within vfs_lookup.c.
     This contains the following additional state:
           docache        A flag indicating whether to cache the last pathname
           rdonly         The read-only state, initialized from the RDONLY
           slashes        The number of trailing slashes found after the cur-
                          rent pathname component.
           attempt_retry  Set on some error cases (and not others) to indicate
                          that a failure in the emulation root should be fol-
                          lowed by a retry in the real system root.

     The state in namei_state is genuinely private to namei.  Note that much
     of the state in nameidata should also be private, but is currently not
     because it is misused in some fashion by outside code, usually nfs(4).

     The control flow within the namei portions of vfs_lookup.c is as follows.

     namei()           does a complete path lookup by calling namei_init(),
                       namei_tryemulroot(), and namei_cleanup().

     namei_init()      sets up the basic internal state and makes some (pre-
                       condition-type) assertions.

     namei_cleanup()   makes some postcondition-type assertions; it currently
                       does nothing besides this.

                       handles TRYEMULROOT by calling namei_oneroot() once or
                       twice as needed, and attends to making sure the origi-
                       nal pathname is preserved for the second try.

     namei_oneroot()   does a complete path search from a single root direc-
                       tory.  It begins with namei_start(), then calls
                       lookup_once() (and if necessary, namei_follow())
                       repeatedly until done.  It also handles returning the
                       result vnode(s) in the requested state.

     namei_start()     sets up the initial state and locking; it calls

                       initializes the root directory state (both ni_rootdir
                       and ni_erootdir) and picks the starting directory, con-
                       suming the leading slashes of an absolute path and han-
                       dling the magic ``/../'' string for bypassing the emu-
                       lation root.  A different version
                       namei_getstartdir_for_nfsd() is used for lookups coming
                       from nfsd(8) as those are required to have different

     lookup_once()     calls VOP_LOOKUP() for one path component, also han-
                       dling any needed crossing of mount points (either up or
                       down) and coping with locking requirements.

                       is called prior to each lookup_once() call to examine
                       the pathname and find where the next component starts.

     namei_follow()    reads the contents of a symbolic link and updates both
                       the path buffer and the search directory accordingly.

     As a final note be advised that the magic return value associated with
     CREATE mode is different for namei than it is for VOP_LOOKUP().  The lat-
     ter ``fails'' with EJUSTRETURN.  namei translates this into succeeding
     and returning a null vnode.

     The name lookup subsystem is implemented within the file

     intro(9), namecache(9), vfs(9), vnode(9), vnodeops(9)

     There should be no such thing as operating modes.  Only LOOKUP is actu-
     ally needed.  The behavior where removing an object looks it up within
     namei and then calls into the file system (which must look it up again
     internally or cache state from VOP_LOOKUP()) is particularly contorted.

     Most of the flags are equally bogus.

     Most of the contents of the nameidata structure should be private and
     hidden within namei; currently it cannot be because of abuse elsewhere.

     The EMULROOTSET flag is messy.

     There is no good way to support file systems that want to use a more
     elaborate pathname schema than the customary slash-delimited components.

NetBSD 7.0                        May 6, 2016                       NetBSD 7.0

You can also request any man page by name and (optionally) by section:


Use the DEFAULT collection to view manual pages for third-party software.

©1994 Man-cgi 1.15, Panagiotis Christias <>
©1996-2016 Modified for NetBSD by Kimmo Suominen