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) interface 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 information. 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
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.