216 lines
7.4 KiB
Groff
216 lines
7.4 KiB
Groff
.\" $NetBSD: namecache.9,v 1.3 2001/10/22 20:47:05 gmcgarry Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Gregory McGarry.
|
|
.\"
|
|
.\" 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. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 October 13, 2001
|
|
.Dt NAMECACHE 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm namecache ,
|
|
.Nm cache_lookup ,
|
|
.Nm cache_revlookup ,
|
|
.Nm cache_enter ,
|
|
.Nm cache_purge ,
|
|
.Nm cache_purgevfs ,
|
|
.Nm namecache_print
|
|
.Nd name lookup cache
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/namei.h>
|
|
.Fd #include <sys/proc.h>
|
|
.Fd #include <sys/uio.h>
|
|
.Fd #include <sys/vnode.h>
|
|
.Ft int
|
|
.Fn cache_lookup "struct vnode *dvp" "struct vnode **vpp" \
|
|
"struct componentname *cnp"
|
|
.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"
|
|
.Ft void
|
|
.Fn cache_purge "struct vnode *vp"
|
|
.Ft void
|
|
.Fn cache_purgevfs "struct mount *mp"
|
|
.Ft void
|
|
.Fn namecache_print "struct vnode *vp" "void (*func)(const char *, ..."
|
|
.Sh DESCRIPTION
|
|
The name lookup cache is the mechanism to allow the file system type
|
|
dependent algorithms to quickly resolve a file's vnode from its
|
|
pathname. The name lookup cache is generally accessed through the
|
|
higher-level
|
|
.Xr namei 9
|
|
interface.
|
|
.Pp
|
|
The name of the file is used to lookup 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 contains information about the file which is useful to the file
|
|
system type dependent functions.
|
|
.Pp
|
|
The name lookup cache is managed by a least recently used (LRU)
|
|
algorithm so frequently used names will hang around. The cache itself
|
|
is a hash table called
|
|
.Va nchashtbl ,
|
|
containing
|
|
.Em namecache
|
|
entries that are allocated dynamically from a kernel memory pool.
|
|
Each entry has the following structure:
|
|
.Bd -literal
|
|
#define NCHNAMLEN 31 /* maximum name segment length */
|
|
struct namecache {
|
|
LIST_ENTRY(namecache) nc_hash; /* hash chain */
|
|
TAILQ_ENTRY(namecache) nc_lru; /* LRU chain */
|
|
LIST_ENTRY(namecache) nc_vhash; /* directory hash 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
|
|
For simplicity (and economy of storage), names longer than a maximum
|
|
length of NCHNAMLEN are not cached; they occur infrequently in any
|
|
case, and are almost never of interest.
|
|
.Pp
|
|
Each
|
|
.Em namecache
|
|
entry can appear on two hash chains in addition to
|
|
.Va nshashtbl :
|
|
.Em ncvhashtbl
|
|
(the name cache directory hash chain), and
|
|
.Em nclruhead
|
|
(the name cache LRU chain). The hash chains are indexed by a hash
|
|
value obtained from the file's name and the address of its parent
|
|
directory vnode.
|
|
.Pp
|
|
Functions which access to the name cache pass arguments in the
|
|
partially initialised
|
|
.Em componentname
|
|
structure. See
|
|
.Xr vnodeops 9
|
|
for details on this structure.
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width compact
|
|
.It Fn cache_lookup "dvp" "vpp" "cnp"
|
|
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->cn_nameptr
|
|
points to the name of the entry being sought,
|
|
.Fa cnp->cn_namelen
|
|
tells the length of the name, and
|
|
.Fa cnp->cn_hash
|
|
contains a hash of the name. If the lookup succeeds, the vnode is
|
|
locked, sotred in
|
|
.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.
|
|
.It Fn cache_revlookup "vp" "dvp" "bpp" "bufp"
|
|
Scan cache looking for name of directory entry pointing at
|
|
.Fa vp
|
|
and fill in
|
|
.Fa dvpp .
|
|
If
|
|
.Fa bufp
|
|
is non-NULL, also place the name in the buffer which starts at
|
|
.Fa bufp ,
|
|
immediately before
|
|
.Fa bpp ,
|
|
and move bpp backwards to point at the start of it. Returns 0 on
|
|
success, -1 on cache miss, positive errno on failure.
|
|
.It Fn cache_enter "dvp" "vp" "cnp"
|
|
Add an entry to the cache.
|
|
.Fn cache_enter
|
|
is called with
|
|
.Fa dvp
|
|
pointing to the vnode of the directory to enter and
|
|
.Fa cnp
|
|
pointing to the partially initialised component structure.
|
|
.Fa cnp->cn_nameptr
|
|
points to the name of the entry being entered,
|
|
.Fa cnp->cn_namelen
|
|
tells the length of the name, and
|
|
.Fa cnp->cn_hash
|
|
contains a hash of the name.
|
|
.It Fn cache_purge "vp"
|
|
Flush the cache of a particular vnode
|
|
.Fa vp .
|
|
.Fn cache_purge
|
|
is called when a vnode is renamed to hide entries that would now be
|
|
invalid.
|
|
.It Fn cache_purgevfs "mp"
|
|
Flush cache of a whole file system
|
|
.Fa mp .
|
|
.Fn cache_purgevfs
|
|
is called when file system is unmounted to remove entries that would
|
|
now be invalid.
|
|
.It Fn namecache_print "vp" "func"
|
|
Print all entries of the name cache.
|
|
.Fa func
|
|
is the
|
|
.Xr printf 9
|
|
format.
|
|
.Fn namecache_print
|
|
is only defined if the kernel option DDB is compiled into the kernel.
|
|
.El
|
|
.Sh CODE REFERENCES
|
|
This section describes places within the
|
|
.Nx
|
|
source tree where actual code implementing or utilising the name
|
|
lookup cache can be found. All pathnames are relative to
|
|
.Pa /usr/src .
|
|
.Pp
|
|
The name lookup cache is implemented within the file
|
|
.Pa sys/kern/vfs_cache.c .
|
|
.Sh SEE ALSO
|
|
.Xr intro 9 ,
|
|
.Xr namei 9 ,
|
|
.Xr vfs 9 ,
|
|
.Xr vnode 9
|
|
.Sh HISTORY
|
|
The name lookup cache first appeared in
|
|
.Bx 4.2 .
|
|
.Sh AUTHORS
|
|
The original name lookup cache was written by Robert Elz.
|