179 lines
4.6 KiB
Groff
179 lines
4.6 KiB
Groff
.\" $OpenBSD: vfs_cache.9,v 1.4 2018/06/04 19:42:54 kn Exp $
|
|
.\" Written by Jared Yanovich <jaredy@openbsd.org>
|
|
.\" Public domain, 2005/6/17
|
|
.Dd $Mdocdate: June 4 2018 $
|
|
.Dt VFS_CACHE 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm vfs_cache ,
|
|
.Nm cache_enter ,
|
|
.Nm cache_lookup ,
|
|
.Nm cache_purge ,
|
|
.Nm cache_purgevfs ,
|
|
.Nm cache_revlookup
|
|
.Nd name lookup cache
|
|
.Sh SYNOPSIS
|
|
.In sys/vnode.h
|
|
.In sys/namei.h
|
|
.Pp
|
|
.Ft int
|
|
.Fn cache_lookup "struct vnode *dvp" "struct vnode **vpp" \
|
|
"struct componentname *cnp"
|
|
.Ft void
|
|
.Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \
|
|
"struct componentname *cnp"
|
|
.Ft void
|
|
.Fn cache_purge "struct vnode *vp"
|
|
.Ft void
|
|
.Fn cache_purgevfs "struct mount *mp"
|
|
.Ft int
|
|
.Fn cache_revlookup "struct vnode *vp" "struct vnode **dvpp" \
|
|
"char **bpp" "char *bufp"
|
|
.Sh DESCRIPTION
|
|
In order to speed up file name look-up operations (see
|
|
.Xr 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:
|
|
.Bd -literal
|
|
struct namecache {
|
|
TAILQ_ENTRY(namecache) nc_lru; /* Regular Entry LRU chain */
|
|
TAILQ_ENTRY(namecache) nc_neg; /* Negative Entry LRU chain */
|
|
RBT_ENTRY(namecache) n_rbcache; /* Namecache rb tree from vnode */
|
|
TAILQ_ENTRY(namecache) nc_me; /* ncp's referring to me */
|
|
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[NAMECACHE_MAXLEN]; /* segment name */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
File names with length longer than
|
|
.Dv NAMECACHE_MAXLEN
|
|
are not cached to simplify lookups and to save space.
|
|
Such names are rare and are generally not worth caching.
|
|
.Pp
|
|
The
|
|
.Nm vfs_cache
|
|
API contains the following routines:
|
|
.Bl -tag -width Ds
|
|
.It Fn cache_lookup dvp vpp cnp
|
|
Look up the given name in the cache.
|
|
.Fa dvp
|
|
points to the directory to search,
|
|
.Fa vpp
|
|
points to a pointer where the vnode of the name being sought will be
|
|
stored, and
|
|
.Fa cnp
|
|
contains the last component of the path name.
|
|
.Fa cnp
|
|
must have the
|
|
.Va cn_nameptr ,
|
|
.Va cn_namelen ,
|
|
and
|
|
.Va 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
|
|
.Xr namei 9
|
|
lookup operation was
|
|
.Dv DELETE
|
|
or the
|
|
.Dv NOCACHE
|
|
flag was set for the call to
|
|
.Xr namei 9 .
|
|
.Pp
|
|
Upon success, a pointer to a locked vnode is stored in
|
|
.Fa vpp
|
|
and a zero value is returned.
|
|
If locking the vnode fails, the vnode will remain unlocked,
|
|
.Fa *vpp
|
|
will be set to
|
|
.Dv NULL ,
|
|
and the corresponding error will be returned.
|
|
If the cache entry is negative cached, meaning the name is no longer
|
|
valid,
|
|
.Er ENOENT
|
|
is returned.
|
|
Otherwise, the cache lookup has failed and a \-1 value is returned.
|
|
.It Fn cache_enter dvp vp cnp
|
|
Add a new entry for the translation in the directory
|
|
.Fa dvp
|
|
for the vnode
|
|
.Fa vp
|
|
with name
|
|
.Fa cnp
|
|
to the cache.
|
|
.Fa cnp
|
|
must have the
|
|
.Va cn_nameptr ,
|
|
.Va cn_namelen ,
|
|
and
|
|
.Va cn_hash
|
|
fields filled in.
|
|
.It Fn cache_purge vp
|
|
Flush all cache entries corresponding with the given vnode
|
|
.Fa vp .
|
|
This is called after rename operations to hide entries that would no
|
|
longer be valid.
|
|
.It Fn cache_purgevfs mp
|
|
Flush all cache entries for name translations associated with the file
|
|
system mount described by
|
|
.Fa mp .
|
|
This is called when unmounting file systems, which would make all name
|
|
translations pertaining to the mount invalid.
|
|
.It Fn cache_revlookup vp dvpp bpp bufp
|
|
Scan the cache for the name of the directory entry that points to
|
|
.Fa vp .
|
|
.Fa dvpp
|
|
points to where a pointer to the encompassing directory will be stored.
|
|
If
|
|
.Fa bufp
|
|
is not
|
|
.Dv NULL ,
|
|
the name will be written to the end of the space between this pointer
|
|
and the value in
|
|
.Fa bpp ,
|
|
and
|
|
.Fa bpp
|
|
will be updated on return to point to the start of the copied name.
|
|
.Pp
|
|
On success,
|
|
.Fa *dvpp
|
|
will be set to point to the encompassing directory and zero will be
|
|
returned.
|
|
If the cache misses,
|
|
.Fa dvpp
|
|
will be set to
|
|
.Dv NULL
|
|
and \-1 will be returned.
|
|
Otherwise, failure has occurred,
|
|
.Fa dvpp
|
|
will be set to
|
|
.Dv NULL ,
|
|
and an appropriate error code will be returned.
|
|
.El
|
|
.Sh CODE REFERENCES
|
|
The
|
|
.Nm
|
|
API is implemented in the file
|
|
.Pa sys/kern/vfs_cache.c .
|
|
.Sh SEE ALSO
|
|
.Xr vmstat 8 ,
|
|
.Xr namei 9 ,
|
|
.Xr vfs 9 ,
|
|
.Xr vnode 9 ,
|
|
.Xr VOP_LOOKUP 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
API first appeared in
|
|
.Bx 4.2 .
|