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