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