namei/lookup/relookpu/NDINIT page from netbsd; will enable w/ some other shitz coming soon

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.