429 lines
12 KiB
Groff
429 lines
12 KiB
Groff
.\" $NetBSD: namei.9,v 1.24 2009/09/27 21:05:55 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 September 27, 2009
|
|
.Dt NAMEI 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm namei ,
|
|
.Nm lookup_for_nfsd ,
|
|
.Nm lookup_for_nfsd_index ,
|
|
.Nm relookup ,
|
|
.Nm NDINIT ,
|
|
.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" \
|
|
"enum uio_seg segflg" "const char *namep"
|
|
.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 structure:
|
|
.Bd -literal
|
|
struct nameidata {
|
|
/*
|
|
* Arguments to namei/lookup.
|
|
*/
|
|
const char *ni_dirp; /* pathname pointer */
|
|
enum uio_seg ni_segflg; /* location of pathname */
|
|
/*
|
|
* 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 */
|
|
u_long ni_loopcnt; /* count of symlinks encountered */
|
|
/*
|
|
* Lookup parameters
|
|
*/
|
|
struct componentname {
|
|
/*
|
|
* Arguments to lookup.
|
|
*/
|
|
u_long cn_nameiop; /* namei operation */
|
|
u_long cn_flags; /* flags to namei */
|
|
kauth_cred_t cn_cred; /* credentials */
|
|
/*
|
|
* Shared between lookup and commit routines.
|
|
*/
|
|
char *cn_pnbuf; /* pathname buffer */
|
|
const char *cn_nameptr; /* pointer to looked up name */
|
|
long cn_namelen; /* length of looked up component */
|
|
u_long cn_hash; /* hash value of looked up name */
|
|
long cn_consume; /* chars to consume in lookup() */
|
|
} 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 HASBUF
|
|
caller has allocated pathname buffer
|
|
.Em ni_cnd.cn_pnbuf
|
|
.It Dv SAVENAME
|
|
save pathname buffer
|
|
.It Dv SAVESTART
|
|
save starting directory
|
|
.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 ISSYMLINK
|
|
symlink needs interpretation
|
|
.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
|
|
If the caller of
|
|
.Fn namei
|
|
sets the SAVENAME flag, then it must free the buffer.
|
|
If
|
|
.Fn VOP_LOOKUP
|
|
sets the flag, then the buffer must be freed by either the commit
|
|
routine or the
|
|
.Fn VOP_ABORT
|
|
routine.
|
|
The
|
|
.Dv SAVESTART
|
|
flag is set only by the callers of
|
|
.Fn namei .
|
|
It implies
|
|
.Dv SAVENAME
|
|
plus the addition of saving the parent directory
|
|
that contains the name in
|
|
.Em ni_startdir .
|
|
It allows repeated calls to
|
|
.Fn lookup
|
|
for the name being sought.
|
|
The caller is responsible for releasing the buffer and for invoking
|
|
.Fn vrele
|
|
on
|
|
.Em ni_startdir .
|
|
.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 pathname is specified by
|
|
.Em ndp-\*[Gt]ni_dirp
|
|
and is of length
|
|
.Em ndp-\*[Gt]ni_pathlen .
|
|
The
|
|
.Em ndp-\*[Gt]segflg
|
|
flags defines whether the name in
|
|
.Em ndp-\*[Gt]ni_dirp
|
|
is an address in kernel space
|
|
.Pq Dv UIO_SYSSPACE
|
|
or an address in user space
|
|
.Pq Dv UIO_USERSPACE .
|
|
.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" "segflg" "namep"
|
|
Initialise a nameidata structure pointed to by
|
|
.Fa ndp
|
|
for use by the
|
|
.Nm
|
|
interface.
|
|
It saves having to deal with the componentname structure inside
|
|
.Fa ndp .
|
|
The operation and flags are specified by
|
|
.Fa op
|
|
and
|
|
.Fa flags
|
|
respectively.
|
|
These are the values to which
|
|
.Em ndp-\*[Gt]ni_cnd.cn_nameiop
|
|
and
|
|
.Em ndp-\*[Gt]ni_cnd.cn_flags
|
|
are respectively set.
|
|
The segment flags which defines whether the pathname is in kernel
|
|
address space or user address space is specified by
|
|
.Fa segflag .
|
|
The argument
|
|
.Fa namep
|
|
is a pointer to the pathname that
|
|
.Em ndp-\*[Gt]ni_dirp
|
|
is set to.
|
|
.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.
|
|
.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
|
|
This section describes places within the
|
|
.Nx
|
|
source tree where actual code implementing or using the name
|
|
lookup subsystem can be found.
|
|
All pathnames are relative to
|
|
.Pa /usr/src .
|
|
.Pp
|
|
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.
|