diff options
| -rw-r--r-- | share/man/man9/namei.9 | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/share/man/man9/namei.9 b/share/man/man9/namei.9 new file mode 100644 index 00000000000..a66f707062f --- /dev/null +++ b/share/man/man9/namei.9 @@ -0,0 +1,307 @@ +.\" $OpenBSD: namei.9,v 1.1 2003/07/21 23:52:36 mickey Exp $ +.\" $NetBSD: namei.9,v 1.9 2003/05/06 10:46:44 jmmv Exp $ +.\" +.\" Copyright (c) 2001 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 October 13, 2001 +.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/proc.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 proc *p" +.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 inode. +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" "p" +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 p +is the calling process. +.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. |