Module Name: src
Committed By: dholland
Date: Mon Nov 5 17:31:16 UTC 2012
Modified Files:
src/share/man/man9: namecache.9
Log Message:
Update docs for namecache changes.
To generate a diff of this commit:
cvs rdiff -u -r1.15 -r1.16 src/share/man/man9/namecache.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/namecache.9
diff -u src/share/man/man9/namecache.9:1.15 src/share/man/man9/namecache.9:1.16
--- src/share/man/man9/namecache.9:1.15 Thu Dec 2 12:54:13 2010
+++ src/share/man/man9/namecache.9 Mon Nov 5 17:31:15 2012
@@ -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 @@ The name lookup cache is generally acces
.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 @@ See
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 @@ immediately before
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 .
