Module Name: src
Committed By: riastradh
Date: Sat Mar 18 17:55:23 UTC 2017
Modified Files:
src/share/man/man9: namei.9
Log Message:
Rewrite operating modes section.
- Identify contract with caller.
- Identify contract with file system.
- Identify failure modes.
- Write in bulleted lists, not long rambly paragraphs.
To generate a diff of this commit:
cvs rdiff -u -r1.38 -r1.39 src/share/man/man9/namei.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/namei.9
diff -u src/share/man/man9/namei.9:1.38 src/share/man/man9/namei.9:1.39
--- src/share/man/man9/namei.9:1.38 Sat Mar 18 16:12:20 2017
+++ src/share/man/man9/namei.9 Sat Mar 18 17:55:23 2017
@@ -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 @@ are being consumed.
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 is the baseline behavior, for all ordinary lookups that simply
-return a vnode.
-In this mode, if the requested object does not exist,
+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 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
-The
+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
+.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
+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
-should be used to ensure the state involved is cleaned up correctly.
+does nothing.
.Ss Flags
The following flags may appear.
Some are set by
