472351e13d
.In header.h instead of .Fd #include \*[Lt]header.h\*[Gt] Much easier to read and write, and supported by groff for ages. Okayed by ross.
221 lines
7.4 KiB
Groff
221 lines
7.4 KiB
Groff
.\" $NetBSD: namecache.9,v 1.8 2003/04/16 13:35:31 wiz 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
|
|
.In sys/namei.h
|
|
.In sys/proc.h
|
|
.In sys/uio.h
|
|
.In 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-\*[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
|
|
.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-\*[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 .
|
|
.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 using 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.
|