| blob | 75e8418f7c2b95b142c7cd4d7b3f59578227a7b3 |
1 .\" $NetBSD: namecache.9,v 1.12 2008/04/30 13:10:58 martin Exp $
2 .\"
3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Gregory McGarry.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd June 25, 2007
31 .Dt NAMECACHE 9
32 .Os
33 .Sh NAME
34 .Nm namecache ,
35 .Nm cache_lookup ,
36 .Nm cache_revlookup ,
37 .Nm cache_enter ,
38 .Nm cache_purge ,
39 .Nm cache_purgevfs ,
40 .Nm namecache_print
41 .Nd name lookup cache
42 .Sh SYNOPSIS
43 .In sys/namei.h
44 .In sys/proc.h
45 .In sys/uio.h
46 .In sys/vnode.h
47 .Ft int
48 .Fn cache_lookup "struct vnode *dvp" "struct vnode **vpp" \
49 "struct componentname *cnp"
50 .Ft int
51 .Fn cache_revlookup "struct vnode *vp" "struct vnode *dvp" \
52 "char **bpp" "char *bufp"
53 .Ft void
54 .Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \
55 "struct componentname *cnp"
56 .Ft void
57 .Fn cache_purge "struct vnode *vp"
58 .Ft void
59 .Fn cache_purgevfs "struct mount *mp"
60 .Ft void
61 .Fn namecache_print "struct vnode *vp" "void (*func)(const char *, ...)"
62 .Sh DESCRIPTION
63 The name lookup cache is the mechanism to allow the file system type
64 dependent algorithms to quickly resolve a file's vnode from its
65 pathname.
66 The name lookup cache is generally accessed through the higher-level
67 .Xr namei 9
68 interface.
69 .Pp
70 The name of the file is used to lookup an entry associated with the
71 file in the name lookup cache.
72 If no entry is found, one is created for it.
73 If an entry is found, the information obtained from the cache lookup
74 contains information about the file which is useful to the file system
75 type dependent functions.
76 .Pp
77 The name lookup cache is managed by a least recently used (LRU)
78 algorithm so frequently used names will hang around.
79 The cache itself is a hash table called
80 .Va nchashtbl ,
81 containing
82 .Em namecache
83 entries that are allocated dynamically from a kernel memory pool.
84 Each entry has the following structure:
85 .Bd -literal
86 #define NCHNAMLEN 31 /* maximum name segment length */
87 struct namecache {
88 LIST_ENTRY(namecache) nc_hash; /* hash chain */
89 TAILQ_ENTRY(namecache) nc_lru; /* LRU chain */
90 LIST_ENTRY(namecache) nc_vhash; /* directory hash chain */
91 LIST_ENTRY(namecache) nc_dvlist;
92 struct vnode *nc_dvp; /* vnode of parent of name */
93 LIST_ENTRY(namecache) nc_vlist;
94 struct vnode *nc_vp; /* vnode the name refers to */
95 int nc_flags; /* copy of componentname's ISWHITEOUT */
96 char nc_nlen; /* length of name */
97 char nc_name[NCHNAMLEN]; /* segment name */
98 };
99 .Ed
100 .Pp
101 For simplicity (and economy of storage), names longer than a maximum
102 length of NCHNAMLEN are not cached; they occur infrequently in any
103 case, and are almost never of interest.
104 .Pp
105 Each
106 .Em namecache
107 entry can appear on two hash chains in addition to
108 .Va nshashtbl :
109 .Em ncvhashtbl
110 (the name cache directory hash chain), and
111 .Em nclruhead
112 (the name cache LRU chain).
113 The hash chains are indexed by a hash value obtained from the file's
114 name and the address of its parent directory vnode.
115 .Pp
116 Functions which access to the name cache pass arguments in the
117 partially initialised
118 .Em componentname
119 structure.
120 See
121 .Xr vnodeops 9
122 for details on this structure.
123 .Sh FUNCTIONS
124 .Bl -tag -width compact
125 .It Fn cache_lookup "dvp" "vpp" "cnp"
126 Look for a name in the cache.
127 .Fn cache_lookup
128 is called with
129 .Fa dvp
130 pointing to the vnode of the directory to search and
131 .Fa cnp
132 pointing to the partially initialised component structure.
133 .Fa cnp-\*[Gt]cn_nameptr
134 points to the name of the entry being sought,
135 .Fa cnp-\*[Gt]cn_namelen
136 tells the length of the name, and
137 .Fa cnp-\*[Gt]cn_hash
138 contains a hash of the name.
139 If the lookup succeeds, the vnode is locked, stored in
140 .Fa vpp
141 and a status of zero is returned.
142 If the locking fails for whatever reason, the vnode is unlocked and the
143 error is returned.
144 If the lookup determines that the name does not exist any longer, a
145 status of ENOENT is returned.
146 If the lookup fails, a status of -1 is returned.
147 .It Fn cache_revlookup "vp" "dvp" "bpp" "bufp"
148 Scan cache looking for name of directory entry pointing at
149 .Fa vp
150 and fill in
151 .Fa dvpp .
152 If
153 .Fa bufp
154 is
155 .Pf non- Dv NULL ,
156 also place the name in the buffer which starts at
157 .Fa bufp ,
158 immediately before
159 .Fa bpp ,
160 and move bpp backwards to point at the start of it.
161 Returns 0 on success, -1 on cache miss, positive errno on failure.
162 .It Fn cache_enter "dvp" "vp" "cnp"
163 Add an entry to the cache.
164 .Fn cache_enter
165 is called with
166 .Fa dvp
167 pointing to the vnode of the directory to enter and
168 .Fa cnp
169 pointing to the partially initialised component structure.
170 If
171 .Fa vp
172 is
173 .Dv NULL ,
174 a negative cache entry is created, specifying that the entry
175 does not exist in the file system.
176 .Fa cnp-\*[Gt]cn_nameptr
177 points to the name of the entry being entered,
178 .Fa cnp-\*[Gt]cn_namelen
179 tells the length of the name, and
180 .Fa cnp-\*[Gt]cn_hash
181 contains a hash of the name.
182 .It Fn cache_purge "vp"
183 Flush the cache of a particular vnode
184 .Fa vp .
185 .Fn cache_purge
186 is called when a vnode is renamed to hide entries that would now be
187 invalid.
188 .It Fn cache_purgevfs "mp"
189 Flush cache of a whole file system
190 .Fa mp .
191 .Fn cache_purgevfs
192 is called when file system is unmounted to remove entries that would
193 now be invalid.
194 .It Fn namecache_print "vp" "func"
195 Print all entries of the name cache.
196 .Fa func
197 is the
198 .Xr printf 9
199 format.
200 .Fn namecache_print
201 is only defined if the kernel option DDB is compiled into the kernel.
202 .El
203 .Sh CODE REFERENCES
204 This section describes places within the
205 .Nx
206 source tree where actual code implementing or using the name
207 lookup cache can be found.
208 All pathnames are relative to
209 .Pa /usr/src .
210 .Pp
211 The name lookup cache is implemented within the file
212 .Pa sys/kern/vfs_cache.c .
213 .Sh SEE ALSO
214 .Xr intro 9 ,
215 .Xr namei 9 ,
216 .Xr vfs 9 ,
217 .Xr vnode 9
218 .Sh HISTORY
219 The name lookup cache first appeared in
220 .Bx 4.2 .
221 .Sh AUTHORS
222 The original name lookup cache was written by Robert Elz.