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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
NAMEI(9)	       FreeBSD Kernel Developer's Manual	      NAMEI(9)

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

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

     int
     namei(struct nameidata *ndp);

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

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

     int
     NDHASGIANT(struct nameidata *ndp);

DESCRIPTION
     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),
     depending on whether the LOCKLEAF flag was	specified or not.  If the
     Giant lock	is required, namei will	acquire	it if the caller indicates it
     is	MPSAFE,	in which case the caller must later release Giant based	on the
     results of	NDHASGIANT().

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

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

     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.

NAMEI OPERATION	FLAGS
     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()
		 invocation; instead, free it later in NDFREE()	so that	the
		 caller	may access the pathname	buffer.	 See below for
		 details.

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

ALLOCATED ELEMENTS
     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
		      otherwise.

		      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
		      inhibited	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
		      NDF_NO_VP_RELE, NDF_NO_VP_PUT, or	NDF_NO_VP_UNLOCK (with
		      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
		      buffer, 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.

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

FILES
     src/sys/kern/vfs_lookup.c

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

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

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

AUTHORS
     This manual page was written by Eivind Eklund <eivind@FreeBSD.org>	and
     later significantly revised by Hiten M. Pandya <hmp@FreeBSD.org>.

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

     Non-MPSAFE	file systems exist, requiring callers to conditionally unlock
     Giant.

FreeBSD	10.1			 March 1, 2012			  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | NAMEI OPERATION FLAGS | ALLOCATED ELEMENTS | RETURN VALUES | FILES | ERRORS | SEE ALSO | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=namei&sektion=9&manpath=FreeBSD+10.1-RELEASE>

home | help