[src/trunk]: src/share/man/man9 Revise/update. List the functions in a sensib...

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/136c4437a953
branches:  trunk
changeset: 345066:136c4437a953
user:      dholland <dholland%NetBSD.org@localhost>
date:      Fri May 06 04:55:10 2016 +0000

description:
Revise/update. List the functions in a sensible order. Document all
the modes and flags. Document the structure fields properly.
Distinguish internals from public interfaces. Mention historic dead
flags like SAVESTART because they still exist in other projects.
Explain the current layout of vfs_lookup.c, or at least the primary
points of it.

Etc.

This ended up being a much larger rewrite than I intended.

Bump date again.

diffstat:

 share/man/man9/namei.9 |  889 ++++++++++++++++++++++++++++++++++++------------
 1 files changed, 655 insertions(+), 234 deletions(-)

diffs (truncated from 1002 to 300 lines):

diff -r 238dc95029b7 -r 136c4437a953 share/man/man9/namei.9
--- a/share/man/man9/namei.9    Fri May 06 04:46:17 2016 +0000
+++ b/share/man/man9/namei.9    Fri May 06 04:55:10 2016 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: namei.9,v 1.35 2016/05/05 17:06:41 salazar Exp $
+.\"     $NetBSD: namei.9,v 1.36 2016/05/06 04:55:10 dholland Exp $
 .\"
 .\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,43 +27,42 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd May 05, 2016
+.Dd May 6, 2016
 .Dt NAMEI 9
 .Os
 .Sh NAME
 .Nm namei ,
-.Nm lookup_for_nfsd ,
-.Nm lookup_for_nfsd_index ,
-.Nm relookup ,
 .Nm NDINIT ,
 .Nm NDAT ,
 .Nm namei_simple_kernel ,
 .Nm namei_simple_user
+.Nm relookup ,
+.Nm lookup_for_nfsd ,
+.Nm lookup_for_nfsd_index ,
 .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" \
 "struct pathbuf *pathbuf"
 .Fn NDAT "struct nameidata *ndp" "struct vnode *dvp"
 .Ft int
+.Fn namei "struct nameidata *ndp"
+.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"
+.Ft int
+.Fn relookup "struct vnode *dvp" "struct vnode **vpp" \
+"struct componentname *cnp"
+.Ft int
+.Fn lookup_for_nfsd "struct nameidata *ndp" "struct vnode *startdir" \
+"int neverfollow"
+.Ft int
+.Fn lookup_for_nfsd_index "struct nameidata *ndp"
 .Sh DESCRIPTION
 The
 .Nm
@@ -81,39 +80,61 @@
 encapsulated in the
 .Em nameidata
 structure.
-It has the following layout:
-.Bd -literal
-struct nameidata {
-       /*
-        * Arguments to namei/lookup.
-        */
-       struct vnode *ni_atdir;         /* startup dir, cwd if null */
-       struct pathbuf *ni_pathbuf;     /* pathname container */
-       char *ni_pnbuf;                 /* extra pathname buffer ref (XXX) */
-       /*
-        * Arguments to lookup.
-        */
-       struct  vnode *ni_rootdir;      /* logical root directory */
-       struct  vnode *ni_erootdir;     /* emulation root directory */
-       /*
-        * Results: returned from/manipulated by lookup
-        */
-       struct  vnode *ni_vp;           /* vnode of result */
-       struct  vnode *ni_dvp;          /* vnode of intermediate directory */
-       /*
-        * Shared between namei and lookup/commit routines.
-        */
-       size_t          ni_pathlen;     /* remaining chars in path */
-       const char      *ni_next;       /* next location in pathname */
-       unsigned int    ni_loopcnt;     /* count of symlinks encountered */
-       /*
-        * Lookup parameters: this structure describes the subset of
-        * information from the nameidata structure that is passed
-        * through the VOP interface.
-        */
-       struct componentname ni_cnd;
-};
-.Ed
+The public interface to this structure is as follows.
+.Bl -offset indent
+.It
+It contains a member
+.Em ni_erootdir
+that may be set to the emulation root directory before the call if
+the
+.Dv EMULROOTSET
+flag is also set and
+.Dv TRYEMULROOT
+is in effect.
+This is only necessary (or allowed) if the emulation root is not yet
+set in the current process.
+.It
+It contains a member
+.Em ni_vp
+that upon successful return contains the result vnode.
+.It
+It contains a member
+.Em ni_dvp
+that upon successful return contains the vnode of the directory
+containing the result vnode or
+.Dv NULL .
+If the
+.Dv LOCKPARENT
+flag is set, the containing vnode is returned; otherwise this field is
+left set to
+.Dv NULL .
+.It
+It contains a member
+.Em ni_cnd
+that is a
+.Em componentname
+structure (described in just a moment).
+This may be used by callers to pass to certain vnode operations that
+operate on pathnames.
+.El
+.Pp
+The other fields in the structure should not be examined or altered
+directly.
+Note that the
+.Xr nfs 4
+code misuses the
+.Em nameidata
+structure and currently has an incestuous relationship with the
+.Nm
+code.
+This is gradually being cleaned up.
+Other code should initialize the
+.Em nameidata
+structure with the
+.Fn NDINIT
+macro and perhaps also the
+.Fn NDAT
+macro.
 .Pp
 The
 .Em componentname
