diff options
Diffstat (limited to 'static/netbsd/man9/namecache.9')
| -rw-r--r-- | static/netbsd/man9/namecache.9 | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/static/netbsd/man9/namecache.9 b/static/netbsd/man9/namecache.9 new file mode 100644 index 00000000..7abed5aa --- /dev/null +++ b/static/netbsd/man9/namecache.9 @@ -0,0 +1,262 @@ +.\" $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 . |