[src/trunk]: src/share/man/man9 Update docs for namecache changes.

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

details:   https://anonhg.NetBSD.org/src/rev/d4f97e5ab5d1
branches:  trunk
changeset: 782544:d4f97e5ab5d1
user:      dholland <dholland%NetBSD.org@localhost>
date:      Mon Nov 05 17:31:15 2012 +0000

description:
Update docs for namecache changes.

diffstat:

 share/man/man9/namecache.9 |  115 +++++++++++++++++++++++++++++++-------------
 1 files changed, 80 insertions(+), 35 deletions(-)

diffs (175 lines):

diff -r 16884403b6e8 -r d4f97e5ab5d1 share/man/man9/namecache.9
--- a/share/man/man9/namecache.9        Mon Nov 05 17:30:37 2012 +0000
+++ b/share/man/man9/namecache.9        Mon Nov 05 17:31:15 2012 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: namecache.9,v 1.15 2010/12/02 12:54:13 wiz Exp $
+.\"     $NetBSD: namecache.9,v 1.16 2012/11/05 17:31:15 dholland Exp $
 .\"
 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd July 21, 2010
+.Dd November 5, 2012
 .Dt NAMECACHE 9
 .Os
 .Sh NAME
@@ -45,14 +45,14 @@
 .In sys/uio.h
 .In sys/vnode.h
 .Ft int
-.Fn cache_lookup "struct vnode *dvp" "struct vnode **vpp" \
-"struct componentname *cnp"
+.Fn cache_lookup "struct vnode *dvp" "const char *name" "size_t namelen" \
+"uint32_t nameiop" "uint32_t nameiflags" "int *iswhiteout" "struct vnode **vpp"
 .Ft int
 .Fn cache_revlookup "struct vnode *vp" "struct vnode *dvp" \
 "char **bpp" "char *bufp"
 .Ft void
 .Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \
-"struct componentname *cnp"
+"const char *name" "size_t namelen" "uint32_t nameiflags"
 .Ft void
 .Fn cache_purge "struct vnode *vp"
 .Ft void
@@ -67,7 +67,7 @@
 .Xr namei 9
 interface.
 .Pp
-The name of the file is used to lookup an entry associated with the
+The name of the file is used to look up an entry associated with the
 file in the name lookup cache.
 If no entry is found, one is created for it.
 If an entry is found, the information obtained from the cache lookup
@@ -122,28 +122,68 @@
 for details on this structure.
 .Sh FUNCTIONS
 .Bl -tag -width compact
-.It Fn cache_lookup "dvp" "vpp" "cnp"
+.It Fn cache_lookup "dvp" "name" "namelen" "nameiop" "nameiflags" \
+"iswhiteout" "vpp"
 Look for a name in the cache.
 .Fn cache_lookup
 is called with
 .Fa dvp
-pointing to the vnode of the directory to search and
-.Fa cnp
-pointing to the partially initialised component structure.
-.Fa cnp-\*[Gt]cn_nameptr
-points to the name of the entry being sought,
-.Fa cnp-\*[Gt]cn_namelen
-tells the length of the name, and
-.Fa cnp-\*[Gt]cn_hash
-contains a hash of the name.
-If the lookup succeeds, the vnode is locked, stored in
+pointing to the vnode of the directory to search.
+The
+.Fa name
+and
+.Fa namelen
+arguments specify the name to look for.
+The
+.Fa nameiop
+and
+.Fa nameiflags
+should be taken from the
+.Fa cn_nameiop
+and
+.Fa cn_flags
+fields of struct componentname.
+.Pp
+The lookup can produce either a cache miss or a cache hit, and a cache
+hit can either be a positive hit, where the name looked up refers to
+some existing object, or a negative hit, where the name looked up is
+known to refer to
+.Em no
+existing object.
+.Pq The lookup cannot fail, in the sense of generating an error condition \
+that requires aborting the operation in progress.
+.Pp
+On a cache miss,
+.Fn cache_lookup
+returns zero
+.Pq false .
+On a positive hit, the vnode for the object found is locked and stored
+in
+.Fa vpp ,
+and a nonzero
+.Pq true
+value is returned.
+On a negative hit,
 .Fa vpp
-and a status of zero is returned.
-If the locking fails for whatever reason, the vnode is unlocked and the
-error is returned.
-If the lookup determines that the name does not exist any longer, a
-status of ENOENT is returned.
-If the lookup fails, a status of -1 is returned.
+is set to contain a null pointer and a nonzero value is returned.
+Usually a negative hit will prompt the caller to fail with ENOENT.
+.Pp
+The
+.Fa iswhiteout
+argument is a pointer to an integer result that will be set to nonzero if
+the entry represents a whiteout, and zero if it does not.
+This pointer may be
+.Dv NULL
+if the caller does not support whiteouts.
+According to the current scheme for handling whiteouts, if
+.Fn cache_lookup
+sets
+.Fa iswhiteout
+the caller should add
+.Dv ISWHITEOUT
+to the
+.Fa cn_flags
+field of its struct componentname.
 .It Fn cache_revlookup "vp" "dvp" "bpp" "bufp"
 Scan cache looking for name of directory entry pointing at
 .Fa vp
@@ -160,26 +200,31 @@
 and move bpp backwards to point at the start of it.
 If the lookup succeeds, the vnode is referenced.
 Returns 0 on success, -1 on cache miss, positive errno on failure.
-.It Fn cache_enter "dvp" "vp" "cnp"
+.It Fn cache_enter "dvp" "vp" "name" "namelen" "nameiflags"
 Add an entry to the cache.
-.Fn cache_enter
-is called with
+The 
+.Fa name
+and
+.Fa namelen
+arguments specify the name to add to the cache.
+The
 .Fa dvp
-pointing to the vnode of the directory to enter and
-.Fa cnp
-pointing to the partially initialised component structure.
+argument specifies the directory the name appears in.
+The
+.Fa vp
+argument specifies the object to enter in the cache.
+The
+.Fa nameiflags
+argument should come from the
+.Fa cn_flags
+member of struct componentname.
+.Pp
 If
 .Fa vp
 is
 .Dv NULL ,
 a negative cache entry is created, specifying that the entry
 does not exist in the file system.
-.Fa cnp-\*[Gt]cn_nameptr
-points to the name of the entry being entered,
-.Fa cnp-\*[Gt]cn_namelen
-tells the length of the name, and
-.Fa cnp-\*[Gt]cn_hash
-contains a hash of the name.
 .It Fn cache_purge "vp"
 Flush the cache of a particular vnode
 .Fa vp .