Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NAMEI(9)		 BSD Kernel Developer's	Manual		      NAMEI(9)

     namei, NDINIT, NDFREE, -- pathname	translation and	lookup operations

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

     namei(struct nameidata *ndp);

     NDINIT(struct nameidata *ndp, u_long op, u_long flags,
	 enum uio_seg segflg, const char *namep, struct	thread *td);

     NDFREE(struct nameidata *ndp, const uint flags);

     The namei facility	allows the client to perform pathname translation and
     lookup operations.	 The namei functions will increment the	reference
     count for the vnode in question.  The reference count has to be decre-
     mented after use of the vnode, by using either vrele(9) or	vput(9), de-
     pending on	whether	the LOCKLEAF flag was specified	or not.

     The NDINIT() function is used to initialize namei components.  It takes
     the following arguments:

     ndp     The struct	nameidata to initialize.

     op	     The operation which namei() will perform.	The following opera-
	     tions are valid: LOOKUP, CREATE, DELETE, and RENAME.  The latter
	     three are just setup for those effects; just calling namei() will
	     not result	in VOP_RENAME()	being called.

     flags   Operation flags.  Several of these	can be effective at the	same

     segflg  UIO segment indicator.  This indicates if the name	of the object
	     is	in userspace (UIO_USERSPACE) or	in the kernel address space

     namep   Pointer to	the component's	pathname buffer	(the file or directory
	     name that will be looked up).

     td	     The thread	context	to use for namei operations and	locks.

     The namei() function takes	the following set of "operation	flags" that
     influence its operation:

     LOCKLEAF	 Lock vnode on return.	This is	a full lock of the vnode; the
		 VOP_UNLOCK(9) should be used to release the lock (or vput(9)
		 which is equivalent to	calling	VOP_UNLOCK(9) followed by
		 vrele(9), all in one).

     LOCKPARENT	 This flag lets	the namei() function return the	parent (direc-
		 tory) vnode, ni_dvp in	locked state, unless it	is identical
		 to ni_vp, in which case ni_dvp	is not locked per se (but may
		 be locked due to LOCKLEAF).  If a lock	is enforced, it	should
		 be released using vput(9) or VOP_UNLOCK(9) and	vrele(9).

     WANTPARENT	 This flag allows the namei() function to return the parent
		 (directory) vnode in an unlocked state.  The parent vnode
		 must be released separately by	using vrele(9).

     NOCACHE	 Avoid namei() creating	this entry in the namecache if it is
		 not already present.  Normally, namei() will add entries to
		 the name cache	if they	are not	already	there.

     FOLLOW	 With this flag, namei() will follow the symbolic link if the
		 last part of the path supplied	is a symbolic link (i.e., it
		 will return a vnode for whatever the link points at, instead
		 for the link itself).

     NOFOLLOW	 Do not	follow symbolic	links (pseudo).	 This flag is not
		 looked	for by the actual code,	which looks for	FOLLOW.
		 NOFOLLOW is used to indicate to the source code reader	that
		 symlinks are intentionally not	followed.

     SAVENAME	 Do not	free the pathname buffer at the	end of the namei() in-
		 vocation; instead, free it later in NDFREE() so that the
		 caller	may access the pathname	buffer.	 See below for de-

     SAVESTART	 Retain	an additional reference	to the parent directory; do
		 not free the pathname buffer.	See below for details.

     The nameidata structure is	composed of the	following fields:

     ni_startdir      In the normal case, this is either the current directory
		      or the root.  It is the current directory	if the name
		      passed in	does not start with `/'	and we have not	gone
		      through any symlinks with	an absolute path, and the root

		      In this case, it is only used by lookup(), and should
		      not be considered	valid after a call to namei().	If
		      SAVESTART	is set,	this is	set to the same	as ni_dvp,
		      with an extra vref(9).  To block NDFREE()	from releasing
		      ni_startdir, the NDF_NO_STARTDIR_RELE can	be set.

     ni_dvp	      Vnode pointer to directory of the	object on which	lookup
		      is performed.  This is available on successful return if
		      LOCKPARENT or WANTPARENT is set.	It is locked if
		      LOCKPARENT is set.  Freeing this in NDFREE() can be in-
		      hibited by NDF_NO_DVP_RELE, NDF_NO_DVP_PUT, or
		      NDF_NO_DVP_UNLOCK	(with the obvious effects).

     ni_vp	      Vnode pointer to the resulting object, NULL otherwise.
		      The v_usecount field of this vnode is incremented.  If
		      LOCKLEAF is set, it is also locked.

		      Freeing this in NDFREE() can be inhibited	by
		      the obvious effects).

     ni_cnd.cn_pnbuf  The pathname buffer contains the location	of the file or
		      directory	that will be used by the namei operations.  It
		      is managed by the	uma(9) zone allocation interface.  If
		      the SAVESTART or SAVENAME	flag is	set, then the pathname
		      buffer is	available after	calling	the namei() function.

		      To only deallocate resources used	by the pathname	buf-
		      fer, ni_cnd.cn_pnbuf, then NDF_ONLY_PNBUF	flag can be
		      passed to	the NDFREE() function.	To keep	the pathname
		      buffer intact, the NDF_NO_FREE_PNBUF flag	can be passed
		      to the NDFREE() function.

     If	successful, namei() will return	0, otherwise it	will return an error.


     Errors which namei() may return:

     [ENOTDIR]		A component of the specified pathname is not a direc-
			tory when a directory is expected.

     [ENAMETOOLONG]	A component of a pathname exceeded 255 characters, or
			an entire pathname exceeded 1023 characters.

     [ENOENT]		A component of the specified pathname does not exist,
			or the pathname	is an empty string.

     [EACCES]		An attempt is made to access a file in a way forbidden
			by its file access permissions.

     [ELOOP]		Too many symbolic links	were encountered in translat-
			ing the	pathname.

     [EISDIR]		An attempt is made to open a directory with write mode

     [EINVAL]		The last component of the pathname specified for a
			DELETE or RENAME operation is `.'.

     [EROFS]		An attempt is made to modify a file or directory on a
			read-only file system.

     uio(9), uma(9), VFS(9), vnode(9), vput(9),	vref(9)

     This manual page was written by Eivind Eklund <>	and
     later significantly revised by Hiten M. Pandya <>.

     The LOCKPARENT flag does not always result	in the parent vnode being
     locked.  This results in complications when the LOCKPARENT	is used.  In
     order to solve this for the cases where both LOCKPARENT and LOCKLEAF are
     used, it is necessary to resort to	recursive locking.

BSD				  May 6, 2015				   BSD


Want to link to this manual page? Use this URL:

home | help