1.\" $OpenBSD: vfs_cache.9,v 1.3 2007/05/31 19:20:01 jmc Exp $ 2.\" Written by Jared Yanovich <jaredy@openbsd.org> 3.\" Public domain, 2005/6/17 4.Dd $Mdocdate: May 31 2007 $ 5.Dt VFS_CACHE 9 6.Os 7.Sh NAME 8.Nm vfs_cache , 9.Nm cache_enter , 10.Nm cache_lookup , 11.Nm cache_purge , 12.Nm cache_purgevfs , 13.Nm cache_revlookup 14.Nd name lookup cache 15.Sh SYNOPSIS 16.In sys/vnode.h 17.In sys/namei.h 18.Pp 19.Ft int 20.Fn cache_lookup "struct vnode *dvp" "struct vnode **vpp" \ 21 "struct componentname *cnp" 22.Ft void 23.Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \ 24 "struct componentname *cnp" 25.Ft void 26.Fn cache_purge "struct vnode *vp" 27.Ft void 28.Fn cache_purgevfs "struct mount *mp" 29.Ft int 30.Fn cache_revlookup "struct vnode *vp" "struct vnode **dvpp" \ 31 "char **bpp" "char *bufp" 32.Sh DESCRIPTION 33In order to speed up file name look-up operations (see 34.Xr VOP_LOOKUP 9 ) , 35the kernel provides an interface for maintaining a cache of the most 36recently looked-up file name translations. 37Entries in this cache have the following definition: 38.Bd -literal 39struct namecache { 40 LIST_ENTRY(namecache) nc_hash; /* hash chain */ 41 LIST_ENTRY(namecache) nc_vhash; /* (reverse) dir hash chain */ 42 TAILQ_ENTRY(namecache) nc_lru; /* LRU chain */ 43 struct vnode *nc_dvp; /* vnode of parent of name */ 44 u_long nc_dvpid; /* capability number of nc_dvp */ 45 struct vnode *nc_vp; /* vnode the name refers to */ 46 u_long nc_vpid; /* capability number of nc_vp */ 47 char nc_nlen; /* length of name */ 48 char nc_name[NCHNAMLEN]; /* segment name */ 49}; 50.Ed 51.Pp 52The cache is indexed by a hash value based on the file's base name and 53its encompassing directory's vnode generation number. 54Negative caching is also performed so that frequently accessed path 55names of files that do not exist do not result in expensive lookups. 56.Pp 57File names with length longer than 58.Dv NCHNAMLEN 59are not cached to simplify lookups and to save space. 60Such names are rare and are generally not worth caching. 61.Pp 62The 63.Nm vfs_cache 64API contains the following routines: 65.Bl -tag -width Ds 66.It Fn cache_lookup dvp vpp cnp 67Look up the given name in the cache. 68.Fa dvp 69points to the directory to search, 70.Fa vpp 71points to a pointer where the vnode of the name being sought will be 72stored, and 73.Fa cnp 74contains the last component of the path name. 75.Fa cnp 76must have the 77.Va cn_nameptr , 78.Va cn_namelen , 79and 80.Va cn_hash 81fields filled in. 82If no entry is found for the given name, a new one will be created, 83even if the path name fails (i.e. it will be negative cached), unless 84the 85.Xr namei 9 86lookup operation was 87.Dv DELETE 88or the 89.Dv NOCACHE 90flag was set for the call to 91.Xr namei 9 . 92.Pp 93Upon success, a pointer to a locked vnode is stored in 94.Fa vpp 95and a zero value is returned. 96If locking the vnode fails, the vnode will remain unlocked, 97.Fa *vpp 98will be set to 99.Dv NULL , 100and the corresponding error will be returned. 101If the cache entry is negative cached, meaning the name is no longer 102valid, 103.Er ENOENT 104is returned. 105Otherwise, the cache lookup has failed and a \-1 value is returned. 106.It Fn cache_enter dvp vp cnp 107Add a new entry for the translation in the directory 108.Fa dvp 109for the vnode 110.Fa vp 111with name 112.Fa cnp 113to the cache. 114.Fa cnp 115must have the 116.Va cn_nameptr , 117.Va cn_namelen , 118and 119.Va cn_hash 120fields filled in. 121.It Fn cache_purge vp 122Flush all cache entries corresponding with the given vnode 123.Fa vp . 124This is called after rename operations to hide entries that would no 125longer be valid. 126.It Fn cache_purgevfs mp 127Flush all cache entries for name translations associated with the file 128system mount described by 129.Fa mp . 130This is called when unmounting file systems, which would make all name 131translations pertaining to the mount invalid. 132.It Fn cache_revlookup vp dvpp bpp bufp 133Scan the cache for the name of the directory entry that points to 134.Fa vp . 135.Fa dvpp 136points to where a pointer to the encompassing directory will be stored. 137If 138.Fa bufp 139is not 140.Dv NULL , 141the name will be written to the end of the space between this pointer 142and the value in 143.Fa bpp , 144and 145.Fa bpp 146will be updated on return to point to the start of the copied name. 147.Pp 148On success, 149.Fa *dvpp 150will be set to point to the encompassing directory and zero will be 151returned. 152If the cache misses, 153.Fa dvpp 154will be set to 155.Dv NULL 156and \-1 will be returned. 157Otherwise, failure has occurred, 158.Fa dvpp 159will be set to 160.Dv NULL , 161and an appropriate error code will be returned. 162.El 163.Sh CODE REFERENCES 164The 165.Nm 166API is implemented in the file 167.Pa sys/kern/vfs_cache.c . 168.Sh SEE ALSO 169.Xr vmstat 8 , 170.Xr namei 9 , 171.Xr vfs 9 , 172.Xr vnode 9 173.Sh HISTORY 174The 175.Nm 176API first appeared in 177.Bx 4.2 . 178