1.\" $NetBSD: namecache.9,v 1.21 2017/04/19 11:33:01 abhinav 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd February 7, 2014 31.Dt NAMECACHE 9 32.Os 33.Sh NAME 34.Nm namecache , 35.Nm cache_lookup , 36.Nm cache_revlookup , 37.Nm cache_enter , 38.Nm cache_purge , 39.Nm cache_purgevfs , 40.Nm namecache_print 41.Nd name lookup cache 42.Sh SYNOPSIS 43.In sys/namei.h 44.In sys/proc.h 45.In sys/uio.h 46.In sys/vnode.h 47.Ft int 48.Fn cache_lookup "struct vnode *dvp" "const char *name" "size_t namelen" \ 49"uint32_t nameiop" "uint32_t nameiflags" "int *iswhiteout" "struct vnode **vpp" 50.Ft int 51.Fn cache_revlookup "struct vnode *vp" "struct vnode *dvp" \ 52"char **bpp" "char *bufp" 53.Ft void 54.Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \ 55"const char *name" "size_t namelen" "uint32_t nameiflags" 56.Ft void 57.Fn cache_purge "struct vnode *vp" 58.Ft void 59.Fn cache_purgevfs "struct mount *mp" 60.Ft void 61.Fn namecache_print "struct vnode *vp" "void (*func)(const char *, ...)" 62.Sh DESCRIPTION 63The name lookup cache is the mechanism to allow the file system type 64dependent algorithms to quickly resolve a file's vnode from its 65pathname. 66The name lookup cache is generally accessed through the higher-level 67.Xr namei 9 68interface. 69.Pp 70The name of the file is used to look up an entry associated with the 71file in the name lookup cache. 72If no entry is found, one is created for it. 73If an entry is found, the information obtained from the cache lookup 74contains information about the file which is useful to the file system 75type dependent functions. 76.Pp 77The name lookup cache is managed by a least recently used (LRU) 78algorithm so frequently used names will hang around. 79The cache itself is a hash table called 80.Va nchashtbl , 81containing 82.Em namecache 83entries that are allocated dynamically from a kernel memory pool. 84Each entry has the following structure: 85.Bd -literal 86#define NCHNAMLEN 31 /* maximum name segment length */ 87struct namecache { 88 LIST_ENTRY(namecache) nc_hash; /* hash chain */ 89 TAILQ_ENTRY(namecache) nc_lru; /* LRU chain */ 90 LIST_ENTRY(namecache) nc_vhash; /* directory hash chain */ 91 LIST_ENTRY(namecache) nc_dvlist; 92 struct vnode *nc_dvp; /* vnode of parent of name */ 93 LIST_ENTRY(namecache) nc_vlist; 94 struct vnode *nc_vp; /* vnode the name refers to */ 95 int nc_flags; /* copy of componentname's ISWHITEOUT */ 96 char nc_nlen; /* length of name */ 97 char nc_name[NCHNAMLEN]; /* segment name */ 98}; 99.Ed 100.Pp 101For simplicity (and economy of storage), names longer than a maximum 102length of NCHNAMLEN are not cached; they occur infrequently in any 103case, and are almost never of interest. 104.Pp 105Each 106.Em namecache 107entry can appear on two hash chains in addition to 108.Va nchashtbl : 109.Em ncvhashtbl 110(the name cache directory hash chain), and 111.Em nclruhead 112(the name cache LRU chain). 113The hash chains are indexed by a hash value obtained from the file's 114name and the address of its parent directory vnode. 115.Pp 116Functions which access to the name cache pass arguments in the 117partially initialised 118.Em componentname 119structure. 120See 121.Xr vnodeops 9 122for details on this structure. 123.Sh FUNCTIONS 124.Bl -tag -width abcd 125.It Fn cache_lookup "dvp" "name" "namelen" "nameiop" "nameiflags" \ 126"iswhiteout" "vpp" 127Look for a name in the cache. 128.Fn cache_lookup 129is called with 130.Fa dvp 131pointing to the vnode of the directory to search. 132The 133.Fa name 134and 135.Fa namelen 136arguments specify the name to look for. 137The 138.Fa nameiop 139and 140.Fa nameiflags 141should be taken from the 142.Fa cn_nameiop 143and 144.Fa cn_flags 145fields of struct componentname. 146.Pp 147The lookup can produce either a cache miss or a cache hit, and a cache 148hit can either be a positive hit, where the name looked up refers to 149some existing object, or a negative hit, where the name looked up is 150known to refer to 151.Em no 152existing object. 153(The lookup cannot fail, in the sense of generating an error condition 154that requires aborting the operation in progress.) 155.Pp 156On a cache miss, 157.Fn cache_lookup 158returns zero 159.Pq false . 160On a positive hit, the unlocked vnode for the object found is stored in 161.Fa vpp , 162and a nonzero 163.Pq true 164value is returned. 165On a negative hit, 166.Fa vpp 167is set to contain a null pointer and a nonzero value is returned. 168Usually a negative hit will prompt the caller to fail with 169.Er ENOENT . 170.Pp 171The 172.Fa iswhiteout 173argument is a pointer to an integer result that will be set to nonzero if 174the entry represents a whiteout, and zero if it does not. 175This pointer may be 176.Dv NULL 177if the caller does not support whiteouts. 178According to the current scheme for handling whiteouts, if 179.Fn cache_lookup 180sets 181.Fa iswhiteout 182the caller should add 183.Dv ISWHITEOUT 184to the 185.Fa cn_flags 186field of its struct componentname. 187.It Fn cache_revlookup "vp" "dvp" "bpp" "bufp" 188Scan cache looking for name of directory entry pointing at 189.Fa vp 190and fill in 191.Fa dvpp . 192If 193.Fa bufp 194is 195.Pf non- Dv NULL , 196also place the name in the buffer which starts at 197.Fa bufp , 198immediately before 199.Fa bpp , 200and move bpp backwards to point at the start of it. 201If the lookup succeeds, the vnode is referenced. 202Returns 0 on success, -1 on cache miss, positive errno on failure. 203.It Fn cache_enter "dvp" "vp" "name" "namelen" "nameiflags" 204Add an entry to the cache. 205The 206.Fa name 207and 208.Fa namelen 209arguments specify the name to add to the cache. 210The 211.Fa dvp 212argument specifies the directory the name appears in. 213The 214.Fa vp 215argument specifies the object to enter in the cache. 216The 217.Fa nameiflags 218argument should come from the 219.Fa cn_flags 220member of struct componentname. 221.Pp 222If 223.Fa vp 224is 225.Dv NULL , 226a negative cache entry is created, specifying that the entry 227does not exist in the file system. 228.It Fn cache_purge "vp" 229Flush the cache of a particular vnode 230.Fa vp . 231.Fn cache_purge 232is called when a vnode is renamed to hide entries that would now be 233invalid. 234.It Fn cache_purgevfs "mp" 235Flush cache of a whole file system 236.Fa mp . 237.Fn cache_purgevfs 238is called when file system is unmounted to remove entries that would 239now be invalid. 240.It Fn namecache_print "vp" "func" 241Print all entries of the name cache. 242.Fa func 243is the 244.Xr printf 9 245format. 246.Fn namecache_print 247is only defined if the kernel option DDB is compiled into the kernel. 248.El 249.Sh CODE REFERENCES 250The name lookup cache is implemented within the file 251.Pa sys/kern/vfs_cache.c . 252.Sh SEE ALSO 253.Xr intro 9 , 254.Xr namei 9 , 255.Xr vfs 9 , 256.Xr vnode 9 257.Sh HISTORY 258The name lookup cache first appeared in 259.Bx 4.2 . 260.Sh AUTHORS 261The original name lookup cache was written by 262.An Robert Elz . 263