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 .\" 4. 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 April 10, 2008
  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 The
  80 .Fn renameat
  81 system call is equivalent to
  82 .Fn rename
  83 except in the case where either
  84 .Fa from
  85 or
  86 .Fa to
  87 specifies a relative path.
  88 If
  89 .Fa from
  90 is a relative path, the file to be renamed is located
  91 relative to the directory associated with the file descriptor
  92 .Fa fromfd
  93 instead of the current working directory.
  94 If the
  95 .Fa to
  96 is a relative path, the same happens only relative to the directory associated
  97 with
  98 .Fa tofd .
  99 If the
 100 .Fn renameat
 101 is passed the special value
 102 .Dv AT_FDCWD
 103 in the
 104 .Fa fromfd
 105 or
 106 .Fa tofd
 107 parameter, the current working directory is used in the determination
 108 of the file for the respective path parameter.
 109 .\".Sh CAVEAT
 110 .\"The system can deadlock if a loop in the file system graph is present.
 111 .\"This loop takes the form of an entry in directory
 112 .\".Pa a ,
 113 .\"say
 114 .\".Pa a/foo ,
 115 .\"being a hard link to directory
 116 .\".Pa b ,
 117 .\"and an entry in
 118 .\"directory
 119 .\".Pa b ,
 120 .\"say
 121 .\".Pa b/bar ,
 122 .\"being a hard link
 123 .\"to directory
 124 .\".Pa a .
 125 .\"When such a loop exists and two separate processes attempt to
 126 .\"perform
 127 .\".Ql rename a/foo b/bar
 128 .\"and
 129 .\".Ql rename b/bar a/foo ,
 130 .\"respectively,
 131 .\"the system may deadlock attempting to lock
 132 .\"both directories for modification.
 133 .\"Hard links to directories should be
 134 .\"replaced by symbolic links by the system administrator.
 135 .Sh RETURN VALUES
 136 .Rv -std rename
 137 .Sh ERRORS
 138 The
 139 .Fn rename
 140 system call
 141 will fail and neither of the argument files will be
 142 affected if:
 143 .Bl -tag -width Er
 144 .It Bq Er ENAMETOOLONG
 145 A component of either pathname exceeded 255 characters,
 146 or the entire length of either path name exceeded 1023 characters.
 147 .It Bq Er ENOENT
 148 A component of the
 149 .Fa from
 150 path does not exist,
 151 or a path prefix of
 152 .Fa to
 153 does not exist.
 154 .It Bq Er EACCES
 155 A component of either path prefix denies search permission.
 156 .It Bq Er EACCES
 157 The requested link requires writing in a directory with a mode
 158 that denies write permission.
 159 .It Bq Er EACCES
 160 The directory pointed at by the
 161 .Fa from
 162 argument denies write permission, and the operation would move
 163 it to another parent directory.
 164 .It Bq Er EPERM
 165 The file pointed at by the
 166 .Fa from
 167 argument has its immutable, undeletable or append-only flag set, see the
 168 .Xr chflags 2
 169 manual page for more information.
 170 .It Bq Er EPERM
 171 The parent directory of the file pointed at by the
 172 .Fa from
 173 argument has its immutable or append-only flag set.
 174 .It Bq Er EPERM
 175 The parent directory of the file pointed at by the
 176 .Fa to
 177 argument has its immutable flag set.
 178 .It Bq Er EPERM
 179 The directory containing
 180 .Fa from
 181 is marked sticky,
 182 and neither the containing directory nor
 183 .Fa from
 184 are owned by the effective user ID.
 185 .It Bq Er EPERM
 186 The file pointed at by the
 187 .Fa to
 188 argument
 189 exists,
 190 the directory containing
 191 .Fa to
 192 is marked sticky,
 193 and neither the containing directory nor
 194 .Fa to
 195 are owned by the effective user ID.
 196 .It Bq Er ELOOP
 197 Too many symbolic links were encountered in translating either pathname.
 198 .It Bq Er ENOTDIR
 199 A component of either path prefix is not a directory.
 200 .It Bq Er ENOTDIR
 201 The
 202 .Fa from
 203 argument
 204 is a directory, but
 205 .Fa to
 206 is not a directory.
 207 .It Bq Er EISDIR
 208 The
 209 .Fa to
 210 argument
 211 is a directory, but
 212 .Fa from
 213 is not a directory.
 214 .It Bq Er EXDEV
 215 The link named by
 216 .Fa to
 217 and the file named by
 218 .Fa from
 219 are on different logical devices (file systems).
 220 Note that this error
 221 code will not be returned if the implementation permits cross-device
 222 links.
 223 .It Bq Er ENOSPC
 224 The directory in which the entry for the new name is being placed
 225 cannot be extended because there is no space left on the file
 226 system containing the directory.
 227 .It Bq Er EDQUOT
 228 The directory in which the entry for the new name
 229 is being placed cannot be extended because the
 230 user's quota of disk blocks on the file system
 231 containing the directory has been exhausted.
 232 .It Bq Er EIO
 233 An I/O error occurred while making or updating a directory entry.
 234 .It Bq Er EROFS
 235 The requested link requires writing in a directory on a read-only file
 236 system.
 237 .It Bq Er EFAULT
 238 Path
 239 points outside the process's allocated address space.
 240 .It Bq Er EINVAL
 241 The
 242 .Fa from
 243 argument
 244 is a parent directory of
 245 .Fa to ,
 246 or an attempt is made to rename
 247 .Ql .\&
 248 or
 249 .Ql \&.. .
 250 .It Bq Er ENOTEMPTY
 251 The
 252 .Fa to
 253 argument
 254 is a directory and is not empty.
 255 .El
 256 .Pp
 257 In addition to the errors returned by the
 258 .Fn rename ,
 259 the
 260 .Fn renameat
 261 may fail if:
 262 .Bl -tag -width Er
 263 .It Bq Er EBADF
 264 The
 265 .Fa from
 266 argument does not specify an absolute path and the
 267 .Fa fromfd
 268 argument is neither
 269 .Dv AT_FDCWD
 270 nor a valid file descriptor open for searching, or the
 271 .Fa to
 272 argument does not specify an absolute path and the
 273 .Fa tofd
 274 argument is neither
 275 .Dv AT_FDCWD
 276 nor a valid file descriptor open for searching.
 277 .It Bq Er ENOTDIR
 278 The
 279 .Fa from
 280 argument is not an absolute path and
 281 .Fa fromfd
 282 is neither
 283 .Dv AT_FDCWD
 284 nor a file descriptor associated with a directory, or the
 285 .Fa to
 286 argument is not an absolute path and
 287 .Fa tofd
 288 is neither
 289 .Dv AT_FDCWD
 290 nor a file descriptor associated with a directory.
 291 .El
 292 .Sh SEE ALSO
 293 .Xr chflags 2 ,
 294 .Xr open 2 ,
 295 .Xr symlink 7
 296 .Sh STANDARDS
 297 The
 298 .Fn rename
 299 system call is expected to conform to
 300 .St -p1003.1-96 .
 301 The
 302 .Fn renameat
 303 system call follows The Open Group Extended API Set 2 specification.
 304 .Sh HISTORY
 305 The
 306 .Fn renameat
 307 system call appeared in
 308 .Fx 8.0 .