DragonFly On-Line Manual Pages

Search: Section:  

NLOOKUP(9)            DragonFly Kernel Developer's Manual           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.

DragonFly 5.5                  December 30, 2016                 DragonFly 5.5

Search: Section: