1.\" $NetBSD: namecache.9,v 1.4 2002/02/13 08:18:46 ross 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 October 13, 2001 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.Fd #include \*[Lt]sys/namei.h\*[Gt] 51.Fd #include \*[Lt]sys/proc.h\*[Gt] 52.Fd #include \*[Lt]sys/uio.h\*[Gt] 53.Fd #include \*[Lt]sys/vnode.h\*[Gt] 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. The name lookup cache is generally accessed through the 73higher-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. If no entry is found, one is created 79for it. If an entry is found, the information obtained from the cache 80lookup contains information about the file which is useful to the file 81system type dependent functions. 82.Pp 83The name lookup cache is managed by a least recently used (LRU) 84algorithm so frequently used names will hang around. The cache itself 85is a hash table called 86.Va nchashtbl , 87containing 88.Em namecache 89entries that are allocated dynamically from a kernel memory pool. 90Each entry has the following structure: 91.Bd -literal 92#define NCHNAMLEN 31 /* maximum name segment length */ 93struct namecache { 94 LIST_ENTRY(namecache) nc_hash; /* hash chain */ 95 TAILQ_ENTRY(namecache) nc_lru; /* LRU chain */ 96 LIST_ENTRY(namecache) nc_vhash; /* directory hash chain */ 97 struct vnode *nc_dvp; /* vnode of parent of name */ 98 u_long nc_dvpid; /* capability number of nc_dvp */ 99 struct vnode *nc_vp; /* vnode the name refers to */ 100 u_long nc_vpid; /* capability number of nc_vp */ 101 char nc_nlen; /* length of name */ 102 char nc_name[NCHNAMLEN]; /* segment name */ 103}; 104.Ed 105.Pp 106For simplicity (and economy of storage), names longer than a maximum 107length of NCHNAMLEN are not cached; they occur infrequently in any 108case, and are almost never of interest. 109.Pp 110Each 111.Em namecache 112entry can appear on two hash chains in addition to 113.Va nshashtbl : 114.Em ncvhashtbl 115(the name cache directory hash chain), and 116.Em nclruhead 117(the name cache LRU chain). The hash chains are indexed by a hash 118value obtained from the file's name and the address of its parent 119directory vnode. 120.Pp 121Functions which access to the name cache pass arguments in the 122partially initialised 123.Em componentname 124structure. See 125.Xr vnodeops 9 126for details on this structure. 127.Sh FUNCTIONS 128.Bl -tag -width compact 129.It Fn cache_lookup "dvp" "vpp" "cnp" 130Look for a name in the cache. 131.Fn cache_lookup 132is called with 133.Fa dvp 134pointing to the vnode of the directory to search and 135.Fa cnp 136pointing to the partially initialised component structure. 137.Fa cnp-\*[Gt]cn_nameptr 138points to the name of the entry being sought, 139.Fa cnp-\*[Gt]cn_namelen 140tells the length of the name, and 141.Fa cnp-\*[Gt]cn_hash 142contains a hash of the name. If the lookup succeeds, the vnode is 143locked, sotred in 144.Fa vpp 145and a status of zero is returned. If the locking fails for whatever 146reason, the vnode is unlocked and the error is returned. If the 147lookup determines that the name does not exist any longer, a status of 148ENOENT is returned. If the lookup fails, a status of -1 is returned. 149.It Fn cache_revlookup "vp" "dvp" "bpp" "bufp" 150Scan cache looking for name of directory entry pointing at 151.Fa vp 152and fill in 153.Fa dvpp . 154If 155.Fa bufp 156is non-NULL, also place the name in the buffer which starts at 157.Fa bufp , 158immediately before 159.Fa bpp , 160and move bpp backwards to point at the start of it. Returns 0 on 161success, -1 on cache miss, positive errno on failure. 162.It Fn cache_enter "dvp" "vp" "cnp" 163Add an entry to the cache. 164.Fn cache_enter 165is called with 166.Fa dvp 167pointing to the vnode of the directory to enter and 168.Fa cnp 169pointing to the partially initialised component structure. 170.Fa cnp-\*[Gt]cn_nameptr 171points to the name of the entry being entered, 172.Fa cnp-\*[Gt]cn_namelen 173tells the length of the name, and 174.Fa cnp-\*[Gt]cn_hash 175contains a hash of the name. 176.It Fn cache_purge "vp" 177Flush the cache of a particular vnode 178.Fa vp . 179.Fn cache_purge 180is called when a vnode is renamed to hide entries that would now be 181invalid. 182.It Fn cache_purgevfs "mp" 183Flush cache of a whole file system 184.Fa mp . 185.Fn cache_purgevfs 186is called when file system is unmounted to remove entries that would 187now be invalid. 188.It Fn namecache_print "vp" "func" 189Print all entries of the name cache. 190.Fa func 191is the 192.Xr printf 9 193format. 194.Fn namecache_print 195is only defined if the kernel option DDB is compiled into the kernel. 196.El 197.Sh CODE REFERENCES 198This section describes places within the 199.Nx 200source tree where actual code implementing or utilising the name 201lookup cache can be found. All pathnames are relative to 202.Pa /usr/src . 203.Pp 204The name lookup cache is implemented within the file 205.Pa sys/kern/vfs_cache.c . 206.Sh SEE ALSO 207.Xr intro 9 , 208.Xr namei 9 , 209.Xr vfs 9 , 210.Xr vnode 9 211.Sh HISTORY 212The name lookup cache first appeared in 213.Bx 4.2 . 214.Sh AUTHORS 215The original name lookup cache was written by Robert Elz. 216