Home Man
Today's Posts

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for namei (netbsd section 9)

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

     namei, lookup_for_nfsd, lookup_for_nfsd_index, relookup, NDINIT, 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);

     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 conver-
     sion, in the days before the vfs(9) interface was implemented.

     Except for the simple forms, 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 {
		      * 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;

     The namei interface accesses vnode operations by passing arguments in the partially ini-
     tialised 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 information.	The details of the componentname structure are not abso-
     lutely necessary since the members are initialised by the helper macro NDINIT().  It is use-
     ful to know the operations and flags as specified in vnodeops(9).

     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 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
	   ISWHITEOUT	 found whiteout
	   DOWHITEOUT	 do whiteouts
	   REQUIREDIR	 must be a directory
	   CREATEDIR	 trailing slashes are ok
	   PARAMASK	 mask of parameter descriptors

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

	      Convert a pathname into a pointer to a vnode.  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 (UIO_SYSSPACE) or an
	      address in user space (UIO_USERSPACE).

	      The vnode for the pathname is returned in ndp->ni_vp.  The parent 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 translation 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 material 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 specified, 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 comparable to the historic
	      lookup() but this code is slated for refactoring.

     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 nor-
	      mally.  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 code.

     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 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.
	      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
	      pathname is passed as a pathbuf structure, which should be initialized 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.  In the
	      rare case that another set of credentials is required for the namei operation,
	      ndp->ni_cnd.cn_cred must be set manually.

     namei_simple_kernel(path, sflags, ret)
	      Look up the path path and translate it to a vnode, returned in ret.  The path argu-
	      ment must be a kernel (UIO_SYSSPACE) pointer.  The sflags argument chooses the pre-
	      cise 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 delib-
	      erately 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 sys/kern/vfs_lookup.c.

     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.

BSD					November 16, 2010				      BSD

All times are GMT -4. The time now is 12:32 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
Show Password