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 EPERM
 160 The file pointed at by the
 161 .Fa from
 162 argument has its immutable, undeletable or append-only flag set, see the
 163 .Xr chflags 2
 164 manual page for more information.
 165 .It Bq Er EPERM
 166 The parent directory of the file pointed at by the
 167 .Fa from
 168 argument has its immutable or append-only flag set.
 169 .It Bq Er EPERM
 170 The parent directory of the file pointed at by the
 171 .Fa to
 172 argument has its immutable flag set.
 173 .It Bq Er EPERM
 174 The directory containing
 175 .Fa from
 176 is marked sticky,
 177 and neither the containing directory nor
 178 .Fa from
 179 are owned by the effective user ID.
 180 .It Bq Er EPERM
 181 The file pointed at by the
 182 .Fa to
 183 argument
 184 exists,
 185 the directory containing
 186 .Fa to
 187 is marked sticky,
 188 and neither the containing directory nor
 189 .Fa to
 190 are owned by the effective user ID.
 191 .It Bq Er ELOOP
 192 Too many symbolic links were encountered in translating either pathname.
 193 .It Bq Er ENOTDIR
 194 A component of either path prefix is not a directory.
 195 .It Bq Er ENOTDIR
 196 The
 197 .Fa from
 198 argument
 199 is a directory, but
 200 .Fa to
 201 is not a directory.
 202 .It Bq Er EISDIR
 203 The
 204 .Fa to
 205 argument
 206 is a directory, but
 207 .Fa from
 208 is not a directory.
 209 .It Bq Er EXDEV
 210 The link named by
 211 .Fa to
 212 and the file named by
 213 .Fa from
 214 are on different logical devices (file systems).
 215 Note that this error
 216 code will not be returned if the implementation permits cross-device
 217 links.
 218 .It Bq Er ENOSPC
 219 The directory in which the entry for the new name is being placed
 220 cannot be extended because there is no space left on the file
 221 system containing the directory.
 222 .It Bq Er EDQUOT
 223 The directory in which the entry for the new name
 224 is being placed cannot be extended because the
 225 user's quota of disk blocks on the file system
 226 containing the directory has been exhausted.
 227 .It Bq Er EIO
 228 An I/O error occurred while making or updating a directory entry.
 229 .It Bq Er EROFS
 230 The requested link requires writing in a directory on a read-only file
 231 system.
 232 .It Bq Er EFAULT
 233 Path
 234 points outside the process's allocated address space.
 235 .It Bq Er EINVAL
 236 The
 237 .Fa from
 238 argument
 239 is a parent directory of
 240 .Fa to ,
 241 or an attempt is made to rename
 242 .Ql .\&
 243 or
 244 .Ql \&.. .
 245 .It Bq Er ENOTEMPTY
 246 The
 247 .Fa to
 248 argument
 249 is a directory and is not empty.
 250 .El
 251 .Pp
 252 In addition to the errors returned by the
 253 .Fn rename ,
 254 the
 255 .Fn renameat
 256 may fail if:
 257 .Bl -tag -width Er
 258 .It Bq Er EBADF
 259 The
 260 .Fa from
 261 argument does not specify an absolute path and the
 262 .Fa fromfd
 263 argument is neither
 264 .Dv AT_FDCWD
 265 nor a valid file descriptor open for searching, or the
 266 .Fa to
 267 argument does not specify an absolute path and the
 268 .Fa tofd
 269 argument is neither
 270 .Dv AT_FDCWD
 271 nor a valid file descriptor open for searching.
 272 .It Bq Er ENOTDIR
 273 The
 274 .Fa from
 275 argument is not an absolute path and
 276 .Fa fromfd
 277 is neither
 278 .Dv AT_FDCWD
 279 nor a file descriptor associated with a directory, or the
 280 .Fa to
 281 argument is not an absolute path and
 282 .Fa tofd
 283 is neither
 284 .Dv AT_FDCWD
 285 nor a file descriptor associated with a directory.
 286 .El
 287 .Sh SEE ALSO
 288 .Xr chflags 2 ,
 289 .Xr open 2 ,
 290 .Xr symlink 7
 291 .Sh STANDARDS
 292 The
 293 .Fn rename
 294 system call is expected to conform to
 295 .St -p1003.1-96 .
 296 The
 297 .Fn renameat
 298 system call follows The Open Group Extended API Set 2 specification.
 299 .Sh HISTORY
 300 The
 301 .Fn renameat
 302 system call appeared in
 303 .Fx 8.0 .