1.\" $NetBSD: namecache.9,v 1.10 2004/12/28 19:23:12 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd December 28, 2004 38.Dt NAMECACHE 9 39.Os 40.Sh NAME 41.Nm namecache , 42.Nm cache_lookup , 43.Nm cache_revlookup , 44.Nm cache_enter , 45.Nm cache_purge , 46.Nm cache_purgevfs , 47.Nm namecache_print 48.Nd name lookup cache 49.Sh SYNOPSIS 50.In sys/namei.h 51.In sys/proc.h 52.In sys/uio.h 53.In sys/vnode.h 54.Ft int 55.Fn cache_lookup "struct vnode *dvp" "struct vnode **vpp" \ 56"struct componentname *cnp" 57.Ft int 58.Fn cache_revlookup "struct vnode *vp" "struct vnode *dvp" \ 59"char **bpp" "char *bufp" 60.Ft void 61.Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \ 62"struct componentname *cnp" 63.Ft void 64.Fn cache_purge "struct vnode *vp" 65.Ft void 66.Fn cache_purgevfs "struct mount *mp" 67.Ft void 68.Fn namecache_print "struct vnode *vp" "void (*func)(const char *, ...)" 69.Sh DESCRIPTION 70The name lookup cache is the mechanism to allow the file system type 71dependent algorithms to quickly resolve a file's vnode from its 72pathname. 73The name lookup cache is generally accessed through the higher-level 74.Xr namei 9 75interface. 76.Pp 77The name of the file is used to lookup an entry associated with the 78file in the name lookup cache. 79If no entry is found, one is created for it. 80If an entry is found, the information obtained from the cache lookup 81contains information about the file which is useful to the file system 82type dependent functions. 83.Pp 84The name lookup cache is managed by a least recently used (LRU) 85algorithm so frequently used names will hang around. 86The cache itself is a hash table called 87.Va nchashtbl , 88containing 89.Em namecache 90entries that are allocated dynamically from a kernel memory pool. 91Each entry has the following structure: 92.Bd -literal 93#define NCHNAMLEN 31 /* maximum name segment length */ 94struct namecache { 95 LIST_ENTRY(namecache) nc_hash; /* hash chain */ 96 TAILQ_ENTRY(namecache) nc_lru; /* LRU chain */ 97 LIST_ENTRY(namecache) nc_vhash; /* directory hash chain */ 98 LIST_ENTRY(namecache) nc_dvlist; 99 struct vnode *nc_dvp; /* vnode of parent of name */ 100 LIST_ENTRY(namecache) nc_vlist; 101 struct vnode *nc_vp; /* vnode the name refers to */ 102 int nc_flags; /* copy of componentname's ISWHITEOUT */ 103 char nc_nlen; /* length of name */ 104 char nc_name[NCHNAMLEN]; /* segment name */ 105}; 106.Ed 107.Pp 108For simplicity (and economy of storage), names longer than a maximum 109length of NCHNAMLEN are not cached; they occur infrequently in any 110case, and are almost never of interest. 111.Pp 112Each 113.Em namecache 114entry can appear on two hash chains in addition to 115.Va nshashtbl : 116.Em ncvhashtbl 117(the name cache directory hash chain), and 118.Em nclruhead 119(the name cache LRU chain). 120The hash chains are indexed by a hash value obtained from the file's 121name and the address of its parent directory vnode. 122.Pp 123Functions which access to the name cache pass arguments in the 124partially initialised 125.Em componentname 126structure. 127See 128.Xr vnodeops 9 129for details on this structure. 130.Sh FUNCTIONS 131.Bl -tag -width compact 132.It Fn cache_lookup "dvp" "vpp" "cnp" 133Look for a name in the cache. 134.Fn cache_lookup 135is called with 136.Fa dvp 137pointing to the vnode of the directory to search and 138.Fa cnp 139pointing to the partially initialised component structure. 140.Fa cnp-\*[Gt]cn_nameptr 141points to the name of the entry being sought, 142.Fa cnp-\*[Gt]cn_namelen 143tells the length of the name, and 144.Fa cnp-\*[Gt]cn_hash 145contains a hash of the name. 146If the lookup succeeds, the vnode is locked, stored in 147.Fa vpp 148and a status of zero is returned. 149If the locking fails for whatever reason, the vnode is unlocked and the 150error is returned. 151If the lookup determines that the name does not exist any longer, a 152status of ENOENT is returned. 153If the lookup fails, a status of -1 is returned. 154.It Fn cache_revlookup "vp" "dvp" "bpp" "bufp" 155Scan cache looking for name of directory entry pointing at 156.Fa vp 157and fill in 158.Fa dvpp . 159If 160.Fa bufp 161is non-NULL, also place the name in the buffer which starts at 162.Fa bufp , 163immediately before 164.Fa bpp , 165and move bpp backwards to point at the start of it. 166Returns 0 on success, -1 on cache miss, positive errno on failure. 167.It Fn cache_enter "dvp" "vp" "cnp" 168Add an entry to the cache. 169.Fn cache_enter 170is called with 171.Fa dvp 172pointing to the vnode of the directory to enter and 173.Fa cnp 174pointing to the partially initialised component structure. 175.Fa cnp-\*[Gt]cn_nameptr 176points to the name of the entry being entered, 177.Fa cnp-\*[Gt]cn_namelen 178tells the length of the name, and 179.Fa cnp-\*[Gt]cn_hash 180contains a hash of the name. 181.It Fn cache_purge "vp" 182Flush the cache of a particular vnode 183.Fa vp . 184.Fn cache_purge 185is called when a vnode is renamed to hide entries that would now be 186invalid. 187.It Fn cache_purgevfs "mp" 188Flush cache of a whole file system 189.Fa mp . 190.Fn cache_purgevfs 191is called when file system is unmounted to remove entries that would 192now be invalid. 193.It Fn namecache_print "vp" "func" 194Print all entries of the name cache. 195.Fa func 196is the 197.Xr printf 9 198format. 199.Fn namecache_print 200is only defined if the kernel option DDB is compiled into the kernel. 201.El 202.Sh CODE REFERENCES 203This section describes places within the 204.Nx 205source tree where actual code implementing or using the name 206lookup cache can be found. 207All pathnames are relative to 208.Pa /usr/src . 209.Pp 210The name lookup cache is implemented within the file 211.Pa sys/kern/vfs_cache.c . 212.Sh SEE ALSO 213.Xr intro 9 , 214.Xr namei 9 , 215.Xr vfs 9 , 216.Xr vnode 9 217.Sh HISTORY 218The name lookup cache first appeared in 219.Bx 4.2 . 220.Sh AUTHORS 221The original name lookup cache was written by Robert Elz. 222