lib/libc/sys/rename.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd March 30, 2020
  29 .Dt RENAME 2
  30 .Os
  31 .Sh NAME
  32 .Nm rename
  33 .Nd change the name of a file
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In stdio.h
  38 .Ft int
  39 .Fn rename "const char *from" "const char *to"
  40 .Ft int
  41 .Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn rename
  45 system call
  46 causes the link named
  47 .Fa from
  48 to be renamed as
  49 .Fa to .
  50 If
  51 .Fa to
  52 exists, it is first removed.
  53 Both
  54 .Fa from
  55 and
  56 .Fa to
  57 must be of the same type (that is, both directories or both
  58 non-directories), and must reside on the same file system.
  59 .Pp
  60 The
  61 .Fn rename
  62 system call
  63 guarantees that if
  64 .Fa to
  65 already exists, an instance of
  66 .Fa to
  67 will always exist, even if the system should crash in
  68 the middle of the operation.
  69 .Pp
  70 If the final component of
  71 .Fa from
  72 is a symbolic link,
  73 the symbolic link is renamed,
  74 not the file or directory to which it points.
  75 .Pp
  76 If
  77 .Fa from
  78 and
  79 .Fa to
  80 resolve to the same directory entry, or to different directory
  81 entries for the same existing file,
  82 .Fn rename
  83 returns success without taking any further action.
  84 .Pp
  85 The
  86 .Fn renameat
  87 system call is equivalent to
  88 .Fn rename
  89 except in the case where either
  90 .Fa from
  91 or
  92 .Fa to
  93 specifies a relative path.
  94 If
  95 .Fa from
  96 is a relative path, the file to be renamed is located
  97 relative to the directory associated with the file descriptor
  98 .Fa fromfd
  99 instead of the current working directory.
 100 If the
 101 .Fa to
 102 is a relative path, the same happens only relative to the directory associated
 103 with
 104 .Fa tofd .
 105 If the
 106 .Fn renameat
 107 is passed the special value
 108 .Dv AT_FDCWD
 109 in the
 110 .Fa fromfd
 111 or
 112 .Fa tofd
 113 parameter, the current working directory is used in the determination
 114 of the file for the respective path parameter.
 115 .\".Sh CAVEAT
 116 .\"The system can deadlock if a loop in the file system graph is present.
 117 .\"This loop takes the form of an entry in directory
 118 .\".Pa a ,
 119 .\"say
 120 .\".Pa a/foo ,
 121 .\"being a hard link to directory
 122 .\".Pa b ,
 123 .\"and an entry in
 124 .\"directory
 125 .\".Pa b ,
 126 .\"say
 127 .\".Pa b/bar ,
 128 .\"being a hard link
 129 .\"to directory
 130 .\".Pa a .
 131 .\"When such a loop exists and two separate processes attempt to
 132 .\"perform
 133 .\".Ql rename a/foo b/bar
 134 .\"and
 135 .\".Ql rename b/bar a/foo ,
 136 .\"respectively,
 137 .\"the system may deadlock attempting to lock
 138 .\"both directories for modification.
 139 .\"Hard links to directories should be
 140 .\"replaced by symbolic links by the system administrator.
 141 .Sh RETURN VALUES
 142 .Rv -std rename
 143 .Sh ERRORS
 144 The
 145 .Fn rename
 146 system call
 147 will fail and neither of the argument files will be
 148 affected if:
 149 .Bl -tag -width Er
 150 .It Bq Er ENAMETOOLONG
 151 A component of either pathname exceeded 255 characters,
 152 or the entire length of either path name exceeded 1023 characters.
 153 .It Bq Er ENOENT
 154 A component of the
 155 .Fa from
 156 path does not exist,
 157 or a path prefix of
 158 .Fa to
 159 does not exist.
 160 .It Bq Er EACCES
 161 A component of either path prefix denies search permission.
 162 .It Bq Er EACCES
 163 The requested link requires writing in a directory with a mode
 164 that denies write permission.
 165 .It Bq Er EACCES
 166 The directory pointed at by the
 167 .Fa from
 168 argument denies write permission, and the operation would move
 169 it to another parent directory.
 170 .It Bq Er EPERM
 171 The file pointed at by the
 172 .Fa from
 173 argument has its immutable, undeletable or append-only flag set, see the
 174 .Xr chflags 2
 175 manual page for more information.
 176 .It Bq Er EPERM
 177 The parent directory of the file pointed at by the
 178 .Fa from
 179 argument has its immutable or append-only flag set.
 180 .It Bq Er EPERM
 181 The parent directory of the file pointed at by the
 182 .Fa to
 183 argument has its immutable flag set.
 184 .It Bq Er EPERM
 185 The directory containing
 186 .Fa from
 187 is marked sticky,
 188 and neither the containing directory nor
 189 .Fa from
 190 are owned by the effective user ID.
 191 .It Bq Er EPERM
 192 The file pointed at by the
 193 .Fa to
 194 argument
 195 exists,
 196 the directory containing
 197 .Fa to
 198 is marked sticky,
 199 and neither the containing directory nor
 200 .Fa to
 201 are owned by the effective user ID.
 202 .It Bq Er ELOOP
 203 Too many symbolic links were encountered in translating either pathname.
 204 .It Bq Er ENOTDIR
 205 A component of either path prefix is not a directory.
 206 .It Bq Er ENOTDIR
 207 The
 208 .Fa from
 209 argument
 210 is a directory, but
 211 .Fa to
 212 is not a directory.
 213 .It Bq Er EISDIR
 214 The
 215 .Fa to
 216 argument
 217 is a directory, but
 218 .Fa from
 219 is not a directory.
 220 .It Bq Er EXDEV
 221 The link named by
 222 .Fa to
 223 and the file named by
 224 .Fa from
 225 are on different logical devices (file systems).
 226 Note that this error
 227 code will not be returned if the implementation permits cross-device
 228 links.
 229 .It Bq Er ENOSPC
 230 The directory in which the entry for the new name is being placed
 231 cannot be extended because there is no space left on the file
 232 system containing the directory.
 233 .It Bq Er EDQUOT
 234 The directory in which the entry for the new name
 235 is being placed cannot be extended because the
 236 user's quota of disk blocks on the file system
 237 containing the directory has been exhausted.
 238 .It Bq Er EIO
 239 An I/O error occurred while making or updating a directory entry.
 240 .It Bq Er EINTEGRITY
 241 Corrupted data was detected while reading from the file system.
 242 .It Bq Er EROFS
 243 The requested link requires writing in a directory on a read-only file
 244 system.
 245 .It Bq Er EFAULT
 246 Path
 247 points outside the process's allocated address space.
 248 .It Bq Er EINVAL
 249 The
 250 .Fa from
 251 argument
 252 is a parent directory of
 253 .Fa to ,
 254 or an attempt is made to rename
 255 .Ql .\&
 256 or
 257 .Ql \&.. .
 258 .It Bq Er ENOTEMPTY
 259 The
 260 .Fa to
 261 argument
 262 is a directory and is not empty.
 263 .It Bq Er ECAPMODE
 264 .Fn rename
 265 was called and the process is in capability mode.
 266 .El
 267 .Pp
 268 In addition to the errors returned by the
 269 .Fn rename ,
 270 the
 271 .Fn renameat
 272 may fail if:
 273 .Bl -tag -width Er
 274 .It Bq Er EBADF
 275 The
 276 .Fa from
 277 argument does not specify an absolute path and the
 278 .Fa fromfd
 279 argument is neither
 280 .Dv AT_FDCWD
 281 nor a valid file descriptor open for searching, or the
 282 .Fa to
 283 argument does not specify an absolute path and the
 284 .Fa tofd
 285 argument is neither
 286 .Dv AT_FDCWD
 287 nor a valid file descriptor open for searching.
 288 .It Bq Er ENOTDIR
 289 The
 290 .Fa from
 291 argument is not an absolute path and
 292 .Fa fromfd
 293 is neither
 294 .Dv AT_FDCWD
 295 nor a file descriptor associated with a directory, or the
 296 .Fa to
 297 argument is not an absolute path and
 298 .Fa tofd
 299 is neither
 300 .Dv AT_FDCWD
 301 nor a file descriptor associated with a directory.
 302 .It Bq Er ECAPMODE
 303 .Dv AT_FDCWD
 304 is specified and the process is in capability mode.
 305 .It Bq Er ENOTCAPABLE
 306 .Fa path
 307 is an absolute path or contained a ".." component leading to a directory
 308 outside of the directory hierarchy specified by
 309 .Fa fromfd
 310 or
 311 .Fa tofd .
 312 .It Bq Er ENOTCAPABLE
 313 The
 314 .Fa fromfd
 315 file descriptor lacks the
 316 .Dv CAP_RENAMEAT_SOURCE
 317 right, or the
 318 .Fa tofd
 319 file descriptor lacks the
 320 .Dv CAP_RENAMEAT_TARGET
 321 right.
 322 .El
 323 .Sh SEE ALSO
 324 .Xr chflags 2 ,
 325 .Xr open 2 ,
 326 .Xr symlink 7
 327 .Sh STANDARDS
 328 The
 329 .Fn rename
 330 system call is expected to conform to
 331 .St -p1003.1-96 .
 332 The
 333 .Fn renameat
 334 system call follows The Open Group Extended API Set 2 specification.
 335 .Sh HISTORY
 336 The
 337 .Fn renameat
 338 system call appeared in
 339 .Fx 8.0 .