unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

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

NAME
     namei, vfs_lookup, vfs_relookup, NDINIT -- pathname lookup

SYNOPSIS
     #include <&lt;sys/param.h>&gt;
     #include <&lt;sys/namei.h>&gt;

     int
     namei(struct nameidata *ndp);

     int
     vfs_lookup(struct nameidata *ndp);

     int
     vfs_relookup(struct vnode *dvp, struct vnode **vpp,
         struct componentname *cnp);

     void
     NDINIT(struct nameidata *ndp, u_long op, u_long flags,
         enum uio_seg segflg, const char *namep, struct proc *p);

     void
     NDINITAT(struct nameidata *ndp, u_long op, u_long flags,
         enum uio_seg segflg, int dirfd, const char *namep, struct proc *p);

DESCRIPTION
     The namei() function is used to convert pathnames to file system vnodes.
     The name of the function 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.

     The arguments passed to the functions are encapsulated in the nameidata
     structure.  It has the following structure:

     struct nameidata {
             /*
              * Arguments to namei/lookup.
              */
             const char *ni_dirp;            /* pathname pointer */
             int     ni_dirfd;               /* AT_FDCWD or fd of base of */
                                             /* relative paths */
             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 ni_cnd;
     };

     The namei() function 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 VOP_LOOKUP(9) for more
     information.  The details of the componentname structure are not abso-
     lutely necessary since the members are initialised by the helper macros
     NDINIT() and NDINITAT().  It is useful to know the operations and flags
     as specified in VOP_LOOKUP(9).

     The namei() function overloads ni_cnd.cn_flags with some additional
     flags.  These flags should be specific to namei() and ignored by vnode
     operations.  However, due to the historic close relationship between
     namei() 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
           HASBUF        caller has allocated pathname buffer ni_cnd.cn_pnbuf
           SAVENAME      save pathname buffer
           SAVESTART     save starting directory
           ISDOTDOT      current pathname component is ..
           MAKEENTRY     add entry to the name cache
           ISLASTCN      this is last component of pathname
           ISSYMLINK     symlink needs interpretation
           REQUIREDIR    must be a directory
           STRIPSLASHES  strip trailing slashes from the pathname
           PDIRUNLOCK    VOP_LOOKUP() unlocked parent dir

     If the caller of namei() sets the SAVENAME flag, then it must free the
     buffer.  If VOP_LOOKUP() sets the flag, then the buffer must be freed by
     either the commit routine or the VOP_ABORT() routine.  The SAVESTART flag
     is set only by the callers of namei().  It implies SAVENAME plus the
     addition of saving the parent directory that contains the name in
     ni_startdir.  It allows repeated calls to vfs_lookup() for the name being
     sought.  The caller is responsible for releasing the buffer and for
     invoking vrele() on ni_startdir.

     All access to namei(), vfs_lookup(), and vfs_relookup() must be in
     process context.  Pathname lookups cannot be done in interrupt context.

FUNCTIONS
     namei(ndp)
              Convert a pathname into a pointer to a vnode.  The pathname is
              specified by ndp-&gt;ni_dirp and is of length ndp-&gt;ni_pathlen.  The
              ndp-&gt;segflg flags defines whether the name in ndp-&gt;ni_dirp is an
              address in kernel space (UIO_SYSSPACE) or an address in user
              space (UIO_USERSPACE).  The vnode for the pathname is referenced
              and returned in ndp-&gt;ni_vp.

              If ndp-&gt;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.

              If the LOCKLEAF flag is set, a locked vnode is returned.

     vfs_lookup(ndp)
              Search for a pathname.  This is a very central and rather com-
              plicated routine.

              The pathname is specified by ndp-&gt;ni_dirp and is of length
              ndp-&gt;ni_pathlen.  The starting directory is taken from
              ndp-&gt;ni_startdir.  The pathname is descended until done, or a
              symbolic link is encountered.

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

              If ndp-&gt;ci_cnd.cn_flags has LOCKPARENT set, the parent directory
              is returned locked in ndp-&gt;ni_dvp.  If WANTPARENT is set, the
              parent directory is returned unlocked.  Otherwise the parent
              directory is not returned.  If the target of the pathname exists
              and LOCKLEAF is set, the target is returned locked in
              ndp-&gt;ni_vp, otherwise it is returned unlocked.

     vfs_relookup(dvp, vpp, cnp)
              Reacquire a path name component in a directory.  This is a
              quicker way to lookup a pathname component when the parent
              directory is known.  The unlocked parent directory vnode is
              specified by dvp and the pathname component by cnp.  The vnode
              of the pathname is returned in the address specified by vpp.

     NDINITAT(ndp, op, flags, segflg, dirfd, namep, p)
              Initialise a nameidata structure pointed to by ndp for use by
              the namei interfaces.  It saves having to deal with the compo-
              nentname structure inside ndp.  The operation and flags are
              specified by op and flags respectively.  These are the values to
              which ndp-&gt;ni_cnd.cn_nameiop and 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 segflg.  The directory from which relative path-
              names will be looked up is specified by dirfd, with AT_FDCWD
              specifying use of the current working directory of process p.
              The argument namep is a pointer to the pathname that
              ndp-&gt;ni_dirp is set to and p is the calling process.

     NDINIT(ndp, op, flags, segflg, namep, p)
              Same as NDINITAT(ndp, op, flags, segflg, AT_FDCWD, namep, p).

CODE REFERENCES
     The name lookup subsystem is implemented within the file
     sys/kern/vfs_lookup.c.

SEE ALSO
     intro(9), vfs(9), vnode(9), VOP_LOOKUP(9)

BUGS
     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.

BSD                              June 4, 2013                              BSD