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