namei(9)
- NetBSD Manual Pages
NAMEI(9) NetBSD Kernel Developer's Manual NAMEI(9)
NAME
namei, lookup, relookup, NDINIT -- pathname lookup
SYNOPSIS
#include <sys/namei.h>
#include <sys/uio.h>
#include <sys/vnode.h>
int
namei(struct nameidata *ndp);
int
lookup(struct nameidata *ndp);
int
relookup(struct vnode *dvp, struct vnode **vpp,
struct componentname *cnp);
void
NDINIT(struct nameidata *ndp, u_long op, u_long flags,
enum uio_seg segflg, const char *namep);
DESCRIPTION
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) inter-
face was implemented.
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 infor-
mation. 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
DOWHITEOUT do whiteouts
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.
FUNCTIONS
namei(ndp)
Convert a pathname into a pointer to a vnode. The pathname is
specified by ndp->ni_dirp and is of length ndp->ni_pathlen. The
ndp->segflg flags defines whether the name in ndp->ni_dirp is an
address in kernel space (UIO_SYSSPACE) or an address in user
space (UIO_USERSPACE).
The vnode for the pathname is returned in ndp->ni_vp. The par-
ent directory is returned locked in ndp->ni_dvp iff LOCKPARENT
is specified.
If ndp->ni_cnd.cn_flags has the FOLLOW flag set then symbolic
links are followed when they occur at the end of the name trans-
lation process. Symbolic links are always followed for all
other pathname components other than the last.
lookup(ndp)
Search for a pathname. This is a very central and rather com-
plicated routine.
The pathname is specified by ndp->ni_dirp and is of length
ndp->ni_pathlen. The starting directory is taken from
ndp->ni_startdir. The pathname is descended until done, or a
symbolic link is encountered.
The semantics of lookup() are altered by the operation specified
by ndp->ni_cnd.cn_nameiop. When CREATE, RENAME, or DELETE is
specified, information usable in creating, renaming, or deleting
a directory entry may be calculated.
If the target of the pathname exists and LOCKLEAF is set, the
target is returned locked in ndp->ni_vp, otherwise it is
returned unlocked.
relookup(dvp, vpp, cnp)
Reacquire a path name component is a directory. This is a
quicker way to lookup a pathname component when the parent
directory is known. The locked parent directory vnode is speci-
fied by dvp and the pathname component by cnp. The vnode of the
pathname is returned in the address specified by vpp.
NDINIT(ndp, op, flags, segflg, namep)
Initialise a nameidata structure pointed to by ndp for use by
the namei interface. It saves having to deal with the compo-
nentname structure inside ndp. The operation and flags are
specified by op and flags respectively. These are the values to
which ndp->ni_cnd.cn_nameiop and ndp->ni_cnd.cn_flags are
respectively set. The segment flags which defines whether the
pathname is in kernel address space or user address space is
specified by segflag. The argument namep is a pointer to the
pathname that ndp->ni_dirp is set to.
This routine stores the credentials of the calling thread
(curlwp) in ndp. In the rare case that another set of creden-
tials is required for the namei operation, ndp->ni_cnd.cn_cred
must be set manually.
CODE REFERENCES
This section describes places within the NetBSD source tree where actual
code implementing or using the name lookup subsystem can be found. All
pathnames are relative to /usr/src.
The name lookup subsystem is implemented within the file
sys/kern/vfs_lookup.c.
SEE ALSO
intro(9), namecache(9), vfs(9), vnode(9), vnodeops(9)
BUGS
It is unfortunate that much of the namei interface makes assumptions on
the underlying vnode operations. These assumptions are an artefact of
the introduction of the vfs interface to split a file system interface
which was historically designed as a tightly coupled module.
NetBSD 5.0 December 28, 2007 NetBSD 5.0
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.