namei(9)

NAME

namei, NDINIT, NDFREE, NDHASGIANT - pathname translation and

lookup operations

SYNOPSIS

#include <sys/param.h>
#include <sys/proc.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 decremented 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 compo

nents. It takes
the following arguments:

ndp The struct nameidata to initialize.

op The operation which namei() will perform. The

following

operations are valid: LOOKUP, CREATE, DELETE,

and RENAME.
The latter three are just setup for those ef

fects; just calling namei() will not result in VOP_RENAME() be

ing called.

flags Operation flags. Several of these can be effec

tive 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

(directory) 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 re

turn the par

ent (directory) vnode in an unlocked state.

The parent
vnode must be released separately by using

vrele(9).

MPSAFE With this flag set, namei() will condition

ally acquire

Giant if it is required by a traversed file

system.
MPSAFE callers should pass the results of

NDHASGIANT

VFS_UNLOCK_GIANT in order to conditionally

release Giant
if necessary.

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 sym

bolic link if

the last part of the path supplied is a sym

bolic link
(i.e., it will return a vnode for whatever

the link
points at, instead for the link itself).

NOOBJ Do not call vfs_object_create() for the re

turned vnode,

even though it meets required criteria for

VM support.

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 fol

lowed.

SAVENAME Do not free the pathname buffer at the end

of the namei()

invocation; instead, free it later in

NDFREE

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 cur

rent 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 ob

ject on which

lookup is performed. This is available

on successful return if LOCKPARENT or WANTPARENT

is set. It
is locked if LOCKPARENT is set. Free

ing 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 other

wise. The v_usecount field of this vn

ode is incremented. If LOCKLEAF is set, it is also

locked.

Freeing this in NDFREE() can be inhib

ited 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 loca

tion 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_ON

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

FILES

src/sys/kern/vfs_lookup.c

SEE ALSO

uio(9), uma(9), VFS(9), VFS_UNLOCK_GIANT(9), vnode(9),

vput(9), vref(9)

AUTHORS

This manual page was written by Eivind Eklund <eivind@FreeB

SD.org> and
later significantly revised by Hiten M. Pandya <hmp@FreeB

SD.org>.

BUGS

The LOCKPARENT flag does not always result in the parent vn

ode 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 condi

tionally unlock
Giant.

BSD May 27, 2003

BSD