Skip site navigation (1)Skip section navigation (2) 
Date:      Wed, 10 Apr 2019 13:02:33 +0000 (UTC)
From:      Alan Somers <asomers@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org
Subject:   svn commit: r346078 - head/sys/kern
Message-ID:  <201904101302.x3AD2XKg012359@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help 
Author: asomers
Date: Wed Apr 10 13:02:33 2019
New Revision: 346078
URL: https://svnweb.freebsd.org/changeset/base/346078

Log:
  fix cache_lookup's documentation
  
  cache_lookup's documentation got dislocated by r324378. Relocate and expand
  it.
  
  Reviewed by:	jhb, kib
  MFC after:	2 weeks
  Sponsored by:	The FreeBSD Foundation

Modified:
  head/sys/kern/vfs_cache.c

Modified: head/sys/kern/vfs_cache.c
==============================================================================
--- head/sys/kern/vfs_cache.c	Wed Apr 10 10:50:48 2019	(r346077)
+++ head/sys/kern/vfs_cache.c	Wed Apr 10 13:02:33 2019	(r346078)
@@ -150,7 +150,7 @@ struct	namecache_ts {
  * Names found by directory scans are retained in a cache
  * for future reference.  It is managed LRU, so frequently
  * used names will hang around.  Cache is indexed by hash value
- * obtained from (vp, name) where vp refers to the directory
+ * obtained from (dvp, name) where dvp refers to the directory
  * containing name.
  *
  * If it is a "negative" entry, (i.e. for a name that is known NOT to
@@ -1129,23 +1129,6 @@ cache_lookup_dot(struct vnode *dvp, struct vnode **vpp
 	return (-1);
 }
 
-/*
- * Lookup an entry in the cache
- *
- * Lookup is called with dvp pointing to the directory to search,
- * cnp pointing to the name of the entry being sought. If the lookup
- * succeeds, the vnode is returned in *vpp, and a status of -1 is
- * returned. If the lookup determines that the name does not exist
- * (negative caching), a status of ENOENT is returned. If the lookup
- * fails, a status of zero is returned.  If the directory vnode is
- * recycled out from under us due to a forced unmount, a status of
- * ENOENT is returned.
- *
- * vpp is locked and ref'd on return.  If we're looking up DOTDOT, dvp is
- * unlocked.  If we're looking up . an extra ref is taken, but the lock is
- * not recursively acquired.
- */
-
 static __noinline int
 cache_lookup_nomakeentry(struct vnode *dvp, struct vnode **vpp,
     struct componentname *cnp, struct timespec *tsp, int *ticksp)
@@ -1229,6 +1212,42 @@ out_no_entry:
 	return (0);
 }
 
+/**
+ * Lookup a name in the name cache
+ *
+ * # Arguments
+ *
+ * - dvp:	Parent directory in which to search.
+ * - vpp:	Return argument.  Will contain desired vnode on cache hit.
+ * - cnp:	Parameters of the name search.  The most interesting bits of
+ *   		the cn_flags field have the following meanings:
+ *   	- MAKEENTRY:	If clear, free an entry from the cache rather than look
+ *   			it up.
+ *   	- ISDOTDOT:	Must be set if and only if cn_nameptr == ".."
+ * - tsp:	Return storage for cache timestamp.  On a successful (positive
+ *   		or negative) lookup, tsp will be filled with any timespec that
+ *   		was stored when this cache entry was created.  However, it will
+ *   		be clear for "." entries.
+ * - ticks:	Return storage for alternate cache timestamp.  On a successful
+ *   		(positive or negative) lookup, it will contain the ticks value
+ *   		that was current when the cache entry was created, unless cnp
+ *   		was ".".
+ *
+ * # Returns
+ *
+ * - -1:	A positive cache hit.  vpp will contain the desired vnode.
+ * - ENOENT:	A negative cache hit, or dvp was recycled out from under us due
+ *		to a forced unmount.  vpp will not be modified.  If the entry
+ *		is a whiteout, then the ISWHITEOUT flag will be set in
+ *		cnp->cn_flags.
+ * - 0:		A cache miss.  vpp will not be modified.
+ *
+ * # Locking
+ *
+ * On a cache hit, vpp will be returned locked and ref'd.  If we're looking up
+ * .., dvp is unlocked.  If we're looking up . an extra ref is taken, but the
+ * lock is not recursively acquired.
+ */
 int
 cache_lookup(struct vnode *dvp, struct vnode **vpp, struct componentname *cnp,
     struct timespec *tsp, int *ticksp)

Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201904101302.x3AD2XKg012359>