document the VFS name cache.

lots of parts/help from and ok pedro joris jmc

2 files changed, 208 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 59d428cfef6..cc4a543bbf2 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.95 2005/06/09 02:59:12 jaredy Exp $
+#	$OpenBSD: Makefile,v 1.96 2005/06/17 15:18:55 jaredy Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -22,7 +22,7 @@ MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \
 	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 \
 	shutdownhook_establish.9 sleep.9 spl.9 startuphook_establish.9 \
 	style.9 syscall.9 systrace.9 \
-	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 \
+	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 vfs_cache.9 \
 	vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \
 	vflushbuf.9 vget.9 vgone.9 vhold.9 vinvalbuf.9 vnode.9 vnsubr.9 \
 	VOP_LOOKUP.9 vput.9 vrecycle.9 vref.9 vrele.9 vwaitforio.9 vwakeup.9 \
@@ -282,6 +282,10 @@ MLINKS+=kern.9 imax.9 kern.9 imin.9 kern.9 lmax.9 kern.9 lmin.9 \
 	kern.9 strcmp.9 kern.9 strncmp.9 kern.9 strncasecmp.9 \
 	kern.9 srandom.9 kern.9 getsn.9
 
+MLINKS+=vfs_cache.9 cache_enter.9 vfs_cache.9 cache_lookup.9 \
+	vfs_cache.9 cache_purge.9 vfs_cache.9 cache_purgevfs.9 \
+	vfs_cache.9 cache_revlookup.9
+
 MLINKS+=vnsubr.9 vn_close.9 vnsubr.9 vn_default_error.9 vnsubr.9 vn_isunder.9 \
 	vnsubr.9 vn_lock.9 vnsubr.9 vn_open.9 vnsubr.9 vn_rdwr.9 \
 	vnsubr.9 vn_stat.9 vnsubr.9 vn_writechk.9 vnsubr.9 vn_marktext.9
