.\"     $NetBSD: namecache.9,v 1.10 2004/12/28 19:23:12 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 December 28, 2004
.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 */
        LIST_ENTRY(namecache) nc_dvlist;
        struct  vnode *nc_dvp;          /* vnode of parent of name */
        LIST_ENTRY(namecache) nc_vlist;
        struct  vnode *nc_vp;           /* vnode the name refers to */
        int     nc_flags;               /* copy of componentname's ISWHITEOUT */
        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.