share/man/man9/VOP_LOOKUP.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 1996 Doug Rabson
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" This program is free software.
   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 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.
  28 .\"
  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 $
  31 .\"
  32 .Dd November 24, 1997
  33 .Os
  34 .Dt VOP_LOOKUP 9
  35 .Sh NAME
  36 .Nm VOP_LOOKUP
  37 .Nd lookup a component of a pathname
  38 .Sh SYNOPSIS
  39 .In sys/param.h
  40 .In sys/vnode.h
  41 .In sys/namei.h
  42 .Ft int
  43 .Fn VOP_LOOKUP "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp"
  44 .Sh DESCRIPTION
  45 This entry point looks up a single pathname component in a given directory.
  46 .Pp
  47 Its arguments are:
  48 .Bl -tag -width vpp
  49 .It Fa dvp
  50 the locked vnode of the directory to search
  51 .It Fa vpp
  52 the address of a variable where the resulting locked vnode should be stored
  53 .It Fa cnp
  54 the pathname component to be searched for
  55 .El
  56 .Pp
  57 .Fa Cnp
  58 is a pointer to a componentname structure defined as follows:
  59 .Bd -literal
  60 struct componentname {
  61         /*
  62          * Arguments to lookup.
  63          */
  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 */
  68         /*
  69          * Shared between lookup and commit routines.
  70          */
  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() */
  76 };
  77 .Ed
  78 .Pp
  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.
  83 .Pp
  84 The
  85 .Fa cnp->cn_nameiop
  86 argument is
  87 .Dv LOOKUP ,
  88 .Dv CREATE ,
  89 .Dv RENAME ,
  90 or
  91 .Dv DELETE
  92 depending on the intended use of the object.
  93 When
  94 .Dv CREATE ,
  95 .Dv RENAME ,
  96 or
  97 .Dv DELETE
  98 is specified, information usable in
  99 creating, renaming, or deleting a directory entry may be calculated.
 100 .Pp
 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.
 106 .Ed
 107 .Pp
 108 notfound:
 109 .Bd -ragged -offset indent
 110 If creating or renaming and at end of pathname,
 111 return
 112 .Er EJUSTRETURN ,
 113 leaving info on available slots else return
 114 .Er ENOENT .
 115 .Ed
 116 .Pp
 117 found:
 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.
 124 .Ed
 125 .Sh LOCKS
 126 The directory,
 127 .Fa dvp
 128 should be locked on entry.
 129 If an error (note: the return value
 130 .Er EJUSTRETURN
 131 is not considered an error)
 132 is detected, it will be returned locked.
 133 Otherwise, it will be unlocked unless both
 134 .Dv LOCKPARENT
 135 and
 136 .Dv ISLASTCN
 137 are specified in
 138 .Fa cnp->cn_flags .
 139 If an entry is found in the directory, it will be returned locked.
 140 .Sh RETURN VALUES
 141 Zero is returned with
 142 .Fa *vpp
 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
 146 .Xr vref 9 .
 147 The caller must take care to release the locks appropriately in this
 148 case.
 149 .Pp
 150 If the component is not found and the operation is
 151 .Dv CREATE
 152 or
 153 .Dv RENAME ,
 154 the flag
 155 .Dv ISLASTCN
 156 is specified and the operation would succeed, the special return value
 157 .Er EJUSTRETURN
 158 is returned.
 159 Otherwise, an appropriate error code is returned.
 160 .Sh PSEUDOCODE
 161 .Bd -literal
 162 int
 163 vop_lookup(struct vnode *dvp,
 164            struct vnode **vpp,
 165            struct componentname *cnp)
 166 {
 167     int error;
 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;
 173
 174     /*
 175      * Check accessibility of directory.
 176      */
 177     if (dvp->v_type != VDIR)
 178         return ENOTDIR;
 179
 180     error = VOP_ACCESS(dvp, VEXEC, cred, cnp->cn_proc);
 181     if (error)
 182         return (error);
 183
 184     if (islastcn && (dvp->v_mount->mnt_flag & MNT_RDONLY) &&
 185         (cnp->cn_nameiop == DELETE || cnp->cn_nameiop == RENAME))
 186         return (EROFS);
 187
 188     /*
 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
 191      * zero if not.
 192      */
 193     error = cache_lookup(dvp, vpp, cnp);
 194     if (error) {
 195         int vpid;
 196
 197         if (error = ENOENT)
 198             return error;
 199
 200         vp = *vpp;
 201         if (dvp == vp) {        /* lookup on "." */
 202             VREF(vp);
 203             error = 0;
 204         } else if (flags & ISDOTDOT) {
 205             /*
 206              * We need to unlock the directory before getting
 207              * the locked vnode for ".." to avoid deadlocks.
 208              */
 209             VOP_UNLOCK(dvp);
 210             error = vget(vp, 1);
 211             if (!error) {
 212                 if (lockparent && islastcn)
 213                     error = VOP_LOCK(dvp);
 214             }
 215         } else {
 216             error = vget(vp, 1);
 217             if (error || !(lockparent && islastcn)) {
 218                 VOP_UNLOCK(dvp);
 219             }
 220         }
 221
 222         /*
 223          * Check that the capability number did not change
 224          * while we were waiting for the lock.
 225          */
 226         if (!error) {
 227             if (vpid == vp->v_id) {
 228                 /*
 229                  * dvp is locked if lockparent && islastcn.
 230                  * vp is locked.
 231                  */
 232                 return (0);
 233             }
 234             vput(vp);
 235
 236             if (dvp != vp && lockparent && islastcn)
 237                 VOP_UNLOCK(pdp);
 238         }
 239
 240         /*
 241          * Re-lock dvp for the directory search below.
 242          */
 243         error = VOP_LOCK(dvp);
 244         if (error) {
 245             return (error);
 246         }
 247
 248         *vpp = NULL;
 249     }
 250
 251     /*
 252      * Search dvp for the component cnp->cn_nameptr.
 253      */
 254     ...;
 255
 256     if (!found) {
 257         if ((nameiop == CREATE || nameiop == RENAME)
 258             && islastcn
 259             && directory dvp has not been removed) {
 260             /*
 261              * Check for write access on directory.
 262              */
 263
 264             /*
 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.
 270              */
 271             cnp->cn_flags |= SAVENAME;
 272             if (!lockparent)
 273                 /*
 274                  * Note that the extra data recorded above is only
 275                  * useful if lockparent is specified.
 276                  */
 277                 VOP_UNLOCK(dvp);
 278
 279             return EJUSTRETURN;
 280         }
 281
 282         /*
 283          * Consider inserting name into cache.
 284          */
 285         if ((cnp->cn_flags & MAKEENTRY) && nameiop != CREATE)
 286             cache_enter(dvp, NULL, cnp);
 287
 288         return ENOENT;
 289     } else {
 290         /*
 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 ".".
 295          */
 296         if (nameiop == DELETE && islastcn) {
 297             /*
 298              * Check for write access on directory.
 299              */
 300             error = VOP_ACCESS(dvp, VWRITE, cred, cnp->cn_proc);
 301             if (error)
 302                 return (error);
 303
 304             if (found entry is same as dvp) {
 305                 VREF(dvp);
 306                 *vpp = dvp;
 307                 return 0;
 308             }
 309
 310             error = VFS_VGET(dvp->v_mount, ..., &vp);
 311             if (error)
 312                 return error;
 313
 314             if (directory is sticky
 315                 && cred->cr_uid != 0
 316                 && cred->cr_uid != owner of dvp
 317                 && owner of vp != cred->cr_uid) {
 318                 vput(vp);
 319                 return EPERM;
 320             }
 321             *vpp = vp;
 322             if (!lockparent)
 323                 VOP_UNLOCK(dvp);
 324
 325             return 0;
 326         }
 327
 328         /*
 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.
 333          */
 334         if (nameiop == RENAME && wantparent && islastcn) {
 335             error = VOP_ACCESS(dvp, VWRITE, cred, cnp->cn_proc);
 336             if (error)
 337                 return (error);
 338
 339             /*
 340              * Check for "."
 341              */
 342             if (found entry is same as dvp)
 343                 return EISDIR;
 344
 345             error = VFS_VGET(dvp->v_mount, ..., &vp);
 346             if (error)
 347                 return error;
 348             *vpp = vp;
 349             /*
 350              * Save the name for use in VOP_RENAME later.
 351              */
 352             cnp->cn_flags |= SAVENAME;
 353             if (!lockparent)
 354                 VOP_UNLOCK(dvp);
 355
 356             return 0;
 357         }
 358
 359         /*
 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.
 377          */
 378         if (flags & ISDOTDOT) {
 379             VOP_UNLOCK(dvp);    /* race to get the inode */
 380             error = VFS_VGET(dvp->v_mount, ..., &vp);
 381             if (error) {
 382                 VOP_LOCK(dvp);
 383                 return (error);
 384             }
 385             if (lockparent && islastcn) {
 386                 error = VOP_LOCK(dvp);
 387                 if (error) {
 388                     vput(vp);
 389                     return error;
 390                 }
 391             }
 392             *vpp = vp;
 393         } else if (found entry is same as dvp) {
 394             VREF(dvp);  /* we want ourself, ie "." */
 395             *vpp = dvp;
 396         } else {
 397             error = VFS_VGET(dvp->v_mount, ..., &vp);
 398             if (error)
 399                 return (error);
 400             if (!lockparent || !islastcn)
 401                 VOP_UNLOCK(dvp);
 402             *vpp = vp;
 403         }
 404
 405         /*
 406          * Insert name into cache if appropriate.
 407          */
 408         if (cnp->cn_flags & MAKEENTRY)
 409             cache_enter(dvp, *vpp, cnp);
 410         return (0);
 411     }
 412 }
 413 .Ed
 414 .Sh ERRORS
 415 .Bl -tag -width Er
 416 .It Bq Er ENOTDIR
 417 The vnode
 418 .Fa dvp
 419 does not represent a directory.
 420 .It Bq Er ENOENT
 421 The component
 422 .Fa dvp
 423 was not found in this directory.
 424 .It Bq Er EACCES
 425 access for the specified operation is denied.
 426 .It Bq Er EJUSTRETURN
 427 a
 428 .Dv CREATE
 429 or
 430 .Dv RENAME
 431 operation would be successful
 432 .El
 433 .Sh SEE ALSO
 434 .Xr VOP_ABORTOP 9 ,
 435 .Xr VOP_ACCESS 9 ,
 436 .Xr VOP_CREATE 9 ,
 437 .Xr VOP_MKDIR 9 ,
 438 .Xr VOP_MKNOD 9 ,
 439 .Xr VOP_RENAME 9 ,
 440 .Xr VOP_SYMLINK 9
 441 .Sh HISTORY
 442 The function
 443 .Nm
 444 appeared in
 445 .Bx 4.3 .
 446 .Sh SEE ALSO
 447 .Xr vnode 9
 448 .Sh AUTHORS
 449 This man page was written by
 450 .An Doug Rabson ,
 451 with some text from comments in
 452 .Pa ufs_lookup.c .