diff --git a/share/man/man9/vfs_cache.9 b/share/man/man9/vfs_cache.9
new file mode 100644
index 00000000000..071cf8b53e0
--- /dev/null
+++ b/share/man/man9/vfs_cache.9
@@ -0,0 +1,202 @@
+.\"	$OpenBSD: vfs_cache.9,v 1.1 2005/06/17 15:18:55 jaredy Exp $
+.\" Copyright (c) 1989, 1993
+.\"      The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"   notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"   notice, this list of conditions and the following disclaimer in the
+.\"   documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"   may be used to endorse or promote products derived from this software
+.\"   without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.Dd June 17, 2005
+.Dt VFS_CACHE 9
+.Os
+.Sh NAME
+.Nm vfs_cache ,
+.Nm cache_enter ,
+.Nm cache_lookup ,
+.Nm cache_purge ,
+.Nm cache_purgevfs ,
+.Nm cache_revlookup
+.Nd name lookup cache
+.Sh SYNOPSIS
+.In sys/vnode.h
+.In sys/namei.h
+.Pp
+.Ft int
+.Fn cache_lookup "struct vnode *dvp" "struct vnode **vpp" \
+    "struct componentname *cnp"
+.Ft void
+.Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \
+    "struct componentname *cnp"
+.Ft void
+.Fn cache_purge "struct vnode *vp"
+.Ft void
+.Fn cache_purgevfs "struct mount *mp"
+.Ft int
+.Fn cache_revlookup "struct vnode *vp" "struct vnode **dvpp" \
+    "char **bpp" "char *bufp"
+.Sh DESCRIPTION
+In order to speed up file name look-up operations (see
+.Xr VOP_LOOKUP 9 ) ,
+the kernel provides an interface for maintaining a cache of the most
+recently looked-up file name translations.
+Entries in this cache have the following definition:
+.Bd -literal
+struct	namecache {
+	LIST_ENTRY(namecache) nc_hash;	/* hash chain */
+	LIST_ENTRY(namecache) nc_vhash;	/* (reverse) dir hash chain */
+	TAILQ_ENTRY(namecache) nc_lru;	/* LRU chain */
+	struct	vnode *nc_dvp;		/* vnode of parent of name */
+	u_long	nc_dvpid;		/* capability number of nc_dvp */
+	struct	vnode *nc_vp;		/* vnode the name refers to */
+	u_long	nc_vpid;		/* capability number of nc_vp */
+	char	nc_nlen;		/* length of name */
+	char	nc_name[NCHNAMLEN];	/* segment name */
+};
+.Ed
+.Pp
+The cache is indexed by a hash value based on the file's base name and
+its encompassing directory's vnode generation number.
+Negative caching is also performed so that frequently accessed path
+names of files that do not exist do not result in expensive lookups.
+.Pp
+For simplicity and economy of storage, names longer than the maximum
+length
+.Dv NCHNAMLEN
+are not cached; they occur infrequently in any case, and are almost
+never of interest.
+.Pp
+The
+.Nm vfs_cache
+API contains the following routines:
+.Bl -tag -width Ds
+.It Fn cache_lookup dvp vpp cnp
+Look up the given name in the cache.
+.Fa dvp
+points to the directory to search,
+.Fa vpp
+points to a pointer where the vnode of the name being sought will be
+stored, and
+.Fa cnp
+contains the last component of the path name.
+.Fa cnp
+must have the
+.Va cn_nameptr ,
+.Va cn_namelen ,
+and
+.Va cn_hash
+fields filled in.
+If no entry is found for the given name, a new one will be created,
+even if the path name fails (i.e. it will be negative cached), unless
+the
+.Xr namei 9
+lookup operation was
+.Dv DELETE
+or the
+.Dv NOCACHE
+flag was set for the call to
+.Xr namei 9 .
+.Pp
+Upon success, a pointer to a locked vnode is stored in
+.Fa vpp
+and a zero value is returned.
+If locking the vnode fails, the vnode will remain unlocked,
+.Fa *vpp
+will be set to
+.Dv NULL ,
+and the corresponding error will be returned.
+If the cache entry is negative cached, meaning the name is no longer
+valid,
+.Er ENOENT
+is returned.
+Otherwise, the cache lookup has failed and a \-1 value is returned.
+.It Fn cache_enter dvp vp cnp
+Add a new entry for the translation in the directory
+.Fa dvp
+for the vnode
+.Fa vp
+with name
+.Fa cnp
+to the cache.
+.Fa cnp
+must have the
+.Va cn_nameptr ,
+.Va cn_namelen ,
+and
+.Va cn_hash
+fields filled in.
+.It Fn cache_purge vp
+Flush all cache entries corresponding with the given vnode
+.Fa vp .
+This is called after rename operations to hide entries that would no
+longer be valid.
+.It Fn cache_purgevfs mp
+Flush all cache entries for name translations associated with the file
+system mount described by
+.Fa mp .
+This is called when unmounting file systems, which would make all name
+translations pertaining to the mount invalid.
+.It Fn cache_revlookup vp dvpp bpp bufp
+Scan the cache for the name of the directory entry that points to
+.Fa vp .
+.Fa dvpp
+points to where a pointer to the encompassing directory will be stored.
+If
+.Fa bufp
+is not
+.Dv NULL ,
+the name will be written to the end of the space between this pointer
+and the value in
+.Fa bpp ,
+and
+.Fa bpp
+will be updated on return to point to the start of the copied name.
+.Pp
+On success,
+.Fa *dvpp
+will be set to point to the encompassing directory and zero will be
+returned.
+If the cache misses,
+.Fa dvpp
+will be set to
+.Dv NULL
+and \-1 will be returned.
+Otherwise, failure has occurred,
+.Fa dvpp
+will be set to
+.Dv NULL ,
+and an appropriate error code will be returned.
+.El
+.Sh CODE REFERENCES
+The
+.Nm
+API is implemented in the file
+.Pa sys/kern/vfs_cache.c .
+.Sh SEE ALSO
+.Xr vmstat 8 ,
+.Xr namei 9 ,
+.Xr vfs 9 ,
+.Xr vnode 9
+.Sh HISTORY
+The
+.Nm
+API first appeared in
+.Bx 4.2 .