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

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

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

     namei(struct nameidata *ndp);

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

     lookup_for_nfsd_index(struct nameidata *ndp);

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

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

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

     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);

     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.  It has the following layout:

     struct nameidata {
              * Arguments to namei/lookup.
             struct vnode *ni_atdir;         /* startup dir, cwd if null */
             struct pathbuf *ni_pathbuf;     /* pathname container */
             char *ni_pnbuf;                 /* extra pathname buffer ref (XXX) */
              * Arguments to lookup.
             struct  vnode *ni_rootdir;      /* logical root directory */
             struct  vnode *ni_erootdir;     /* emulation root directory */
              * Results: returned from/manipulated by lookup
             struct  vnode *ni_vp;           /* vnode of result */
             struct  vnode *ni_dvp;          /* vnode of intermediate directory */
              * Shared between namei and lookup/commit routines.
             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;

     The componentname structure has the following layout:

     struct componentname {
              * Arguments to lookup.
             uint32_t        cn_nameiop;     /* namei operation */
             uint32_t        cn_flags;       /* flags to namei */
             kauth_cred_t    cn_cred;        /* credentials */
              * Shared between lookup and commit routines.
             const char      *cn_nameptr;    /* pointer to looked up name */
             size_t          cn_namelen;     /* length of looked up comp */
             size_t          cn_consume;     /* chars to consume in lookup */

     The namei interface accesses vnode operations by passing arguments in the
     partially initialised componentname structure ni_cnd.  This structure
     describes the subset of information from the nameidata structure that is
     passed through to the vnode operations.  See vnodeops(9) for more infor-
     mation.  The details of the componentname structure are not absolutely
     necessary since the members are initialised by the helper macro NDINIT().
     It is useful to know the operations and flags as specified in

     The namei interface overloads ni_cnd.cn_flags with some additional flags.
     These flags should be specific to the namei interface and ignored by
     vnode operations.  However, due to the historic close relationship
     between the namei interface and the vnode operations, these flags are
     sometimes used (and set) by vnode operations, particularly VOP_LOOKUP().
     The additional flags are:

           NOCROSSMOUNT  do not cross mount points
           RDONLY        lookup with read-only semantics
           ISDOTDOT      current pathname component is ..
           MAKEENTRY     add entry to the name cache
           ISLASTCN      this is last component of pathname
           ISWHITEOUT    found whiteout
           DOWHITEOUT    do whiteouts
           REQUIREDIR    must be a directory
           CREATEDIR     trailing slashes are ok
           PARAMASK      mask of parameter descriptors

     All access to the namei interface must be in process context.  Pathname
     lookups cannot be done in interrupt context.

              Convert a pathname into a pointer to a vnode.  The nameidata
              structure pointed to by ndp should be initialized with the
              NDINIT() macro.  Direct initialization of members of struct
              nameidata is not supported and may 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.

              If ndp->ni_cnd.cn_flags has the FOLLOW flag set then symbolic
              links are followed when they occur at the end of the name trans-
              lation process.  Symbolic links are always followed for all
              other pathname components other than the last.

              Historically namei had a sub-function called lookup().  This
              function processed a pathname until either running out of mate-
              rial or encountering a symbolic link.  namei worked by first
              setting up the start directory ndp->ni_startdir and then calling
              lookup() repeatedly.

              The semantics of namei are altered by the operation specified by
              ndp->ni_cnd.cn_nameiop.  When CREATE, RENAME, or DELETE is spec-
              ified, information usable in creating, renaming, or deleting a
              directory entry may be calculated.

              If the target of the pathname exists and LOCKLEAF is set, the
              target is returned locked in ndp->ni_vp, otherwise it is
              returned unlocked.

              As of this writing the internal function do_lookup() is compara-
              ble to the historic lookup() but this code is slated for refac-

     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.  Its semantics are similar to a symlink-following loop
              around the historic lookup() function described above.  It
              should not be used by new code.

              This is a (second) private entry point into namei used by the
              NFS server code.  Its semantics are similar to the historic
              lookup() function described above.  It should not be used by new

     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.

     NDINIT(ndp, op, flags, pathbuf)
              Initialise a nameidata structure pointed to by ndp for use by
              the namei interface.  The operation and flags are specified by
              op and flags respectively.  The pathname is passed as a pathbuf
              structure, which should be initialized using one of the
              pathbuf(9) operations.  Destroying the pathbuf is the responsi-
              bility 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.  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.

              The following fields of ndp are set:

                       is set to op.

                       is set to flags.

                       is set to NULL.

                       is set to pathbuf.

                       is set using kauth_cred_get(9).
              Other fields of struct nameidata are not (normally) initialized
              before namei is called.  Direct assignment of these or other
              fields other than by using NDINIT() or NDAT(), except as specif-
              ically described above, is not supported and may break silently
              in the future.

     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.

     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.

     The name lookup subsystem is implemented within the file

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

     It is unfortunate that much of the namei 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.

NetBSD 7.0                       May 05, 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