@@ -121,186 +142,288 @@
 .Bd -literal
 struct componentname {
        /*
-        * Arguments to lookup.
+        * Arguments to VOP_LOOKUP and directory VOP routines.
         */
        uint32_t        cn_nameiop;     /* namei operation */
        uint32_t        cn_flags;       /* flags to namei */
        kauth_cred_t    cn_cred;        /* credentials */
-       /*
-        * Shared between lookup and commit routines.
-        */
        const char      *cn_nameptr;    /* pointer to looked up name */
        size_t          cn_namelen;     /* length of looked up comp */
+       /*
+        * Side result from VOP_LOOKUP.
+        */
        size_t          cn_consume;     /* chars to consume in lookup */
 };
 .Ed
+This structure contains the information about a single directory
+component name, along with certain other information required by vnode
+operations.
+See
+.Xr vnodeops 9
+for more information about these vnode operations.
+.Pp
+The members:
+.Bl -tag -offset indent -width cn_consumexx -compact
+.It cn_nameiop
+The type of operation in progress; indicates the basic operating mode
+of namei.
+May be one of
+.Dv LOOKUP ,
+.Dv CREATE ,
+.Dv DELETE ,
+or
+.Dv RENAME .
+These modes are described below.
+.It cn_flags
+Additional flags affecting the operation of namei.
+These are described below as well.
+.It cn_cred
+The credentials to use for the lookup or other operation the
+.Em componentname
+is passed to.
+This may match the credentials of the current process or it may not,
+depending on where the original operation request came from and how it
+has been routed.
+.It cn_nameptr
+The name of this directory component, followed by the rest of the path
+being looked up.
+.It cn_namelen
+The length of the name of this directory component.
+The name is not in general null terminated, although the complete
+string (the full remaining path) always is.
+.It cn_consume
+This field starts at zero; it may be set to a larger value by
+implementations of
+.Xr VOP_LOOKUP 9
+to indicate how many more characters beyond
+.Em cn_namelen
+are being consumed.
+New uses of this feature are discouraged and should be discussed.
+.El
+.Ss Operating modes
+The
+.Dv LOOKUP
+mode is the baseline behavior, for all ordinary lookups that simply
+return a vnode.
+In this mode, if the requested object does not exist,
+.Dv ENOENT
+is returned.
 .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 .
+.Dv CREATE
+mode is used when doing the lookup for operations that create names in
+the file system namespace, such as
+.Xr mkdir 2 .
+In this mode, if the requested name already exists,
+.Dv EEXIST
+is returned.
+Otherwise if the requested name does not exist, the lookup succeeds
+and the returned vnode
+.Em ni_vp
+is set to
+.Dv NULL .
 .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
+.Dv DELETE
+mode is used when doing the lookup for operations that remove names
+from the file system namespace, such as
+.Xr rmdir 2 ;
+and the
+.Dv RENAME
+mode is used when doing (one of the) lookups for
+.Xr rename 2 .
+.Pp
+The mode may affect both the
+.Xr VOP_LOOKUP 9
+implementation of the file system involved and the internal operation
+of
+.Nm ,
+such as interactions with the
+.Xr namecache 9 .
+In
+.Xr ffs 4 ,
+for example, the
+.Xr VOP_LOOKUP 9
+implementation reacts to
+.Dv CREATE ,
+.Dv DELETE ,
+and