NLOOKUP(9) BSD Kernel Developer's Manual NLOOKUP(9)NAME
nlookup, nlookup_init, nlookup_init_at, nlookup_init_raw,
nlookup_init_root, nlookup_set_cred, 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_set_cred(struct nlookupdata *nd, struct ucred *cred);
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);
DESCRIPTIONnlookup() 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, includ‐
ing the current directory, require execute (search) permission.
nlookup() does not examine the access permissions on the returned ele‐
ment. 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_set_cred() sets a different credential; this credential will be
used by future operations performed on nd.nl_open_vp and the nlookupdata
structure.
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 ini‐
tialized 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 direc‐
tory 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 ALSOVFS(9), vnode(9)AUTHORS
This man page was written by Sascha Wildner.
BSD August 1, 2010 BSD