3 .\" Copyright (c) 1996 Doug Rabson
5 .\" All rights reserved.
7 .\" This program is free software.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
18 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 .\" $FreeBSD: src/share/man/man9/VOP_LOOKUP.9,v 1.8.2.5 2001/12/17 11:30:18 ru Exp $
30 .\" $DragonFly: src/share/man/man9/VOP_LOOKUP.9,v 1.3 2003/07/27 05:36:06 hmp Exp $
37 .Nd lookup a component of a pathname
43 .Fn VOP_LOOKUP "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp"
45 This entry point looks up a single pathname component in a given directory.
50 the locked vnode of the directory to search
52 the address of a variable where the resulting locked vnode should be stored
54 the pathname component to be searched for
58 is a pointer to a componentname structure defined as follows:
60 struct componentname {
62 * Arguments to lookup.
64 u_long cn_nameiop; /* namei operation */
65 u_long cn_flags; /* flags to namei */
66 struct proc *cn_proc; /* process requesting lookup */
67 struct ucred *cn_cred; /* credentials */
69 * Shared between lookup and commit routines.
71 char *cn_pnbuf; /* pathname buffer */
72 char *cn_nameptr; /* pointer to looked up name */
73 long cn_namelen; /* length of looked up component */
74 u_long cn_hash; /* hash value of looked up name */
75 long cn_consume; /* chars to consume in lookup() */
79 Convert a component of a pathname into a pointer to a locked vnode.
80 This is a very central and rather complicated routine.
81 If the file system is not maintained in a strict tree hierarchy,
82 this can result in a deadlock situation.
92 depending on the intended use of the object.
98 is specified, information usable in
99 creating, renaming, or deleting a directory entry may be calculated.
101 Overall outline of VOP_LOOKUP:
102 .Bd -ragged -offset indent
103 Check accessibility of directory.
104 Look for name in cache, if found, then return name.
105 Search for name in directory, goto to found or notfound as appropriate.
109 .Bd -ragged -offset indent
110 If creating or renaming and at end of pathname,
113 leaving info on available slots else return
118 .Bd -ragged -offset indent
119 If at end of path and deleting, return information to allow delete.
120 If at end of path and renaming, lock target
121 inode and return info to allow rename.
122 If not at end, add name to cache; if at end and neither creating
123 nor deleting, add name to cache.
128 should be locked on entry.
129 If an error (note: the return value
131 is not considered an error)
132 is detected, it will be returned locked.
133 Otherwise, it will be unlocked unless both
139 If an entry is found in the directory, it will be returned locked.
141 Zero is returned with
143 set to the locked vnode of the file if the component is found.
144 If the component being searched for is ".", then the vnode just has
145 an extra reference added to it with
147 The caller must take care to release the locks appropriately in this
150 If the component is not found and the operation is
156 is specified and the operation would succeed, the special return value
159 Otherwise, an appropriate error code is returned.
163 vop_lookup(struct vnode *dvp,
165 struct componentname *cnp)
168 int nameiop = cnp->cn_nameiop;
169 int flags = cnp->cn_flags;
170 int lockparent = flags & LOCKPARENT;
171 int islastcn = flags & ISLASTCN;
172 struct vnode *vp = NULL;
175 * Check accessibility of directory.
177 if (dvp->v_type != VDIR)
180 error = VOP_ACCESS(dvp, VEXEC, cred, cnp->cn_proc);
184 if (islastcn && (dvp->v_mount->mnt_flag & MNT_RDONLY) &&
185 (cnp->cn_nameiop == DELETE || cnp->cn_nameiop == RENAME))
189 * Check name cache for directory/name pair. This returns ENOENT
190 * if the name is known not to exist, -1 if the name was found, or
193 error = cache_lookup(dvp, vpp, cnp);
201 if (dvp == vp) { /* lookup on "." */
204 } else if (flags & ISDOTDOT) {
206 * We need to unlock the directory before getting
207 * the locked vnode for ".." to avoid deadlocks.
212 if (lockparent && islastcn)
213 error = VOP_LOCK(dvp);
217 if (error || !(lockparent && islastcn)) {
223 * Check that the capability number did not change
224 * while we were waiting for the lock.
227 if (vpid == vp->v_id) {
229 * dvp is locked if lockparent && islastcn.
236 if (dvp != vp && lockparent && islastcn)
241 * Re-lock dvp for the directory search below.
243 error = VOP_LOCK(dvp);
252 * Search dvp for the component cnp->cn_nameptr.
257 if ((nameiop == CREATE || nameiop == RENAME)
259 && directory dvp has not been removed) {
261 * Check for write access on directory.
265 * Possibly record the position of a slot in the directory
266 * large enough for the new component name. This can be
267 * recorded in the vnode private data for dvp.
268 * Set the SAVENAME flag to hold onto the pathname for use
269 * later in VOP_CREATE or VOP_RENAME.
271 cnp->cn_flags |= SAVENAME;
274 * Note that the extra data recorded above is only
275 * useful if lockparent is specified.
283 * Consider inserting name into cache.
285 if ((cnp->cn_flags & MAKEENTRY) && nameiop != CREATE)
286 cache_enter(dvp, NULL, cnp);
291 * If deleting, and at end of pathname, return parameters
292 * which can be used to remove file. If the wantparent flag
293 * isn't set, we return only the directory, otherwise we go on
294 * and lock the inode, being careful with ".".
296 if (nameiop == DELETE && islastcn) {
298 * Check for write access on directory.
300 error = VOP_ACCESS(dvp, VWRITE, cred, cnp->cn_proc);
304 if (found entry is same as dvp) {
310 error = VFS_VGET(dvp->v_mount, ..., &vp);
314 if (directory is sticky
316 && cred->cr_uid != owner of dvp
317 && owner of vp != cred->cr_uid) {
329 * If rewriting (RENAME), return the inode and the
330 * information required to rewrite the present directory
331 * Must get inode of directory entry to verify it's a
332 * regular file, or empty directory.
334 if (nameiop == RENAME && wantparent && islastcn) {
335 error = VOP_ACCESS(dvp, VWRITE, cred, cnp->cn_proc);
342 if (found entry is same as dvp)
345 error = VFS_VGET(dvp->v_mount, ..., &vp);
350 * Save the name for use in VOP_RENAME later.
352 cnp->cn_flags |= SAVENAME;
360 * Step through the translation in the name. We do not `vput' the
361 * directory because we may need it again if a symbolic link
362 * is relative to the current directory. Instead we save it
363 * unlocked as "pdp". We must get the target inode before unlocking
364 * the directory to insure that the inode will not be removed
365 * before we get it. We prevent deadlock by always fetching
366 * inodes from the root, moving down the directory tree. Thus
367 * when following backward pointers ".." we must unlock the
368 * parent directory before getting the requested directory.
369 * There is a potential race condition here if both the current
370 * and parent directories are removed before the VFS_VGET for the
371 * inode associated with ".." returns. We hope that this occurs
372 * infrequently since we cannot avoid this race condition without
373 * implementing a sophisticated deadlock detection algorithm.
374 * Note also that this simple deadlock detection scheme will not
375 * work if the file system has any hard links other than ".."
376 * that point backwards in the directory structure.
378 if (flags & ISDOTDOT) {
379 VOP_UNLOCK(dvp); /* race to get the inode */
380 error = VFS_VGET(dvp->v_mount, ..., &vp);
385 if (lockparent && islastcn) {
386 error = VOP_LOCK(dvp);
393 } else if (found entry is same as dvp) {
394 VREF(dvp); /* we want ourself, ie "." */
397 error = VFS_VGET(dvp->v_mount, ..., &vp);
400 if (!lockparent || !islastcn)
406 * Insert name into cache if appropriate.
408 if (cnp->cn_flags & MAKEENTRY)
409 cache_enter(dvp, *vpp, cnp);
419 does not represent a directory.
423 was not found in this directory.
425 access for the specified operation is denied.
426 .It Bq Er EJUSTRETURN
431 operation would be successful
449 This man page was written by
451 with some text from comments in