NAME

namei, lookup_for_nfsd, lookup_for_nfsd_index, relookup, NDINIT, NDAT, namei_simple_kernel, namei_simple_user — pathname lookup

SYNOPSIS

#include <sys/namei.h>
#include <sys/uio.h>
#include <sys/vnode.h>

int
namei(struct nameidata *ndp);

int
lookup_for_nfsd(struct nameidata *ndp, struct vnode *startdir, int neverfollow);

int
lookup_for_nfsd_index(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, struct pathbuf *pathbuf);

NDAT(struct nameidata *ndp, struct vnode *dvp);

int
namei_simple_kernel(const char *path, namei_simple_flags_t sflags, struct vnode **ret);

int
namei_simple_user(const char *path, namei_simple_flags_t sflags, struct vnode **ret);

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) interface was implemented.

Except for the simple forms, the arguments passed to the functions are encapsulated in the nameidata structure. It has the following layout:

struct nameidata { 
        /* 
         * Arguments to namei/lookup. 
         */ 
        struct vnode *ni_startdir;      /* starting dir, cwd if null */ 
        struct pathbuf *ni_pathbuf;     /* pathname container */ 
        char *ni_pnbuf;                 /* extra pathname buffer ref (XXX) */ 
        /* 
         * 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 */ 
        unsigned int ni_loopcnt;        /* count of symlinks encountered */ 
        /* 
         * Lookup parameters 
         */ 
        struct componentname { 
                /* 
                 * Arguments to lookup. 
                 */ 
                uint32_t cn_nameiop;    /* namei operation */ 
                uint32_t cn_flags;      /* flags to namei */ 
                kauth_cred_t cn_cred;   /* credentials */ 
                /* 
                 * Shared between lookup and commit routines. 
                 */ 
                const char *cn_nameptr; /* pointer to looked up name */ 
                size_t cn_namelen;      /* length of looked up component */ 
                size_t cn_consume;      /* chars to be consumed this time */ 
        } 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

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 nameidata structure pointed to by ndp should be initialized with the NDINIT() macro. Direct initialization of members of struct nameidata is not supported and may break silently in the future.

The vnode for the pathname is returned in ndp->ni_vp. The parent 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 translation process. Symbolic links are always followed for all other pathname components other than the last.

Historically namei had a sub-function called lookup(). This function processed a pathname until either running out of material or encountering a symbolic link. namei worked by first setting up the start directory ndp->ni_startdir and then calling lookup() repeatedly.

The semantics of namei 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.

As of this writing the internal function do_lookup() is comparable to the historic lookup() but this code is slated for refactoring.

lookup_for_nfsd(ndp, startdir, neverfollow)

This is a private entry point into namei used by the NFS server code. It looks up a path starting from startdir. If neverfollow is set, any symbolic link (not just at the end of the path) will cause an error. Otherwise, it follows symlinks normally. Its semantics are similar to a symlink-following loop around the historic lookup() function described above. It should not be used by new code.

lookup_for_nfsd_index(ndp)

This is a (second) private entry point into namei used by the NFS server code. Its semantics are similar to the historic lookup() function described above. It should not be used by new code.

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 specified 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, pathbuf)

Initialise a nameidata structure pointed to by ndp for use by the namei interface. The operation and flags are specified by op and flags respectively. The pathname is passed as a pathbuf structure, which should be initialized using one of the pathbuf(9) operations. Destroying the pathbuf is the responsibility of the caller; this must not be done until the caller is finished with all of the namei results and all of the nameidata contents except for the result vnode.

This routine stores the credentials of the calling thread (curlwp) in ndp. In the rare case that another set of credentials is required for the namei operation, ndp->ni_cnd.cn_cred must be set manually.

The following fields of ndp are set:

ni_cnd.cn_nameiop

is set to op.

ni_cnd.cn_flags

is set to flags.

ni_startdir

is set to NULL.

ni_pathbuf

is set to pathbuf.

ni_cnd.cn_cred

is set using kauth_cred_get(9).

Other fields of struct nameidata are not (normally) initialized before namei is called. Direct assignment of these or other fields other than by using NDINIT() or NDAT(), except as specifically described above, is not supported and may break silently in the future.

NDAT(ndp, dvp)

This macro is used after NDINIT() to set the starting directory. This supersedes the current process's current working directory as the initial point of departure for looking up relative paths. This mechanism is used by openat(2) and related calls.

namei_simple_kernel(path, sflags, ret)

Look up the path path and translate it to a vnode, returned in ret. The path argument must be a kernel (UIO_SYSSPACE) pointer. The sflags argument chooses the precise behavior. It may be set to one of the following symbols:

NSM_NOFOLLOW_NOEMULROOT

NSM_NOFOLLOW_TRYEMULROOT

NSM_FOLLOW_NOEMULROOT

NSM_FOLLOW_TRYEMULROOT

These select (or not) the FOLLOW/NOFOLLOW and TRYEMULROOT flags. Other flags are not available through this interface, which is nonetheless sufficient for more than half the namei() usage in the kernel. Note that the encoding of sflags has deliberately been arranged to be type-incompatible with anything else. This prevents various possible accidents while the namei() interface is being rototilled.

namei_simple_user(path, sflags, ret)

This function is the same as namei_simple_kernel() except that the path argument shall be a user pointer (UIO_USERSPACE) rather than a kernel pointer.

CODE REFERENCES

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.