c398ae9734
- LOCKPARENT is no longer relevant for lookup(), relookup() or VOP_LOOKUP(). these now always return the parent vnode locked. namei() works as before. lookup() and various other paths no longer acquire vnode locks in the wrong order via vrele(). fixes PR 32535. as a nice side effect, path lookup is also up to 25% faster. - the above allows us to get rid of PDIRUNLOCK. - also get rid of WANTPARENT (just use LOCKPARENT and unlock it). - remove an assumption in layer_node_find() that all file systems implement a recursive VOP_LOCK() (unionfs doesn't). - require that all file systems supply vfs_vptofh and vfs_fhtovp routines. fill in eopnotsupp() for file systems that don't support being exported and remove the checks for NULL. (layerfs calls these without checking.) - in union_lookup1(), don't change refcounts in the ISDOTDOT case, just adjust which vnode is locked. fixes PR 33374. - apply fixes for ufs_rename() from ufs_vnops.c rev. 1.61 to ext2fs_rename().
310 lines
9.1 KiB
Groff
310 lines
9.1 KiB
Groff
.\" $NetBSD: namei.9,v 1.13 2006/12/09 16:11:50 chs 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 CREATEDIR
|
|
trailing slashes are ok
|
|
.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
|
|
The parent directory is returned locked in
|
|
.Em ndp-\*[Gt]ni_dvp .
|
|
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 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" "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.
|