usr/src/man/man2/rename.2

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH RENAME 2 "Oct 4, 2007"
   8 .SH NAME
   9 rename, renameat \- change the name of a file
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <stdio.h>
  14
  15 \fBint\fR \fBrename\fR(\fBconst char *\fR\fIold\fR, \fBconst char *\fR\fInew\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 #include <unistd.h>
  21
  22 \fBint\fR \fBrenameat\fR(\fBint\fR \fIfromfd\fR, \fBconst char *\fR\fIold\fR, \fBint\fR \fItofd\fR,
  23      \fBconst char *\fR\fInew\fR);
  24 .fi
  25
  26 .SS "XPG3"
  27 .LP
  28 .nf
  29 #include <unistd.h>
  30
  31 \fBint\fR \fBrename\fR(\fBconst char *\fR\fIold\fR, \fBconst char *\fR\fInew\fR);
  32 .fi
  33
  34 .SH DESCRIPTION
  35 .sp
  36 .LP
  37 The  \fBrename()\fR function changes the name of a file. The \fIold\fR argument
  38 points to the pathname of the file to be renamed. The \fInew\fR argument points
  39 to the new path name of the file.
  40 .sp
  41 .LP
  42 The \fBrenameat()\fR function renames an entry in a directory, possibly moving
  43 the entry into a different directory.  See \fBfsattr\fR(5). If the \fIold\fR
  44 argument is an absolute path, the \fIfromfd\fR is ignored.  Otherwise it is
  45 resolved relative to the \fIfromfd\fR argument rather than the current working
  46 directory.  Similarly, if the \fInew\fR argument is not absolute, it is
  47 resolved relative to the \fItofd\fR argument.  If either \fIfromfd\fR or
  48 \fItofd\fR have the value \fBAT_FDCWD\fR, defined in <\fBfcntl.h\fR>, and their
  49 respective paths are relative, the path is resolved relative to the current
  50 working directory.
  51 .sp
  52 .LP
  53 Current implementation restrictions will cause the \fBrenameat()\fR function to
  54 return an error if an attempt is made to rename an extended attribute file to a
  55 regular (non-attribute) file, or to rename a regular file to an extended
  56 attribute file.
  57 .sp
  58 .LP
  59 If \fIold\fR and \fInew\fR both refer to the same existing file, the
  60 \fBrename()\fR and \fBrenameat()\fR functions return successfully and performs
  61 no other action.
  62 .sp
  63 .LP
  64 If \fIold\fR points to the pathname of a file that is not a directory,
  65 \fInew\fR must not point to the pathname of a directory. If the link named by
  66 \fInew\fR exists, it will be removed and \fIold\fR will be renamed to
  67 \fInew\fR. In this case, a link named \fInew\fR must remain visible to other
  68 processes throughout the renaming operation and will refer to either the file
  69 referred to by \fInew\fR or the file referred to as \fIold\fR before the
  70 operation began.
  71 .sp
  72 .LP
  73 If \fIold\fR points to the pathname of a directory, \fInew\fR  must not point
  74 to the pathname of a file that is not a directory. If the directory named by
  75 \fInew\fR exists, it will be removed and \fIold\fR will be renamed to
  76 \fInew\fR. In this case, a link named \fInew\fR  will exist throughout the
  77 renaming operation and will refer to either the file referred to by \fInew\fR
  78 or the file referred to as \fIold\fR before the operation began. Thus, if
  79 \fInew\fR names  an existing directory, it must be an empty directory.
  80 .sp
  81 .LP
  82 The \fInew\fR pathname must not contain a path prefix that names \fIold\fR.
  83 Write access permission is required for both the directory containing \fIold\fR
  84 and the directory containing \fInew\fR. If \fIold\fR points to the  pathname of
  85 a directory, write access permission is required for the  directory named by
  86 \fIold\fR, and, if it exists, the directory  named by \fInew\fR.
  87 .sp
  88 .LP
  89 If the directory containing \fIold\fR has the sticky bit set,  at least one of
  90 the following conditions listed below must be true:
  91 .RS +4
  92 .TP
  93 .ie t \(bu
  94 .el o
  95 the user must own \fIold\fR
  96 .RE
  97 .RS +4
  98 .TP
  99 .ie t \(bu
 100 .el o
 101 the user must own the directory containing \fIold\fR
 102 .RE
 103 .RS +4
 104 .TP
 105 .ie t \(bu
 106 .el o
 107 \fIold\fR must be writable by the user
 108 .RE
 109 .RS +4
 110 .TP
 111 .ie t \(bu
 112 .el o
 113 the user must be a privileged user
 114 .RE
 115 .sp
 116 .LP
 117 If \fInew\fR exists, and the directory containing \fInew\fR is writable and has
 118 the sticky bit set, at least  one of the following conditions must be true:
 119 .RS +4
 120 .TP
 121 .ie t \(bu
 122 .el o
 123 the user must own \fInew\fR
 124 .RE
 125 .RS +4
 126 .TP
 127 .ie t \(bu
 128 .el o
 129 the user must own the directory containing \fInew\fR
 130 .RE
 131 .RS +4
 132 .TP
 133 .ie t \(bu
 134 .el o
 135 \fInew\fR must be writable by the user
 136 .RE
 137 .RS +4
 138 .TP
 139 .ie t \(bu
 140 .el o
 141 the user must be a privileged user
 142 .RE
 143 .sp
 144 .LP
 145 If the link named by \fInew\fR exists, the file's link count becomes zero when
 146 it is removed, and no process has the file open, then  the space occupied by
 147 the file will be freed and the file will no longer be accessible. If one or
 148 more processes have the file open when the last link is removed, the link will
 149 be removed before \fBrename()\fR or \fBrenameat()\fR returns, but the removal
 150 of the file contents will be postponed until all references to the file have
 151 been closed.
 152 .sp
 153 .LP
 154 Upon successful completion, the \fBrename()\fR and \fBrenameat()\fR functions
 155 will mark for update the \fBst_ctime\fR and \fBst_mtime\fR fields of the parent
 156 directory of each file.
 157 .SH RETURN VALUES
 158 .sp
 159 .LP
 160 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
 161 returned and \fBerrno\fR is set to indicate an error.
 162 .SH ERRORS
 163 .sp
 164 .LP
 165 The \fBrename()\fR function will fail if:
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBEACCES\fR\fR
 170 .ad
 171 .RS 16n
 172 A component of either path prefix denies search permission; one of the
 173 directories containing \fIold\fR and \fInew\fR denies write permissions; or
 174 write permission is denied by a directory pointed to by \fIold\fR or \fInew\fR.
 175 .RE
 176
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBEBUSY\fR\fR
 181 .ad
 182 .RS 16n
 183 The \fInew\fR argument is a directory and the mount point for a mounted file
 184 system.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBEDQUOT\fR\fR
 191 .ad
 192 .RS 16n
 193 The directory where the new name entry is being placed cannot be extended
 194 because the user's quota of disk blocks on that file system has been exhausted.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBEEXIST\fR\fR
 201 .ad
 202 .RS 16n
 203 The link named by \fInew\fR is a directory containing entries other than
 204 `\fB\&.\fR' (the directory itself) and `\fB\&..\fR' (the parent directory).
 205 .RE
 206
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fBEFAULT\fR\fR
 211 .ad
 212 .RS 16n
 213 Either \fIold\fR or \fInew\fR references an invalid address.
 214 .RE
 215
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fBEILSEQ\fR\fR
 220 .ad
 221 .RS 16n
 222 The path argument includes non-UTF8 characters and the file system accepts only
 223 file names where all characters are part of the UTF-8 character codeset.
 224 .RE
 225
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBEINVAL\fR\fR
 230 .ad
 231 .RS 16n
 232 The \fInew\fR argument directory pathname contains a path prefix that names the
 233 \fIold\fR directory, or an attempt was made to rename a regular file to an
 234 extended attribute or from an extended attribute to a regular file.
 235 .RE
 236
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fBEIO\fR\fR
 241 .ad
 242 .RS 16n
 243 An I/O error occurred while making or updating a directory entry.
 244 .RE
 245
 246 .sp
 247 .ne 2
 248 .na
 249 \fB\fBEISDIR\fR\fR
 250 .ad
 251 .RS 16n
 252 The \fInew\fR argument points to a directory but \fIold\fR points to a file
 253 that is not a directory.
 254 .RE
 255
 256 .sp
 257 .ne 2
 258 .na
 259 \fB\fBELOOP\fR\fR
 260 .ad
 261 .RS 16n
 262 Too many symbolic links were encountered in translating the pathname.
 263 .RE
 264
 265 .sp
 266 .ne 2
 267 .na
 268 \fB\fBENAMETOOLONG\fR\fR
 269 .ad
 270 .RS 16n
 271 The length of \fIold\fR or \fInew\fR exceeds  \fBPATH_MAX\fR, or a pathname
 272 component is longer than  \fBNAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in
 273 effect.
 274 .RE
 275
 276 .sp
 277 .ne 2
 278 .na
 279 \fB\fBEMLINK\fR\fR
 280 .ad
 281 .RS 16n
 282 The file named by \fIold\fR is a directory, and the link count of  the parent
 283 directory of \fInew\fR would exceed  \fBLINK_MAX\fR.
 284 .RE
 285
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fBENOENT\fR\fR
 290 .ad
 291 .RS 16n
 292 The link named by \fIold\fR does not name an existing file, a component of the
 293 path prefix of \fInew\fR does not exist, or either \fIold\fR or \fInew\fR
 294 points to an empty string.
 295 .RE
 296
 297 .sp
 298 .ne 2
 299 .na
 300 \fB\fBENOSPC\fR\fR
 301 .ad
 302 .RS 16n
 303 The directory that would contain \fInew\fR cannot be extended.
 304 .RE
 305
 306 .sp
 307 .ne 2
 308 .na
 309 \fB\fBENOTDIR\fR\fR
 310 .ad
 311 .RS 16n
 312 A component of either path prefix is not a directory, or \fIold\fR names a
 313 directory and \fInew\fR names a file that is not a directory, or \fItofd\fR and
 314 \fIdirfd\fR in \fBrenameat()\fR do not reference a directory.
 315 .RE
 316
 317 .sp
 318 .ne 2
 319 .na
 320 \fB\fBEROFS\fR\fR
 321 .ad
 322 .RS 16n
 323 The requested operation requires writing in a directory on a read-only file
 324 system.
 325 .RE
 326
 327 .sp
 328 .ne 2
 329 .na
 330 \fB\fBEXDEV\fR\fR
 331 .ad
 332 .RS 16n
 333 The links named by \fIold\fR and \fInew\fR are on different file systems.
 334 .RE
 335
 336 .sp
 337 .LP
 338 The \fBrenameat()\fR functions will fail if:
 339 .sp
 340 .ne 2
 341 .na
 342 \fB\fBENOTSUP\fR\fR
 343 .ad
 344 .RS 11n
 345 An attempt was made to rename a regular file as an attribute file or to rename
 346 an attribute file as a regular file.
 347 .RE
 348
 349 .SH ATTRIBUTES
 350 .sp
 351 .LP
 352 See \fBattributes\fR(5) for descriptions of the following attributes:
 353 .sp
 354
 355 .sp
 356 .TS
 357 box;
 358 c | c
 359 l | l .
 360 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 361 _
 362 Interface Stability     Committed
 363 _
 364 MT-Level        Async-Signal-Safe
 365 _
 366 Standard        For \fBrename()\fR, see \fBstandards\fR(5).
 367 .TE
 368
 369 .SH SEE ALSO
 370 .sp
 371 .LP
 372 \fBchmod\fR(2), \fBlink\fR(2), \fBunlink\fR(2), \fBattributes\fR(5),
 373 \fBfsattr\fR(5), \fBstandards\fR(5)
 374 .SH NOTES
 375 .sp
 376 .LP
 377 The system can deadlock if there is a loop in the file system graph. Such a
 378 loop can occur if there is an entry in directory \fBa\fR, \fBa/name1\fR, that
 379 is a hard link to directory \fBb\fR, and an entry in directory \fBb\fR,
 380 \fBb/name2\fR, that is a hard link to directory \fBa\fR. When such a loop
 381 exists and two separate processes attempt to rename \fBa/name1\fR to
 382 \fBb/name2\fR and \fBb/name2\fR to \fBa/name1\fR, the system may deadlock
 383 attempting to lock  both directories for modification.  Use symbolic links
 384 instead of hard links  for directories.