[src/trunk]: src/share/man/man9 Rewrite operating modes section.

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

details:   https://anonhg.NetBSD.org/src/rev/3c5031bb1007
branches:  trunk
changeset: 822395:3c5031bb1007
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sat Mar 18 17:55:23 2017 +0000

description:
Rewrite operating modes section.

- Identify contract with caller.
- Identify contract with file system.
- Identify failure modes.
- Write in bulleted lists, not long rambly paragraphs.

diffstat:

 share/man/man9/namei.9 |  225 ++++++++++++++++++++++++++++++++++++++----------
 1 files changed, 178 insertions(+), 47 deletions(-)

diffs (249 lines):

diff -r 5eabc9e038a3 -r 3c5031bb1007 share/man/man9/namei.9
--- a/share/man/man9/namei.9    Sat Mar 18 17:07:04 2017 +0000
+++ b/share/man/man9/namei.9    Sat Mar 18 17:55:23 2017 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: namei.9,v 1.38 2017/03/18 16:12:20 riastradh Exp $
+.\"     $NetBSD: namei.9,v 1.39 2017/03/18 17:55:23 riastradh Exp $
 .\"
 .\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -201,62 +201,193 @@
 New uses of this feature are discouraged and should be discussed.
 .El
 .Ss Operating modes
-The
+Each lookup happens in one of the following modes, specified by
+callers of
+.Nm
+and specified internally by
+.Nm
+to
+.Xr VOP_LOOKUP 9 :
+.Bl -bullet -compact
+.It
+Callers of
+.Nm
+specify the mode for the last component of a lookup.
+.It
+Internally,
+.Nm
+recursively calls
+.Xr VOP_LOOKUP 9
+in
+.Dv LOOKUP
+mode for each directory component, and then finally calls
+.Xr VOP_LOOKUP 9
+in the caller-specified mode for the last component.
+.El
+Each mode can fail in different ways -- for example,
 .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,
+mode fails with
 .Er ENOENT
-is returned.
+if no entry exists, but
+.Dv CREATE
+mode succeeds with a
+.Dv NULL
+vnode.
+.Bl -tag -width LOOKUP
+.It Dv LOOKUP
+Yield the vnode for an existing entry.
+Callers specify
+.Dv LOOKUP
+for operations on existing vnodes:
+.Xr stat 2 ,
+.Xr open 2
+without
+.Dv O_CREATE ,
+etc.
 .Pp
-The
+File systems:
+.Bl -dash -compact
+.It
+MUST refuse if user lacks lookup permission for directory.
+.It
+SHOULD use
+.Xr namecache 9
+to cache lookup results.
+.El
+.Pp
+.Bl -tag -compact -width ENAMETOOLONG
+.It Bq Er ENOENT
+No entry exists.
+.El
+.It Dv CREATE
+Yield the vnode for an existing entry; or, if there is none, yield
+.Dv NULL
+and hint that it will soon be created.
+Callers specify
 .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,
-.Er 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 .
+for operations that may create directory entries:
+.Xr mkdir 2 ,
+.Xr open 2
+with
+.Dv O_CREATE ,
+etc.
+.Pp
+File systems:
+.Bl -dash -compact
+.It
+MUST refuse if user lacks lookup permission for directory.
+.It
+MUST refuse if no entry exists and user lacks write permission for
+directory.
+.It
+MUST refuse if no entry exists and file system is read-only.
+.It
+SHOULD NOT use
+.Xr namecache 9
+to cache negative lookup results.
+.It
+SHOULD save lookup hints internally in the directory for a subsequent
+operation to create a directory entry.
+.El
 .Pp
-The
+.Bl -tag -compact -width ENAMETOOLONG
+.It Bq Er EPERM
+The user lacks lookup permission for the directory.
+.It Bq Er EPERM
+No entry exists and the user lacks write permission for the directory.
+.It Bq Er EROFS
+No entry exists and the file system is read-only.
+.El
+.It Dv DELETE
+Yield the vnode of an existing entry, and hint that it will soon be
+deleted.
+Callers specify
 .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
+for operations that delete directory entries:
+.Xr unlink 2 ,
+.Xr rmdir 2 ,
+etc.
+.Pp
+File systems:
+.Bl -dash -compact
+.It
+MUST refuse if user lacks lookup permission for directory.
+.It
+MUST refuse if entry exists and user lacks write permission for
+directory.
+.It
+MUST refuse if entry exists and file system is read-only.
+.It
+SHOULD NOT use
+.Xr namecache 9
+to cache lookup results.
+.It
+SHOULD save lookup hints internally in the directory for a subsequent
+operation to delete a directory entry.
+.El
+.Pp
+.Bl -tag -compact -width ENAMETOOLONG
+.It Bq Er ENOENT
+No entry exists.
+.It Bq Er EPERM
+The user lacks lookup permission for the directory.
+.It Bq Er EPERM
+An entry exists and the user lacks write permission for the directory.
+.It Bq Er EROFS
+An entry exists and the file system is read-only.
+.El
+.It Dv RENAME
+Yield the vnode of an existing entry, and hint that it will soon be
+overwritten; or, if there is none, yield
+.Dv NULL ,
+and hint that it will soon be created.
+.Pp
+Callers specify
 .Dv RENAME
-mode is used when doing (one of the) lookups for
+for an entry that is about to be created or overwritten, namely for the
+target of
 .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
-.Dv RENAME
-by computing additional information needed to operate on directory
-entries.
-This information is consumed by the vnode operations expected to be
-called subsequently.
-If one of these modes is used (and owing to failure or whatever other
-circumstances) the eventual vnode operation is not called,
+File systems:
+.Bl -dash -compact
+.It
+MUST refuse if user lacks lookup permission for directory.
+.It
+MUST refuse if user lacks write permission for directory.
+.It
+MUST refuse if file system is read-only.
+.It
+SHOULD NOT use
+.Xr namecache 9
+to cache lookup results.
+.It
+SHOULD save lookup hints internally in the directory for a subsequent
+operation to create or overwrite a directory entry.
+.El
+.Pp
+.Bl -tag -compact -width ENAMETOOLONG
+.It Bq Er EPERM
+The user lacks lookup permission for the directory.
+.It Bq Er EPERM
+The user lacks write permission for the directory.
+.It Bq Er EROFS
+The file system is read-only.
+.El
+.El
+.Pp
+If a caller decides not to perform a operation it hinted at by a
+destructive operating mode
+.Pq Dv CREATE , Dv DELETE , No or Dv RENAME ,
+it SHOULD call
 .Xr VOP_ABORTOP 9
-should be used to ensure the state involved is cleaned up correctly.
+to release the hints.
+If a file system fails to perform such an operation, it SHOULD call
+.Xr VOP_ABORTOP 9
+to release the hints.
+However, the current code is inconsistent about this, and every
+implementation of
+.Xr VOP_ABORTOP 9
+does nothing.
 .Ss Flags
 The following flags may appear.
 Some are set by