xref: /netbsd-src/share/man/man9/namecache.9 (revision 6a493d6bc668897c91594964a732d38505b70cbb)
1.\"     $NetBSD: namecache.9,v 1.17 2012/11/05 22:49:14 wiz 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 November 5, 2012
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" "const char *name" "size_t namelen" \
49"uint32_t nameiop" "uint32_t nameiflags" "int *iswhiteout" "struct vnode **vpp"
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"const char *name" "size_t namelen" "uint32_t nameiflags"
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
63The name lookup cache is the mechanism to allow the file system type
64dependent algorithms to quickly resolve a file's vnode from its
65pathname.
66The name lookup cache is generally accessed through the higher-level
67.Xr namei 9
68interface.
69.Pp
70The name of the file is used to look up an entry associated with the
71file in the name lookup cache.
72If no entry is found, one is created for it.
73If an entry is found, the information obtained from the cache lookup
74contains information about the file which is useful to the file system
75type dependent functions.
76.Pp
77The name lookup cache is managed by a least recently used (LRU)
78algorithm so frequently used names will hang around.
79The cache itself is a hash table called
80.Va nchashtbl ,
81containing
82.Em namecache
83entries that are allocated dynamically from a kernel memory pool.
84Each entry has the following structure:
85.Bd -literal
86#define NCHNAMLEN	31	/* maximum name segment length */
87struct  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
101For simplicity (and economy of storage), names longer than a maximum
102length of NCHNAMLEN are not cached; they occur infrequently in any
103case, and are almost never of interest.
104.Pp
105Each
106.Em namecache
107entry 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).
113The hash chains are indexed by a hash value obtained from the file's
114name and the address of its parent directory vnode.
115.Pp
116Functions which access to the name cache pass arguments in the
117partially initialised
118.Em componentname
119structure.
120See
121.Xr vnodeops 9
122for details on this structure.
123.Sh FUNCTIONS
124.Bl -tag -width compact
125.It Fn cache_lookup "dvp" "name" "namelen" "nameiop" "nameiflags" \
126"iswhiteout" "vpp"
127Look for a name in the cache.
128.Fn cache_lookup
129is called with
130.Fa dvp
131pointing to the vnode of the directory to search.
132The
133.Fa name
134and
135.Fa namelen
136arguments specify the name to look for.
137The
138.Fa nameiop
139and
140.Fa nameiflags
141should be taken from the
142.Fa cn_nameiop
143and
144.Fa cn_flags
145fields of struct componentname.
146.Pp
147The lookup can produce either a cache miss or a cache hit, and a cache
148hit can either be a positive hit, where the name looked up refers to
149some existing object, or a negative hit, where the name looked up is
150known to refer to
151.Em no
152existing object.
153(The lookup cannot fail, in the sense of generating an error condition
154that requires aborting the operation in progress.)
155.Pp
156On a cache miss,
157.Fn cache_lookup
158returns zero
159.Pq false .
160On a positive hit, the vnode for the object found is locked and stored
161in
162.Fa vpp ,
163and a nonzero
164.Pq true
165value is returned.
166On a negative hit,
167.Fa vpp
168is set to contain a null pointer and a nonzero value is returned.
169Usually a negative hit will prompt the caller to fail with
170.Er ENOENT .
171.Pp
172The
173.Fa iswhiteout
174argument is a pointer to an integer result that will be set to nonzero if
175the entry represents a whiteout, and zero if it does not.
176This pointer may be
177.Dv NULL
178if the caller does not support whiteouts.
179According to the current scheme for handling whiteouts, if
180.Fn cache_lookup
181sets
182.Fa iswhiteout
183the caller should add
184.Dv ISWHITEOUT
185to the
186.Fa cn_flags
187field of its struct componentname.
188.It Fn cache_revlookup "vp" "dvp" "bpp" "bufp"
189Scan cache looking for name of directory entry pointing at
190.Fa vp
191and fill in
192.Fa dvpp .
193If
194.Fa bufp
195is
196.Pf non- Dv NULL ,
197also place the name in the buffer which starts at
198.Fa bufp ,
199immediately before
200.Fa bpp ,
201and move bpp backwards to point at the start of it.
202If the lookup succeeds, the vnode is referenced.
203Returns 0 on success, -1 on cache miss, positive errno on failure.
204.It Fn cache_enter "dvp" "vp" "name" "namelen" "nameiflags"
205Add an entry to the cache.
206The
207.Fa name
208and
209.Fa namelen
210arguments specify the name to add to the cache.
211The
212.Fa dvp
213argument specifies the directory the name appears in.
214The
215.Fa vp
216argument specifies the object to enter in the cache.
217The
218.Fa nameiflags
219argument should come from the
220.Fa cn_flags
221member of struct componentname.
222.Pp
223If
224.Fa vp
225is
226.Dv NULL ,
227a negative cache entry is created, specifying that the entry
228does not exist in the file system.
229.It Fn cache_purge "vp"
230Flush the cache of a particular vnode
231.Fa vp .
232.Fn cache_purge
233is called when a vnode is renamed to hide entries that would now be
234invalid.
235.It Fn cache_purgevfs "mp"
236Flush cache of a whole file system
237.Fa mp .
238.Fn cache_purgevfs
239is called when file system is unmounted to remove entries that would
240now be invalid.
241.It Fn namecache_print "vp" "func"
242Print all entries of the name cache.
243.Fa func
244is the
245.Xr printf 9
246format.
247.Fn namecache_print
248is only defined if the kernel option DDB is compiled into the kernel.
249.El
250.Sh CODE REFERENCES
251The name lookup cache is implemented within the file
252.Pa sys/kern/vfs_cache.c .
253.Sh SEE ALSO
254.Xr intro 9 ,
255.Xr namei 9 ,
256.Xr vfs 9 ,
257.Xr vnode 9
258.Sh HISTORY
259The name lookup cache first appeared in
260.Bx 4.2 .
261.Sh AUTHORS
262The original name lookup cache was written by Robert Elz.
263