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