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