netbsd/share/man/man9/namei.9

.\"     $NetBSD: namei.9,v 1.34 2015/04/21 10:00:30 wiz Exp $
.\"
.\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 21, 2015
.Dt NAMEI 9
.Os
.Sh NAME
.Nm namei ,
.Nm lookup_for_nfsd ,
.Nm lookup_for_nfsd_index ,
.Nm relookup ,
.Nm NDINIT ,
.Nm NDAT ,
.Nm namei_simple_kernel ,
.Nm namei_simple_user
.Nd pathname lookup
.Sh SYNOPSIS
.In sys/namei.h
.In sys/uio.h
.In sys/vnode.h
.Ft int
.Fn namei "struct nameidata *ndp"
.Ft int
.Fn lookup_for_nfsd "struct nameidata *ndp" "struct vnode *startdir" \
"int neverfollow"
.Ft int
.Fn lookup_for_nfsd_index "struct nameidata *ndp"
.Ft int
.Fn relookup "struct vnode *dvp" "struct vnode **vpp" \
"struct componentname *cnp"
.Ft void
.Fn NDINIT "struct nameidata *ndp" "u_long op" "u_long flags" \
"struct pathbuf *pathbuf"
.Fn NDAT "struct nameidata *ndp" "struct vnode *dvp"
.Ft int
.Fn namei_simple_kernel "const char *path" "namei_simple_flags_t sflags" \
"struct vnode **ret"
.Ft int
.Fn namei_simple_user "const char *path" "namei_simple_flags_t sflags" \
"struct vnode **ret"
.Sh DESCRIPTION
The
.Nm
interface is used to convert pathnames to file system vnodes.
The
name of the interface is actually a contraction of the words
.Em name
and
.Em inode
for name-to-inode conversion, in the days before the
.Xr vfs 9
interface was implemented.
.Pp
Except for the simple forms, the arguments passed to the functions are
encapsulated in the
.Em nameidata
structure.
It has the following layout:
.Bd -literal
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;
};
.Ed
.Pp
The
.Nm
interface accesses vnode operations by passing arguments in the
partially initialised
.Em componentname
structure
.Em ni_cnd .
This structure describes the subset of information from the nameidata
structure that is passed through to the vnode operations.
See
.Xr vnodeops 9
for more information.
The details of the componentname structure are not absolutely necessary
since the members are initialised by the helper macro
.Fn NDINIT .
It is useful to know the operations and flags as specified in
.Xr vnodeops 9 .
.Pp
The
.Nm
interface overloads
.Em ni_cnd.cn_flags
with some additional flags.
These flags should be specific to the
.Nm
interface and ignored by vnode operations.
However, due to the historic close relationship between the
.Nm
interface and the vnode operations, these flags are sometimes used
(and set) by vnode operations, particularly
.Fn VOP_LOOKUP .
The additional flags are:
.Pp
.Bl -tag -offset indent -width NOCROSSMOUNT -compact
.It Dv NOCROSSMOUNT
do not cross mount points
.It Dv RDONLY
lookup with read-only semantics
.It Dv ISDOTDOT
current pathname component is ..
.It Dv MAKEENTRY
add entry to the name cache
.It Dv ISLASTCN
this is last component of pathname
.It Dv ISWHITEOUT
found whiteout
.It Dv DOWHITEOUT
do whiteouts
.It Dv REQUIREDIR
must be a directory
.It Dv CREATEDIR
trailing slashes are ok
.It Dv PARAMASK
mask of parameter descriptors
.El
.Pp
All access to the
.Nm
interface must be in process context.
Pathname lookups cannot be done in interrupt context.
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn namei "ndp"
Convert a pathname into a pointer to a vnode.
The nameidata structure pointed to by
.Fa ndp
should be initialized with the
.Fn NDINIT
macro.
Direct initialization of members of struct nameidata is
.Em not
supported and may break silently in the future.
.Pp
The vnode for the pathname is returned in
.Em ndp-\*[Gt]ni_vp .
The parent directory is returned locked in
.Em ndp-\*[Gt]ni_dvp
iff
.Dv LOCKPARENT
is specified.
.Pp
If
.Em ndp-\*[Gt]ni_cnd.cn_flags
has the
.Dv 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.
.Pp
Historically
.Nm
had a sub-function called
.Fn lookup .
This function processed a pathname until either running out of
material or encountering a symbolic link.
.Nm
worked by first setting up the start directory
.Em ndp-\*[Gt]ni_startdir
and then calling
.Fn lookup
repeatedly.
.Pp
The semantics of
.Nm
are altered by the operation specified by
.Em ndp-\*[Gt]ni_cnd.cn_nameiop .
When
.Dv CREATE ,
.Dv RENAME ,
or
.Dv DELETE
is specified, information usable in
creating, renaming, or deleting a directory entry may be calculated.
.Pp
If the target of the pathname exists and LOCKLEAF is set, the target
is returned locked in
.Em ndp-\*[Gt]ni_vp ,
otherwise it is returned unlocked.
.Pp
As of this writing the internal function
.Fn do_lookup
is comparable to the historic
.Fn lookup
but this code is slated for refactoring.
.It Fn lookup_for_nfsd "ndp" "startdir" "neverfollow"
This is a private entry point into
.Nm
used by the NFS server code.
It looks up a path starting from
.Fa startdir .
If
.Fa neverfollow
is set,
.Em 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
.Fn lookup
function described above.
It should not be used by new code.
.It Fn lookup_for_nfsd_index "ndp"
This is a (second) private entry point into
.Nm
used by the NFS server code.
Its semantics are similar to the historic
.Fn lookup
function described above.
It should not be used by new code.
.It Fn 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
.Fa dvp
and the pathname component by
.Fa cnp .
The vnode of the pathname is returned in the address specified by
.Fa vpp .
.It Fn NDINIT "ndp" "op" "flags" "pathbuf"
Initialise a nameidata structure pointed to by
.Fa ndp
for use by the
.Nm
interface.
The operation and flags are specified by
.Fa op
and
.Fa flags
respectively.
The pathname is passed as a pathbuf structure, which should be
initialized using one of the
.Xr 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
.Nm
results and all of the nameidata contents except for the result vnode.
.Pp
This routine stores the credentials of the calling thread
.Va ( curlwp )
in
.Fa ndp .
In the rare case that another set of credentials is required for the
namei operation,
.Em ndp-\*[Gt]ni_cnd.cn_cred
must be set manually.
.Pp
The following fields of
.Fa ndp
are set:
.Bl -tag -width compact
.It Fa ni_cnd.cn_nameiop
is set to
.Fa op .
.It Fa ni_cnd.cn_flags
is set to
.Fa flags .
.It Fa ni_startdir
is set to
.Dv NULL .
.It Fa ni_pathbuf
is set to
.Fa pathbuf .
.It Fa ni_cnd.cn_cred
is set using
.Xr kauth_cred_get 9 .
.El
Other fields of struct nameidata are not
.Pq normally
initialized before
.Nm
is called.
Direct assignment of these or other fields other than by using
.Fn NDINIT
or
.Fn NDAT ,
except as specifically described above, is not supported and may break
silently in the future.
.It Fn NDAT "ndp" "dvp"
This macro is used after
.Fn 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
.Xr openat 2
and related calls.
.It Fn namei_simple_kernel "path" "sflags" "ret"
Look up the path
.Fa path
and translate it to a vnode, returned in
.Fa ret .
The
.Fa path
argument must be a kernel
.Pq Dv UIO_SYSSPACE
pointer.
The
.Fa sflags
argument chooses the precise behavior.
It may be set to one of the following symbols:
.Bl -tag -offset indent -width NSM_NOFOLLOW_TRYEMULROOT -compact
.It Dv NSM_NOFOLLOW_NOEMULROOT
.It Dv NSM_NOFOLLOW_TRYEMULROOT
.It Dv NSM_FOLLOW_NOEMULROOT
.It Dv NSM_FOLLOW_TRYEMULROOT
.El
These select (or not) the
.Dv FOLLOW/NOFOLLOW
and
.Dv TRYEMULROOT
flags.
Other flags are not available through this interface, which is
nonetheless sufficient for more than half the
.Fn namei
usage in the kernel.
Note that the encoding of
.Fa sflags
has deliberately been arranged to be type-incompatible with anything
else.
This prevents various possible accidents while the
.Fn namei
interface is being rototilled.
.It Fn namei_simple_user "path" "sflags" "ret"
This function is the same as
.Fn namei_simple_kernel
except that the
.Fa path
argument shall be a user pointer
.Pq Dv UIO_USERSPACE
rather than a kernel pointer.
.El
.Sh CODE REFERENCES
The name lookup subsystem is implemented within the file
.Pa sys/kern/vfs_lookup.c .
.Sh SEE ALSO
.Xr intro 9 ,
.Xr namecache 9 ,
.Xr vfs 9 ,
.Xr vnode 9 ,
.Xr vnodeops 9
.Sh BUGS
It is unfortunate that much of the
.Nm
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.