263 lines
7.8 KiB
Groff
263 lines
7.8 KiB
Groff
.\" $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 .
|