share/man/man9/VOP_RENAME.9

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