namecache(9)
- NetBSD Manual Pages
NAMECACHE(9) NetBSD Kernel Developer's Manual NAMECACHE(9)
NAME
namecache, cache_lookup, cache_revlookup, cache_enter, cache_purge,
cache_purgevfs, namecache_print -- name lookup cache
SYNOPSIS
#include <sys/namei.h>
#include <sys/proc.h>
#include <sys/uio.h>
#include <sys/vnode.h>
int
cache_lookup(struct vnode *dvp, const char *name, size_t namelen,
uint32_t nameiop, uint32_t nameiflags, int *iswhiteout,
struct vnode **vpp);
int
cache_revlookup(struct vnode *vp, struct vnode *dvp, char **bpp,
char *bufp);
void
cache_enter(struct vnode *dvp, struct vnode *vp, const char *name,
size_t namelen, uint32_t nameiflags);
void
cache_purge(struct vnode *vp);
void
cache_purgevfs(struct mount *mp);
void
namecache_print(struct vnode *vp, void (*func)(const char *, ...));
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
namei(9) interface.
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 con-
tains information about the file which is useful to the file system type
dependent functions.
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 nchashtbl, containing namecache entries that are allocated
dynamically from a kernel memory pool. Each entry has the following
structure:
#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 */
};
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.
Each namecache entry can appear on two hash chains in addition to
nchashtbl: ncvhashtbl (the name cache directory hash chain), and
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.
Functions which access to the name cache pass arguments in the partially
initialised componentname structure. See vnodeops(9) for details on this
structure.
FUNCTIONS
cache_lookup(dvp, name, namelen, nameiop, nameiflags, iswhiteout, vpp)
Look for a name in the cache. cache_lookup() is called with dvp
pointing to the vnode of the directory to search. The name and
namelen arguments specify the name to look for. The nameiop and
nameiflags should be taken from the cn_nameiop and cn_flags fields
of struct componentname.
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 no existing object. (The lookup
cannot fail, in the sense of generating an error condition that
requires aborting the operation in progress.)
On a cache miss, cache_lookup() returns zero (false). On a posi-
tive hit, the unlocked vnode for the object found is stored in vpp,
and a nonzero (true) value is returned. On a negative hit, 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 ENOENT.
The 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 NULL if the caller does not sup-
port whiteouts. According to the current scheme for handling
whiteouts, if cache_lookup() sets iswhiteout the caller should add
ISWHITEOUT to the cn_flags field of its struct componentname.
cache_revlookup(vp, dvp, bpp, bufp)
Scan cache looking for name of directory entry pointing at vp and
fill in dvpp. If bufp is non-NULL, also place the name in the
buffer which starts at bufp, immediately before 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, posi-
tive errno on failure.
cache_enter(dvp, vp, name, namelen, nameiflags)
Add an entry to the cache. The name and namelen arguments specify
the name to add to the cache. The dvp argument specifies the
directory the name appears in. The vp argument specifies the
object to enter in the cache. The nameiflags argument should come
from the cn_flags member of struct componentname.
If vp is NULL, a negative cache entry is created, specifying that
the entry does not exist in the file system.
cache_purge(vp)
Flush the cache of a particular vnode vp. cache_purge() is called
when a vnode is renamed to hide entries that would now be invalid.
cache_purgevfs(mp)
Flush cache of a whole file system mp. cache_purgevfs() is called
when file system is unmounted to remove entries that would now be
invalid.
namecache_print(vp, func)
Print all entries of the name cache. func is the printf(9) format.
namecache_print() is only defined if the kernel option DDB is com-
piled into the kernel.
CODE REFERENCES
The name lookup cache is implemented within the file
sys/kern/vfs_cache.c.
SEE ALSO
intro(9), namei(9), vfs(9), vnode(9)
HISTORY
The name lookup cache first appeared in 4.2BSD.
AUTHORS
The original name lookup cache was written by Robert Elz.
NetBSD 10.99 February 7, 2014 NetBSD 10.99
Powered by man-cgi (2021-06-01).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.