314 lines
9.3 KiB
Groff
314 lines
9.3 KiB
Groff
.\" $NetBSD: namei.9,v 1.12 2006/03/03 16:15:11 rumble 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 March 3, 2006
|
|
.Dt NAMEI 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm namei ,
|
|
.Nm lookup ,
|
|
.Nm relookup ,
|
|
.Nm NDINIT
|
|
.Nd pathname lookup
|
|
.Sh SYNOPSIS
|
|
.In sys/namei.h
|
|
.In sys/lwp.h
|
|
.In sys/uio.h
|
|
.In sys/vnode.h
|
|
.Ft int
|
|
.Fn namei "struct nameidata *ndp"
|
|
.Ft int
|
|
.Fn lookup "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" "struct lwp *l"
|
|
.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
|
|
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 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 NOCROSSMOUNT
|
|
do not cross mount points
|
|
.It RDONLY
|
|
lookup with read-only semantics
|
|
.It HASBUF
|
|
caller has allocated pathname buffer
|
|
.Em ni_cnd.cn_pnbuf
|
|
.It SAVENAME
|
|
save pathname buffer
|
|
.It SAVESTART
|
|
save starting directory
|
|
.It ISDOTDOT
|
|
current pathname component is ..
|
|
.It MAKEENTRY
|
|
add entry to the name cache
|
|
.It ISLASTCN
|
|
this is last component of pathname
|
|
.It ISSYMLINK
|
|
symlink needs interpretation
|
|
.It ISWHITEOUT
|
|
found whiteout
|
|
.It DOWHITEOUT
|
|
do whiteouts
|
|
.It REQUIREDIR
|
|
must be a directory
|
|
.It PDIRUNLOCK
|
|
vfs_lookup() unlocked parent dir
|
|
.It 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 SAVESTART flag is set only by the callers of
|
|
.Fn namei .
|
|
It implies 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 locked 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 (UIO_SYSSPACE) or an address in user
|
|
space (UIO_USERSPACE).
|
|
The locked vnode for the pathname is returned in
|
|
.Em ndp-\*[Gt]ni_vp .
|
|
.Pp
|
|
If
|
|
.Em ndp-\*[Gt]ni_cnd.cn_flags
|
|
has the 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.
|
|
.It Fn lookup "ndp"
|
|
Search for a pathname.
|
|
This is a very central and rather complicated routine.
|
|
.Pp
|
|
The pathname is specified by
|
|
.Em ndp-\*[Gt]ni_dirp
|
|
and is of length
|
|
.Em ndp-\*[Gt]ni_pathlen .
|
|
The starting directory is taken from
|
|
.Em ndp-\*[Gt]ni_startdir .
|
|
The pathname is descended until done, or a symbolic link is
|
|
encountered.
|
|
.Pp
|
|
The semantics of
|
|
.Fn lookup
|
|
are altered by the operation specified by
|
|
.Em ndp-\*[Gt]ni_cnd.cn_nameiop .
|
|
When CREATE, RENAME, or DELETE is specified, information usable in
|
|
creating, renaming, or deleting a directory entry may be calculated.
|
|
.Pp
|
|
If
|
|
.Em ndp-\*[Gt]ci_cnd.cn_flags
|
|
has LOCKPARENT set, the parent directory is returned locked in
|
|
.Em ndp-\*[Gt]ni_dvp .
|
|
If WANTPARENT is set, the parent directory is returned unlocked.
|
|
Otherwise the parent directory is not returned.
|
|
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.
|
|
.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 unlocked 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" "l"
|
|
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 and
|
|
.Fa l
|
|
is the calling lwp.
|
|
.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.
|