unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

VFS_CACHE(9)             BSD Kernel Developer's Manual            VFS_CACHE(9)

NAME
     vfs_cache, cache_enter, cache_lookup, cache_purge, cache_purgevfs,
     cache_revlookup -- name lookup cache

SYNOPSIS
     #include <&lt;sys/vnode.h>&gt;
     #include <&lt;sys/namei.h>&gt;

     int
     cache_lookup(struct vnode *dvp, struct vnode **vpp,
         struct componentname *cnp);

     void
     cache_enter(struct vnode *dvp, struct vnode *vp,
         struct componentname *cnp);

     void
     cache_purge(struct vnode *vp);

     void
     cache_purgevfs(struct mount *mp);

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

DESCRIPTION
     In order to speed up file name look-up operations (see VOP_LOOKUP(9)),
     the kernel provides an interface for maintaining a cache of the most
     recently looked-up file name translations.  Entries in this cache have
     the following definition:

     struct  namecache {
             LIST_ENTRY(namecache) nc_hash;  /* hash chain */
             LIST_ENTRY(namecache) nc_vhash; /* (reverse) dir hash chain */
             TAILQ_ENTRY(namecache) nc_lru;  /* LRU chain */
             struct  vnode *nc_dvp;          /* vnode of parent of name */
             u_long  nc_dvpid;               /* capability number of nc_dvp */
             struct  vnode *nc_vp;           /* vnode the name refers to */
             u_long  nc_vpid;                /* capability number of nc_vp */
             char    nc_nlen;                /* length of name */
             char    nc_name[NCHNAMLEN];     /* segment name */
     };

     The cache is indexed by a hash value based on the file's base name and
     its encompassing directory's vnode generation number.  Negative caching
     is also performed so that frequently accessed path names of files that do
     not exist do not result in expensive lookups.

     File names with length longer than NCHNAMLEN are not cached to simplify
     lookups and to save space.  Such names are rare and are generally not
     worth caching.

     The vfs_cache API contains the following routines:

     cache_lookup(dvp, vpp, cnp)
             Look up the given name in the cache.  dvp points to the directory
             to search, vpp points to a pointer where the vnode of the name
             being sought will be stored, and cnp contains the last component
             of the path name.  cnp must have the cn_nameptr, cn_namelen, and
             cn_hash fields filled in.  If no entry is found for the given
             name, a new one will be created, even if the path name fails
             (i.e. it will be negative cached), unless the namei(9) lookup
             operation was DELETE or the NOCACHE flag was set for the call to
             namei(9).

             Upon success, a pointer to a locked vnode is stored in vpp and a
             zero value is returned.  If locking the vnode fails, the vnode
             will remain unlocked, *vpp will be set to NULL, and the corre-
             sponding error will be returned.  If the cache entry is negative
             cached, meaning the name is no longer valid, ENOENT is returned.
             Otherwise, the cache lookup has failed and a -1 value is
             returned.

     cache_enter(dvp, vp, cnp)
             Add a new entry for the translation in the directory dvp for the
             vnode vp with name cnp to the cache.  cnp must have the
             cn_nameptr, cn_namelen, and cn_hash fields filled in.

     cache_purge(vp)
             Flush all cache entries corresponding with the given vnode vp.
             This is called after rename operations to hide entries that would
             no longer be valid.

     cache_purgevfs(mp)
             Flush all cache entries for name translations associated with the
             file system mount described by mp.  This is called when unmount-
             ing file systems, which would make all name translations pertain-
             ing to the mount invalid.

     cache_revlookup(vp, dvpp, bpp, bufp)
             Scan the cache for the name of the directory entry that points to
             vp.  dvpp points to where a pointer to the encompassing directory
             will be stored.  If bufp is not NULL, the name will be written to
             the end of the space between this pointer and the value in bpp,
             and bpp will be updated on return to point to the start of the
             copied name.

             On success, *dvpp will be set to point to the encompassing direc-
             tory and zero will be returned.  If the cache misses, dvpp will
             be set to NULL and -1 will be returned.  Otherwise, failure has
             occurred, dvpp will be set to NULL, and an appropriate error code
             will be returned.

CODE REFERENCES
     The vfs_cache API is implemented in the file sys/kern/vfs_cache.c.

SEE ALSO
     vmstat(8), namei(9), vfs(9), vnode(9)

HISTORY
     The vfs_cache API first appeared in 4.2BSD.

BSD                              May 31, 2007                              BSD