NLOOKUP(9)

NAME
nlookup, nlookup_init, nlookup_init_at, nlookup_init_raw, nlookup_init_root, nlookup_zero, nlookup_done, nlookup_done_at, nlookup_simple, nlookup_mp, nreadsymlink, naccess, naccess_va - namecache API

SYNOPSIS
#include <sys/types.h>
#include <sys/nlookup.h>
int
nlookup(struct nlookupdata *nd);
int
nlookup_init(struct nlookupdata *nd, const char *path, enum uio_seg seg, int flags);
int
nlookup_init_at(struct nlookupdata *nd, struct file **fpp, int fd, const char *path, enum uio_seg seg, int flags);
int
nlookup_init_raw(struct nlookupdata *nd, const char *path, enum uio_seg seg, int flags, struct ucred *cred, struct namecache *ncstart);
int
nlookup_init_root(struct nlookupdata *nd, const char *path, enum uio_seg seg, int flags, struct ucred *cred, struct namecache *ncstart, struct namecache *ncroot);
void
nlookup_zero(struct nlookupdata *nd);
void
nlookup_done(struct nlookupdata *nd);
void
nlookup_done_at(struct nlookupdata *nd, struct file *fp);
struct namecache *
nlookup_simple(const char *str, enum uio_seg seg, int niflags, int *error);
int
nlookup_mp(struct mount *mp, struct namecache **ncpp);
int
nreadsymlink(struct nlookupdata *nd, struct namecache *ncp, struct nlcomponent *nlc);
int
naccess(struct namecache *ncp, int vmode, struct ucred *cred);
int
naccess_va(struct vattr *va, int vmode, struct ucred *cred);

DESCRIPTION
nlookup() does a generic namecache lookup. Note that the passed struct nlookupdata is not nlookup_done()'d on return, even if an error occurs. If no error occurs the returned nl_ncp is always referenced and locked, otherwise it may or may not be. Intermediate directory elements, including the current directory, require execute (search) permission. nlookup() does not examine the access permissions on the returned element. If NLC_CREATE or NLC_DELETE is set the last directory must allow node creation ( VCREATE/VDELETE), and an error code of 0 will be returned for a non-existent target. Otherwise a non-existent target will cause ENOENT to be returned.

nlookup_init() initializes a struct nlookupdata, and does an early error return for copyin faults or a degenerate empty string (which is not allowed). The first process proc0's credentials are used if the calling thread is not associated with a process context.

nlookup_init_at() is similar to nlookup_init() except that when path is a relative path and fd is not AT_FDCWD, path is interpreted relative to the directory associated with fd and the file entry for fd is referenced and returned in *fpp. Its main use is the implementation of *at() system calls.

nlookup_init_raw() works similarly to nlookup_init() but does not assume a process context. rootncp is always chosen for the root directory and the cred and starting directory are supplied in the arguments.

nlookup_init_root() works similarly to nlookup_init_raw() but does not assume rootnch for the root directory. The root directory is supplied in the arguments, and is also used for the jail directory.

nlookup_zero() zeroes a given struct nlookupdata.

nlookup_done() cleans up an nlookupdata structure after we are through with it. This function may be called on any nlookupdata structure initialized with nlookup_init(). Calling nlookup_done() is mandatory in all cases except where nlookup_init() returns an error, even if as a consumer you believe you have taken all dynamic elements out of the nlookupdata structure.

nlookup_done_at() cleans up an nlookupdata structure that was initialized with nlookup_init_at() and drops the reference to fp.

nlookup_simple() is a simple all-in-one nlookup(). It returns a locked namecache structure or NULL if an error occurred. Note that the returned ncp is not checked for permissions, though VEXEC is checked on the directory path leading up to the result. The caller must call naccess() to check the permissions of the returned leaf.

nlookup_mp() is used to resolve a mount point's glue ncp. It creates the illusion of continuity in the namecache tree by connecting the ncp related to the vnode under the mount to the ncp related to the mount's root vnode. If no error occurred a locked, ref'd ncp is stored in *ncpp.

nreadsymlink() reads the contents of a symlink, allocates a path buffer out of the namei_zone and initialize the supplied nlcomponent with the result. If an error occurs no buffer will be allocated or returned in the nlc.

naccess() generally checks the V* access bits from <sys/vnode.h>. All specified bits must pass for this function to return 0. If VCREATE is specified and the target ncp represents a non-existent file or dir, or if VDELETE is specified and the target exists, the parent directory is checked for VWRITE. If VEXCL is specified and the target ncp represents a positive hit, an error is returned. If VCREATE is not specified and the target does not exist (negative hit), ENOENT is returned. Note that nlookup() does not (and should not) return ENOENT for non-existent leafs. The passed ncp may or may not be locked. The caller should use a locked ncp on leaf lookups, especially for VCREATE, VDELETE, and VEXCL checks.

naccess_va() checks the requested access against the given vattr using cred.

FILES
sys/kern/vfs_nlookup.c

SEE ALSO
VFS(9), vnode(9)

AUTHORS
This man page was written by Sascha Wildner.