I would appreciate any donations. Wishlist or send e-mail type donations to maekawa AT daemon-systems.org.

Thank you.

NAMECACHE(9)               Kernel Developer's Manual              NAMECACHE(9)

     namecache, cache_lookup, cache_revlookup, cache_enter, cache_purge,
     cache_purgevfs, namecache_print -- name lookup cache

     #include <sys/namei.h>
     #include <sys/proc.h>
     #include <sys/uio.h>
     #include <sys/vnode.h>

     cache_lookup(struct vnode *dvp, const char *name, size_t namelen,
         uint32_t nameiop, uint32_t nameiflags, int *iswhiteout,
         struct vnode **vpp);

     cache_revlookup(struct vnode *vp, struct vnode *dvp, char **bpp,
         char *bufp);

     cache_enter(struct vnode *dvp, struct vnode *vp, const char *name,
         size_t namelen, uint32_t nameiflags);

     cache_purge(struct vnode *vp);

     cache_purgevfs(struct mount *mp);

     namecache_print(struct vnode *vp, void (*func)(const char *, ...));

     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

     #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
     nshashtbl: 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

     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

     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

              If vp is NULL, a negative cache entry is created, specifying
              that the entry does not exist in the file system.

              Flush the cache of a particular vnode vp.  cache_purge() is
              called when a vnode is renamed to hide entries that would now be

              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.

     The name lookup cache is implemented within the file

     intro(9), namei(9), vfs(9), vnode(9)

     The name lookup cache first appeared in 4.2BSD.

     The original name lookup cache was written by Robert Elz.

NetBSD 7.1.2                   February 7, 2014                   NetBSD 7.1.2