.\" $NetBSD: namecache.9,v 1.21 2017/04/19 11:33:01 abhinav Exp $ .\" .\" Copyright (c) 2001 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Gregory McGarry. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd February 7, 2014 .Dt NAMECACHE 9 .Os .Sh NAME .Nm namecache , .Nm cache_lookup , .Nm cache_revlookup , .Nm cache_enter , .Nm cache_purge , .Nm cache_purgevfs , .Nm namecache_print .Nd name lookup cache .Sh SYNOPSIS .In sys/namei.h .In sys/proc.h .In sys/uio.h .In sys/vnode.h .Ft int .Fn cache_lookup "struct vnode *dvp" "const char *name" "size_t namelen" \ "uint32_t nameiop" "uint32_t nameiflags" "int *iswhiteout" "struct vnode **vpp" .Ft int .Fn cache_revlookup "struct vnode *vp" "struct vnode *dvp" \ "char **bpp" "char *bufp" .Ft void .Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \ "const char *name" "size_t namelen" "uint32_t nameiflags" .Ft void .Fn cache_purge "struct vnode *vp" .Ft void .Fn cache_purgevfs "struct mount *mp" .Ft void .Fn namecache_print "struct vnode *vp" "void (*func)(const char *, ...)" .Sh DESCRIPTION The name lookup cache is the mechanism to allow the file system type dependent algorithms to quickly resolve a file's vnode from its pathname. The name lookup cache is generally accessed through the higher-level .Xr namei 9 interface. .Pp The name of the file is used to look up an entry associated with the file in the name lookup cache. If no entry is found, one is created for it. If an entry is found, the information obtained from the cache lookup contains information about the file which is useful to the file system type dependent functions. .Pp The name lookup cache is managed by a least recently used (LRU) algorithm so frequently used names will hang around. The cache itself is a hash table called .Va nchashtbl , containing .Em namecache entries that are allocated dynamically from a kernel memory pool. Each entry has the following structure: .Bd -literal #define NCHNAMLEN 31 /* maximum name segment length */ struct namecache { LIST_ENTRY(namecache) nc_hash; /* hash chain */ TAILQ_ENTRY(namecache) nc_lru; /* LRU chain */ LIST_ENTRY(namecache) nc_vhash; /* directory hash chain */ LIST_ENTRY(namecache) nc_dvlist; struct vnode *nc_dvp; /* vnode of parent of name */ LIST_ENTRY(namecache) nc_vlist; struct vnode *nc_vp; /* vnode the name refers to */ int nc_flags; /* copy of componentname's ISWHITEOUT */ char nc_nlen; /* length of name */ char nc_name[NCHNAMLEN]; /* segment name */ }; .Ed .Pp For simplicity (and economy of storage), names longer than a maximum length of NCHNAMLEN are not cached; they occur infrequently in any case, and are almost never of interest. .Pp Each .Em namecache entry can appear on two hash chains in addition to .Va nchashtbl : .Em ncvhashtbl (the name cache directory hash chain), and .Em nclruhead (the name cache LRU chain). The hash chains are indexed by a hash value obtained from the file's name and the address of its parent directory vnode. .Pp Functions which access to the name cache pass arguments in the partially initialised .Em componentname structure. See .Xr vnodeops 9 for details on this structure. .Sh FUNCTIONS .Bl -tag -width abcd .It Fn cache_lookup "dvp" "name" "namelen" "nameiop" "nameiflags" \ "iswhiteout" "vpp" Look for a name in the cache. .Fn cache_lookup is called with .Fa dvp pointing to the vnode of the directory to search. The .Fa name and .Fa namelen arguments specify the name to look for. The .Fa nameiop and .Fa nameiflags should be taken from the .Fa cn_nameiop and .Fa cn_flags fields of struct componentname. .Pp The lookup can produce either a cache miss or a cache hit, and a cache hit can either be a positive hit, where the name looked up refers to some existing object, or a negative hit, where the name looked up is known to refer to .Em no existing object. (The lookup cannot fail, in the sense of generating an error condition that requires aborting the operation in progress.) .Pp On a cache miss, .Fn cache_lookup returns zero .Pq false . On a positive hit, the unlocked vnode for the object found is stored in .Fa vpp , and a nonzero .Pq true value is returned. On a negative hit, .Fa vpp is set to contain a null pointer and a nonzero value is returned. Usually a negative hit will prompt the caller to fail with .Er ENOENT . .Pp The .Fa iswhiteout argument is a pointer to an integer result that will be set to nonzero if the entry represents a whiteout, and zero if it does not. This pointer may be .Dv NULL if the caller does not support whiteouts. According to the current scheme for handling whiteouts, if .Fn cache_lookup sets .Fa iswhiteout the caller should add .Dv ISWHITEOUT to the .Fa cn_flags field of its struct componentname. .It Fn cache_revlookup "vp" "dvp" "bpp" "bufp" Scan cache looking for name of directory entry pointing at .Fa vp and fill in .Fa dvpp . If .Fa bufp is .Pf non- Dv NULL , also place the name in the buffer which starts at .Fa bufp , immediately before .Fa bpp , and move bpp backwards to point at the start of it. If the lookup succeeds, the vnode is referenced. Returns 0 on success, -1 on cache miss, positive errno on failure. .It Fn cache_enter "dvp" "vp" "name" "namelen" "nameiflags" Add an entry to the cache. The .Fa name and .Fa namelen arguments specify the name to add to the cache. The .Fa dvp argument specifies the directory the name appears in. The .Fa vp argument specifies the object to enter in the cache. The .Fa nameiflags argument should come from the .Fa cn_flags member of struct componentname. .Pp If .Fa vp is .Dv NULL , a negative cache entry is created, specifying that the entry does not exist in the file system. .It Fn cache_purge "vp" Flush the cache of a particular vnode .Fa vp . .Fn cache_purge is called when a vnode is renamed to hide entries that would now be invalid. .It Fn cache_purgevfs "mp" Flush cache of a whole file system .Fa mp . .Fn cache_purgevfs is called when file system is unmounted to remove entries that would now be invalid. .It Fn namecache_print "vp" "func" Print all entries of the name cache. .Fa func is the .Xr printf 9 format. .Fn namecache_print is only defined if the kernel option DDB is compiled into the kernel. .El .Sh CODE REFERENCES The name lookup cache is implemented within the file .Pa sys/kern/vfs_cache.c . .Sh SEE ALSO .Xr intro 9 , .Xr namei 9 , .Xr vfs 9 , .Xr vnode 9 .Sh HISTORY The name lookup cache first appeared in .Bx 4.2 . .Sh AUTHORS The original name lookup cache was written by .An Robert Elz .