share/man/man9/VOP_RENAME.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_RENAME.9,v 1.10.2.2 2001/12/17 11:30:18 ru Exp $
  30 .\" $DragonFly: src/share/man/man9/VOP_RENAME.9,v 1.3 2003/07/27 05:36:06 hmp Exp $
  31 .\"
  32 .Dd July 24, 1996
  33 .Os
  34 .Dt VOP_RENAME 9
  35 .Sh NAME
  36 .Nm VOP_RENAME
  37 .Nd rename a file
  38 .Sh SYNOPSIS
  39 .In sys/param.h
  40 .In sys/vnode.h
  41 .Ft int
  42 .Fn VOP_RENAME "struct vnode *fdvp" "struct vnode *fvp" "struct componentname *fcnp" "struct vnode *tdvp" "struct vnode *tvp" "struct componentname *tcnp"
  43 .Sh DESCRIPTION
  44 This renames a file and possibly changes its parent directory.
  45 If the destination object exists, it will be removed first.
  46 .Pp
  47 Its arguments are:
  48 .Bl -tag -width fdvp
  49 .It Fa fdvp
  50 the vnode of the old parent directory
  51 .It Fa fvp
  52 the vnode of the file to be renamed
  53 .It Fa fcnp
  54 pathname information about the file's current name
  55 .It Fa tdvp
  56 the vnode of the new parent directory
  57 .It Fa tvp
  58 the vnode of the target file (if it exists)
  59 .It Fa tcnp
  60 pathname information about the file's new name
  61 .El
  62 .Sh LOCKS
  63 The source directory and file are unlocked but are expected to have their
  64 ref count bumped on entry.  The VOP routine is expected to
  65 .Fn vrele
  66 both prior
  67 to returning.
  68 .Pp
  69 The destination directory and file are locked as well as having their ref
  70 count bumped.  The VOP routine is expected to
  71 .Fn vput
  72 both prior to
  73 returning.
  74 .Sh PSEUDOCODE
  75 .Bd -literal
  76 int
  77 vop_rename(struct vnode *fdvp, struct vnode *fvp, struct componentname *fcnp,
  78            struct vnode *tdvp, struct vnode *tvp, struct componentname *tcnp)
  79 {
  80     int doingdirectory = 0;
  81     int error = 0;
  82
  83     /*
  84      * Check for cross-device rename.
  85      */
  86     if (fvp->v_mount != tdvp->v_mount) {
  87         error = EXDEV;
  88     abortit:
  89         VOP_ABORTOP(tdvp, tcnp);
  90         if (tdvp == tvp)
  91             vrele(tdvp);
  92         else
  93             vput(tdvp);
  94         if (tvp)
  95             vput(tvp);
  96         VOP_ABORTOP(fdvp, fcnp);
  97         vrele(fdvp);
  98         vrele(fvp);
  99         return error;
 100     }
 101
 102     if (tvp exists and is immutable) {
 103         error = EPERM;
 104         goto abortit;
 105     }
 106
 107     /*
 108      * Check if just deleting a link name.
 109      */
 110     if (fvp == tvp) {
 111         if (fvp->v_type == VDIR) {
 112             error = EINVAL;
 113             goto abortit;
 114         }
 115
 116         /*
 117          * Release destination.
 118          */
 119         VOP_ABORTOP(tdvp, tcnp);
 120         vput(tdvp);
 121         vput(tvp);
 122
 123         /*
 124          * Delete source.  Pretty bizarre stuff.
 125          */
 126         vrele(fdvp);
 127         vrele(fvp);
 128         fcnp->cn_flags &= ~MODMASK;
 129         fcnp->cn_flags |= LOCKPARENT | LOCKLEAF;
 130         fcnp->cn_nameiop = DELETE;
 131         VREF(fdvp);
 132         error = relookup(fdvp, &fvp, fcnp);
 133         if (error == 0)
 134             vrele(fdvp);
 135         return VOP_REMOVE(fdvp, fvp, fcnp);
 136     }
 137
 138     if (fvp is immutable) {
 139         error = EPERM;
 140         goto abortit;
 141     }
 142
 143     error = VOP_LOCK(fvp);
 144     if (error)
 145         goto abortit;
 146
 147     if (vp is a directory) {
 148         /*
 149          * Avoid ".", "..", and aliases of "." for obvious reasons.
 150          */
 151         if ((fcnp->cn_namelen == 1 && fcnp->cn_nameptr[0] == '.')
 152             || fdvp == fvp
 153             || ((fcnp->cn_flags | tcnp->cn_flags) & ISDOTDOT)) {
 154             VOP_UNLOCK(fvp);
 155             error = EINVAL;
 156             goto abortit;
 157         }
 158         doingdirectory = 1;
 159     }
 160     vrele(fdvp);
 161
 162     /*
 163      * Bump link count on fvp while we are moving stuff around.  If we
 164      * crash before completing the work, the link count may be wrong
 165      * but correctable.
 166      */
 167     ...;
 168
 169     /*
 170      * If ".." must be changed (ie the directory gets a new
 171      * parent) then the source directory must not be in the
 172      * directory hierarchy above the target, as this would
 173      * orphan everything below the source directory. Also
 174      * the user must have write permission in the source so
 175      * as to be able to change "..".
 176      */
 177     error = VOP_ACCESS(fvp, VWRITE, tcnp->cn_cred, tcnp->cn_proc);
 178     VOP_UNLOCK(fvp);
 179     if (doingdirectory && fdvp != tdvp) {
 180         /*
 181          * Check for pathname conflict.
 182          */
 183         ...;
 184     }
 185
 186     /*
 187      * If the target doesn't exist, link the target to the source and
 188      * unlink the source.  Otherwise, rewrite the target directory to
 189      * reference the source and remove the original entry.
 190      */
 191     if (tvp == NULL) {
 192         /*
 193          * Account for ".." in new directory.
 194          */
 195         if (doingdirectory && fdvp != tdvp) {
 196             /*
 197              * Increase link count of tdvp.
 198              */
 199             ...;
 200         }
 201
 202         /*
 203          * Add name in new directory.
 204          */
 205         ...;
 206
 207         if (error) {
 208             if (doingdirectory && fdvp != tdvp) {
 209                 /*
 210                  * Decrease link count if tdvp.
 211                  */
 212                 ...;
 213             }
 214             goto bad;
 215         }
 216         vput(tdvp);
 217     } else {
 218         /*
 219          * Target must be empty if a directory and have no links
 220          * to it. Also, ensure source and target are compatible
 221          * (both directories, or both not directories).
 222          */
 223         if (tvp is a directory) {
 224             if (tvp is not empty) {
 225                 error = ENOTEMPTY;
 226                 goto bad;
 227             }
 228             if (!doingdirectory) {
 229                 error = ENOTDIR;
 230                 goto bad;
 231             }
 232             /*
 233              * Update name cache since directory is going away.
 234              */
 235             cache_purge(tdvp);
 236         } else if (doingdirectory) {
 237             error = ENOTDIR;
 238             goto bad;
 239         }
 240
 241         /*
 242          * Change name tcnp in tdvp to point at fvp.
 243          */
 244         ...;
 245
 246         /*
 247          * If the target directory is in same directory as the source
 248          * directory, decrement the link count on the parent of the
 249          * target directory.  This accounts for the fact that a
 250          * directory links back to its parent with "..".
 251          */
 252         if (doingdirectory && fdvp == tdvp) {
 253             /*
 254              * Decrement link count of tdvp.
 255              */
 256             ...;
 257         }
 258         vput(tdvp);
 259
 260         /*
 261          * Decrement the link count of tvp since the directory no
 262          * longer points at it.
 263          */
 264         ...;
 265         if (doingdirectory) {
 266             /*
 267              * Clean up the old directory tvp.
 268              */
 269             ...;
 270         }
 271         vput(tvp);
 272     }
 273
 274     /*
 275      * Unlink the source.  If a directory was moved to a new parent,
 276      * update its ".." entry.  Gobs of ugly UFS code omitted here.
 277      */
 278     ...;
 279
 280 bad:
 281     if (tvp)
 282         vput(tvp);
 283     vput(tdvp);
 284 out:
 285     if (VOP_LOCK(fvp) == 0) {
 286         /*
 287          * Decrement link count of fvp.
 288          */
 289         ...;
 290         vput(fvp);
 291     } else
 292         vrele(fvp);
 293
 294     return error;
 295 }
 296 .Ed
 297 .Sh ERRORS
 298 .Bl -tag -width Er
 299 .It Bq Er EPERM
 300 the file is immutable
 301 .It Bq Er EXDEV
 302 cross device move
 303 .It Bq Er EINVAL
 304 illegal directory rename
 305 .It Bq Er ENOTDIR
 306 attempt to rename a directory to a file or vice versa
 307 .It Bq Er ENOTEMPTY
 308 attempt to remove a directory which is not empty
 309 .El
 310 .Sh SEE ALSO
 311 .Xr vnode 9
 312 .Sh AUTHORS
 313 This man page was written by
 314 .An Doug Rabson .