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

# NAME

`namei`, `vfs_lookup`, `vfs_relookup`, `NDINIT`, `NDINITAT` — pathname lookup

# SYNOPSIS

`#include <sys/param.h>`
`#include <sys/namei.h>`

int
`namei`(struct nameidata *ndp);

int
`vfs_lookup`(struct nameidata *ndp);

int
`vfs_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, struct proc *p);

void
`NDINITAT`(struct nameidata *ndp, u_long op, u_long flags, enum uio_seg segflg, int dirfd, const char *namep, struct proc *p);

# DESCRIPTION

The `namei`() function converts a pathname to a vnode(9). It uses the following structure:

    struct nameidata {
            /*
             * Arguments to namei/lookup.
             */
            const char *ni_dirp;            /* pathname pointer */
            int     ni_dirfd;               /* AT_FDCWD or fd of base of */
    					/* relative paths */
            enum    uio_seg ni_segflg;      /* location of pathname */
            /*
             * Arguments to lookup.
             */
            struct  vnode *ni_startdir;     /* starting directory */
            struct  vnode *ni_rootdir;      /* logical root directory */
            uint64_t ni_pledge;             /* expected pledge for namei */
            u_char ni_unveil;               /* required unveil flags for namei */
            /*
             * 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 */
            char *ni_next;                  /* next location in pathname */
            u_long  ni_loopcnt;             /* count of symlinks encountered */
            struct unveil *ni_unveil_match; /* last matching unveil component */
            /*
             * Lookup parameters
             */
            struct componentname ni_cnd;
    };

The `namei`() function 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 VOP_LOOKUP(9) for more information. The details of the componentname structure are not absolutely necessary since the members are initialised by the helper macros `NDINIT`() and `NDINITAT`(). It is useful to know the operations and flags as specified in VOP_LOOKUP(9).

The `namei`() function overloads ni_cnd.cn_flags with some additional flags. These flags should be specific to `namei`() and ignored by vnode operations. However, due to the historic close relationship between `namei`() 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
REALPATH
  save pathname buffer for realpath
REQUIREDIR
  must be a directory
STRIPSLASHES
  strip trailing slashes from the pathname
PDIRUNLOCK
  `VOP_LOOKUP`() unlocked parent dir
BYPASSUNVEIL
  bypass pledge paths checks
KERNELPATH
  access file as kernel, not process

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 `vfs_lookup`() for the name being sought. The caller is responsible for releasing the buffer and for invoking `vrele`() on ni_startdir.

All access to `namei`(), `vfs_lookup`(), and `vfs_relookup`() 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 flag 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 referenced and returned in ndp->ni_vp.

  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 translation process. Symbolic links are always followed for all other pathname components other than the last.

  If the LOCKLEAF flag is set, a locked vnode is returned.

`vfs_lookup`(ndp)
  Search for a pathname. This is a very central and rather complicated 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 `vfs_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 ndp->ci_cnd.cn_flags has LOCKPARENT set, the parent directory is returned locked in ndp->ni_dvp. If WANTPARENT is set, the parent directory is returned unlocked. Otherwise the parent directory is not returned. 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.

`vfs_relookup`(dvp, vpp, cnp)
  Reacquire a path name component in a directory. This is a quicker way to lookup a pathname component when the parent directory is known. The unlocked parent directory vnode is specified by dvp and the pathname component by cnp. The vnode of the pathname is returned in the address specified by vpp.
`NDINITAT`(ndp, op, flags, segflg, dirfd, namep, p)
  Initialise a nameidata structure pointed to by ndp for use by the `namei` interfaces. It saves having to deal with the componentname 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 flag, which defines whether the pathname is in kernel address space or user address space, is specified by segflg. The directory from which relative pathnames will be looked up is specified by dirfd, with `AT_FDCWD` specifying use of the current working directory of process p. The argument namep is a pointer to the pathname that ndp->ni_dirp is set to and p is the calling process.
`NDINIT`(ndp, op, flags, segflg, namep, p)
  Same as `NDINITAT`(ndp, op, flags, segflg, AT_FDCWD, namep, p).

# CODE REFERENCES

The name lookup subsystem is implemented within the file sys/kern/vfs_lookup.c.

# SEE ALSO

intro(9), vfs(9), vnode(9), VOP_LOOKUP(9)

# HISTORY

The `namei`() function first appeared in Version 4 AT&T UNIX. Its name is an abbreviation for the name-to-inode conversion which it performed before the appearance of vfs(9) in 4.3BSD-Reno.

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

July 15, 2023 | Debian