lookup man page on NetBSD

Man page or keyword search:  
man Server   9087 pages
apropos Keyword Search (all sections)
Output format
NetBSD logo
[printable version]

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

NAME
     namei, lookup_for_nfsd, lookup_for_nfsd_index, relookup, NDINIT,
     namei_simple_kernel, namei_simple_user — pathname lookup

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

     int
     namei(struct nameidata *ndp);

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

     int
     lookup_for_nfsd_index(struct nameidata *ndp);

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

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

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

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

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

FUNCTIONS
     namei(ndp)
	      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 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‐
	      toring.

     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.

     lookup_for_nfsd_index(ndp)
	      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 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.  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->ni_cnd.cn_nameiop and ndp->ni_cnd.cn_flags are
	      respectively set.	 The pathname is passed as a pathbuf struc‐
	      ture, 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 creden‐
	      tials 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 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:
		    NSM_NOFOLLOW_NOEMULROOT
		    NSM_NOFOLLOW_TRYEMULROOT
		    NSM_FOLLOW_NOEMULROOT
		    NSM_FOLLOW_TRYEMULROOT
	      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.

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

SEE ALSO
     intro(9), namecache(9), vfs(9), vnode(9), vnodeops(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			       November 16, 2010			   BSD
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server NetBSD

List of man pages available for NetBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net