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

FreeBSD Manual Pages

  
 
  

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

NAME
       namei,  NDINIT,	NDINIT_AT,  NDFREE_PNBUF  --  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,	 enum nameiop op,     u_int64_t	flags,
	   enum	uio_seg	segflg,	const char *namep);

       void
       NDINIT_AT(struct	nameidata *ndp,	   enum	nameiop	op,   u_int64_t	flags,
	   enum	uio_seg	segflg,	const char *namep, int dirfd);

       void
       NDFREE_PNBUF(struct nameidata *ndp);

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

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

       ndp     A pointer to the	struct nameidata to initialize.

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

       flags   Operation  flags,  described  in	 the next section.  Several of
	       these can be effective at the same time.

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

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

       The NDINIT_AT() macro is	similar	to NDINIT(), but takes one extra argu-
       ment:

       dirfd   File  descriptor	 referencing a directory, or the special value
	       AT_FDCWD	meaning	the calling thread's  current  working	direc-
	       tory.  Lookups will be performed	relative to this directory.

       The  NDFREE_PNBUF() macro is used to free the pathname buffer.  It must
       be called exactly once for each successful namei() call.	 It takes  the
       following argument:

       ndp     A  pointer  to a	struct nameidata that was used in a successful
	       namei() call.

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

       LOCKLEAF	   Lock	vnode on return	with LK_EXCLUSIVE unless LOCKSHARED is
		   also	set.  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  (di-
		   rectory)  vnode, ni_dvp in locked state, unless it is iden-
		   tical to ni_vp, in which case ni_dvp	is not locked  per  se
		   (but	 may  be  locked  due  to LOCKLEAF).  If a lock	is en-
		   forced,  it	 should	  be   released	  using	  vput(9)   or
		   VOP_UNLOCK(9) and vrele(9).

       LOCKSHARED  Lock	 vnode	on  return with	LK_SHARED, if permitted	by the
		   file	system that owns the vnode.  The file system must  ex-
		   plicitly  permit  this  by  setting	MNTK_LOOKUP_SHARED  in
		   mp->mnt_kern_flag   during	 mount	  and	 by    calling
		   VN_LOCK_ASHARE() when allocating the	vnode.	If LOCKLEAF is
		   specified but shared	locking	is not permitted, then the vn-
		   ode	will  be  returned  with  LK_EXCLUSIVE.	 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).

       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.

ALLOCATED ELEMENTS
       The nameidata structure is composed of the following fields:

       ni_startdir	In  the	normal case, this is either the	current	direc-
			tory 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  vfs_lookup(),  and
			should	not  be	 considered  valid  after  a  call  to
			namei().

       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.

       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.

       ni_cnd.cn_pnbuf	The  pathname buffer contains the location of the file
			or directory that will be used	by  the	 namei	opera-
			tions.	 It  is	 managed by the	uma(9) zone allocation
			interface.

RETURN VALUES
       If successful, namei() will return 0, otherwise it will return  an  er-
       ror.

FILES
       src/sys/kern/vfs_lookup.c

ERRORS
       Errors which namei() may	return:

       [ENOTDIR]	  A  component	of the specified pathname is not a di-
			  rectory 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 ex-
			  ist, or the pathname is an empty string.

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

       [ELOOP]		  Too many symbolic links were encountered  in	trans-
			  lating 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), vrele(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.

FreeBSD	14.3			 May 16, 2025			      NAMEI(9)

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

home | help