1 .\" Copyright (c) 1996 Doug Rabson
3 .\" All rights reserved.
5 .\" This program is free software.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 .\" $FreeBSD: src/share/man/man9/VOP_LOOKUP.9,v 1.8.2.5 2001/12/17 11:30:18 ru Exp $
34 .Nd lookup a component of a pathname
40 .Fn VOP_LOOKUP "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp"
42 This entry point looks up a single pathname component in a given directory.
47 the locked vnode of the directory to search
49 the address of a variable where the resulting locked vnode should be stored
51 the pathname component to be searched for
55 is a pointer to a componentname structure defined as follows:
57 struct componentname {
59 * Arguments to lookup.
61 u_long cn_nameiop; /* namei operation */
62 u_long cn_flags; /* flags to namei */
63 struct proc *cn_proc; /* process requesting lookup */
64 struct ucred *cn_cred; /* credentials */
66 * Shared between lookup and commit routines.
68 char *cn_pnbuf; /* pathname buffer */
69 char *cn_nameptr; /* pointer to looked up name */
70 long cn_namelen; /* length of looked up component */
71 u_long cn_hash; /* hash value of looked up name */
72 long cn_consume; /* chars to consume in lookup() */
76 Convert a component of a pathname into a pointer to a locked vnode.
77 This is a very central and rather complicated routine.
78 If the file system is not maintained in a strict tree hierarchy,
79 this can result in a deadlock situation.
89 depending on the intended use of the object.
95 is specified, information usable in
96 creating, renaming, or deleting a directory entry may be calculated.
98 Overall outline of VOP_LOOKUP:
99 .Bd -ragged -offset indent
100 Check accessibility of directory.
101 Look for name in cache, if found, then return name.
102 Search for name in directory, goto to found or notfound as appropriate.
106 .Bd -ragged -offset indent
107 If creating or renaming and at end of pathname,
110 leaving info on available slots else return
115 .Bd -ragged -offset indent
116 If at end of path and deleting, return information to allow delete.
117 If at end of path and renaming, lock target
118 inode and return info to allow rename.
119 If not at end, add name to cache; if at end and neither creating
120 nor deleting, add name to cache.
125 should be locked on entry.
126 If an error (note: the return value
128 is not considered an error)
129 is detected, it will be returned locked.
130 Otherwise, it will be unlocked unless both
136 If an entry is found in the directory, it will be returned locked.
138 Zero is returned with
140 set to the locked vnode of the file if the component is found.
141 If the component being searched for is ".", then the vnode just has
142 an extra reference added to it with
144 The caller must take care to release the locks appropriately in this
147 If the component is not found and the operation is
153 is specified and the operation would succeed, the special return value
156 Otherwise, an appropriate error code is returned.
160 vop_lookup(struct vnode *dvp,
162 struct componentname *cnp)
165 int nameiop = cnp->cn_nameiop;
166 int flags = cnp->cn_flags;
167 int lockparent = flags & LOCKPARENT;
168 int islastcn = flags & ISLASTCN;
169 struct vnode *vp = NULL;
172 * Check accessibility of directory.
174 if (dvp->v_type != VDIR)
177 error = VOP_ACCESS(dvp, VEXEC, cred, cnp->cn_proc);
181 if (islastcn && (dvp->v_mount->mnt_flag & MNT_RDONLY) &&
182 (cnp->cn_nameiop == DELETE || cnp->cn_nameiop == RENAME))
186 * Check name cache for directory/name pair. This returns ENOENT
187 * if the name is known not to exist, -1 if the name was found, or
190 error = cache_lookup(dvp, vpp, cnp);
198 if (dvp == vp) { /* lookup on "." */
201 } else if (flags & ISDOTDOT) {
203 * We need to unlock the directory before getting
204 * the locked vnode for ".." to avoid deadlocks.
209 if (lockparent && islastcn)
210 error = VOP_LOCK(dvp);
214 if (error || !(lockparent && islastcn)) {
220 * Check that the capability number did not change
221 * while we were waiting for the lock.
224 if (vpid == vp->v_id) {
226 * dvp is locked if lockparent && islastcn.
233 if (dvp != vp && lockparent && islastcn)
238 * Re-lock dvp for the directory search below.
240 error = VOP_LOCK(dvp);
249 * Search dvp for the component cnp->cn_nameptr.
254 if ((nameiop == CREATE || nameiop == RENAME)
256 && directory dvp has not been removed) {
258 * Check for write access on directory.
262 * Possibly record the position of a slot in the directory
263 * large enough for the new component name. This can be
264 * recorded in the vnode private data for dvp.
265 * Set the SAVENAME flag to hold onto the pathname for use
266 * later in VOP_CREATE or VOP_RENAME.
268 cnp->cn_flags |= SAVENAME;
271 * Note that the extra data recorded above is only
272 * useful if lockparent is specified.
280 * Consider inserting name into cache.
282 if ((cnp->cn_flags & MAKEENTRY) && nameiop != CREATE)
283 cache_enter(dvp, NULL, cnp);
288 * If deleting, and at end of pathname, return parameters
289 * which can be used to remove file. If the wantparent flag
290 * isn't set, we return only the directory, otherwise we go on
291 * and lock the inode, being careful with ".".
293 if (nameiop == DELETE && islastcn) {
295 * Check for write access on directory.
297 error = VOP_ACCESS(dvp, VWRITE, cred, cnp->cn_proc);
301 if (found entry is same as dvp) {
307 error = VFS_VGET(dvp->v_mount, ..., &vp);
311 if (directory is sticky
313 && cred->cr_uid != owner of dvp
314 && owner of vp != cred->cr_uid) {
326 * If rewriting (RENAME), return the inode and the
327 * information required to rewrite the present directory
328 * Must get inode of directory entry to verify it's a
329 * regular file, or empty directory.
331 if (nameiop == RENAME && wantparent && islastcn) {
332 error = VOP_ACCESS(dvp, VWRITE, cred, cnp->cn_proc);
339 if (found entry is same as dvp)
342 error = VFS_VGET(dvp->v_mount, ..., &vp);
347 * Save the name for use in VOP_RENAME later.
349 cnp->cn_flags |= SAVENAME;
357 * Step through the translation in the name. We do not `vput' the
358 * directory because we may need it again if a symbolic link
359 * is relative to the current directory. Instead we save it
360 * unlocked as "pdp". We must get the target inode before unlocking
361 * the directory to insure that the inode will not be removed
362 * before we get it. We prevent deadlock by always fetching
363 * inodes from the root, moving down the directory tree. Thus
364 * when following backward pointers ".." we must unlock the
365 * parent directory before getting the requested directory.
366 * There is a potential race condition here if both the current
367 * and parent directories are removed before the VFS_VGET for the
368 * inode associated with ".." returns. We hope that this occurs
369 * infrequently since we cannot avoid this race condition without
370 * implementing a sophisticated deadlock detection algorithm.
371 * Note also that this simple deadlock detection scheme will not
372 * work if the file system has any hard links other than ".."
373 * that point backwards in the directory structure.
375 if (flags & ISDOTDOT) {
376 VOP_UNLOCK(dvp); /* race to get the inode */
377 error = VFS_VGET(dvp->v_mount, ..., &vp);
382 if (lockparent && islastcn) {
383 error = VOP_LOCK(dvp);
390 } else if (found entry is same as dvp) {
391 VREF(dvp); /* we want ourself, ie "." */
394 error = VFS_VGET(dvp->v_mount, ..., &vp);
397 if (!lockparent || !islastcn)
403 * Insert name into cache if appropriate.
405 if (cnp->cn_flags & MAKEENTRY)
406 cache_enter(dvp, *vpp, cnp);
416 does not represent a directory.
420 was not found in this directory.
422 access for the specified operation is denied.
423 .It Bq Er EJUSTRETURN
428 operation would be successful
444 This man page was written by
446 with some text from comments in
447 .Pa sys/vfs/ufs/ufs_lookup.c .