1.\" $NetBSD: namecache.9,v 1.11 2007/06/25 16:33:50 rumble 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 June 25, 2007 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. 175If 176.Fa vp 177is NULL, a negative cache entry is created, specifying that the entry 178does not exist in the file system. 179.Fa cnp-\*[Gt]cn_nameptr 180points to the name of the entry being entered, 181.Fa cnp-\*[Gt]cn_namelen 182tells the length of the name, and 183.Fa cnp-\*[Gt]cn_hash 184contains a hash of the name. 185.It Fn cache_purge "vp" 186Flush the cache of a particular vnode 187.Fa vp . 188.Fn cache_purge 189is called when a vnode is renamed to hide entries that would now be 190invalid. 191.It Fn cache_purgevfs "mp" 192Flush cache of a whole file system 193.Fa mp . 194.Fn cache_purgevfs 195is called when file system is unmounted to remove entries that would 196now be invalid. 197.It Fn namecache_print "vp" "func" 198Print all entries of the name cache. 199.Fa func 200is the 201.Xr printf 9 202format. 203.Fn namecache_print 204is only defined if the kernel option DDB is compiled into the kernel. 205.El 206.Sh CODE REFERENCES 207This section describes places within the 208.Nx 209source tree where actual code implementing or using the name 210lookup cache can be found. 211All pathnames are relative to 212.Pa /usr/src . 213.Pp 214The name lookup cache is implemented within the file 215.Pa sys/kern/vfs_cache.c . 216.Sh SEE ALSO 217.Xr intro 9 , 218.Xr namei 9 , 219.Xr vfs 9 , 220.Xr vnode 9 221.Sh HISTORY 222The name lookup cache first appeared in 223.Bx 4.2 . 224.Sh AUTHORS 225The original name lookup cache was written by Robert Elz. 226