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 contains 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
positive 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 support 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, positive 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 compiled 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.