*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> namei (9)              



NAME    [Toc]    [Back]

     namei, lookup, relookup, NDINIT - pathname lookup

SYNOPSIS    [Toc]    [Back]

     #include <sys/param.h>
     #include <sys/namei.h>

     namei(struct nameidata *ndp);

     lookup(struct nameidata *ndp);

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

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

DESCRIPTION    [Toc]    [Back]

     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) interface
 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
             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 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  VOP_LOOKUP(9)
for more information.
   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

     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
           HASBUF         caller  has  allocated  pathname buffer
           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
           ISWHITEOUT    found whiteout
           DOWHITEOUT    do whiteouts
           REQUIREDIR    must be a directory
           PDIRUNLOCK    vfs_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
     is  set only by the callers of namei().  It implies SAVENAME
plus the addition
 of saving the parent directory that contains the name
     ni_startdir.   It  allows repeated calls to lookup() for the
name being
     sought.  The caller is responsible for releasing the  buffer
and for invoking
 vrele() on ni_startdir.

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

FUNCTIONS    [Toc]    [Back]

              Convert a pathname into a pointer to a  locked  inode.  The pathname
 is specified by ndp->ni_dirp and is of length
              ndp->ni_pathlen.   The  ndp->segflg  flags  defines
whether the name
              in ndp->ni_dirp  is  an  address  in  kernel  space
              an  address  in  user  space  (UIO_USERSPACE).  The
locked vnode for
              the  pathname  is  referenced   and   returned   in

              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 translation
 process.  Symbolic links are always followed
for all other
 pathname components other than the last.

              Search for a pathname.  This is a very central  and
rather complicated

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

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

              If  ndp->ci_cnd.cn_flags  has  LOCKPARENT  set, the
parent directory
              is returned locked in ndp->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
              ndp->ni_vp, otherwise it is returned unlocked.

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

     NDINIT(ndp, op, flags, segflg, namep, p)
              Initialise  a nameidata structure pointed to by ndp
for use by
              the namei interface.  It saves having to deal  with
the componentname
  structure  inside ndp.  The operation and
flags are
              specified by op and flags respectively.  These  are
the values to
              which           ndp->ni_cnd.cn_nameiop          and
ndp->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  argument  namep  is  a
pointer to the
              pathname  that  ndp->ni_dirp is set to and p is the
calling process.

CODE REFERENCES    [Toc]    [Back]

     The name lookup subsystem is implemented within the file

SEE ALSO    [Toc]    [Back]

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

BUGS    [Toc]    [Back]

     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
     which was historically designed as a tightly coupled module.

OpenBSD     3.6                        October      13,      2001
[ Back ]
 Similar pages
Name OS Title
VOP_LOOKUP FreeBSD lookup a component of a pathname
NDFREE FreeBSD pathname translation and lookup operations
namei FreeBSD pathname translation and lookup operations
NDINIT FreeBSD pathname translation and lookup operations
vm_page_lookup FreeBSD lookup a vm page
host HP-UX DNS lookup utility
dig Linux DNS lookup utility
namecache NetBSD name lookup cache
host OpenBSD DNS lookup utility
host Linux DNS lookup utility
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service