docs: OpenBSD Man Pages Added

1 files changed, 179 insertions, 0 deletions

diff --git a/static/openbsd/man9/vfs_cache.9 b/static/openbsd/man9/vfs_cache.9
new file mode 100644
index 00000000..b6ebe043
--- /dev/null
+++ b/static/openbsd/man9/vfs_cache.9
@@ -0,0 +1,179 @@
+.\"	$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 .