bsd/man/man2/rename.2

   1 .\"     $NetBSD: rename.2,v 1.7 1995/02/27 12:36:15 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)rename.2    8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd September 18, 2008
  37 .Dt RENAME 2
  38 .Os BSD 4.2
  39 .Sh NAME
  40 .Nm rename ,
  41 .Nm renameat
  42 .Nd change the name of a file
  43 .Sh SYNOPSIS
  44 .Fd #include <stdio.h>
  45 .Ft int
  46 .Fo rename
  47 .Fa "const char *old"
  48 .Fa "const char *new"
  49 .Fc
  50 .Ft int
  51 .Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn rename
  55 system call causes the link named
  56 .Fa old
  57 to be renamed as
  58 .Fa new .
  59 If
  60 .Fa new
  61 exists, it is first removed.
  62 Both
  63 .Fa old
  64 and
  65 .Fa new
  66 must be of the same type
  67 (that is, both must be either directories or non-directories)
  68 and must reside on the same file system.
  69 .Pp
  70 The
  71 .Fn rename
  72 system call guarantees that an instance of
  73 .Fa new
  74 will always exist,
  75 even if the system should crash in the middle of the operation.
  76 .Pp
  77 If the final component of
  78 .Fa old
  79 is a symbolic link,
  80 the symbolic link is renamed,
  81 not the file or directory to which it points.
  82 .Pp
  83 The
  84 .Fn renameat
  85 system call is equivalent to
  86 .Fn rename
  87 except in the case where either
  88 .Fa from
  89 or
  90 .Fa to
  91 specifies a relative path.
  92 If
  93 .Fa from
  94 is a relative path, the file to be renamed is located
  95 relative to the directory associated with the file descriptor
  96 .Fa fromfd
  97 instead of the current working directory.
  98 If the
  99 .Fa to
 100 is a relative path, the same happens only relative to the directory associated
 101 with
 102 .Fa tofd .
 103 If the
 104 .Fn renameat
 105 is passed the special value
 106 .Dv AT_FDCWD
 107 in the
 108 .Fa fromfd
 109 or
 110 .Fa tofd
 111 parameter, the current working directory is used in the determination
 112 of the file for the respective path parameter.
 113 .Sh CAVEATS
 114 The system can deadlock if a loop is present in the file system graph.
 115 This loop takes the form of an entry in directory
 116 .Ql Pa a ,
 117 say
 118 .Ql Pa a/foo ,
 119 being a hard link to directory
 120 .Ql Pa b ,
 121 and an entry in
 122 directory
 123 .Ql Pa b ,
 124 say
 125 .Ql Pa b/bar ,
 126 being a hard link
 127 to directory
 128 .Ql Pa a .
 129 When such a loop exists and two separate processes attempt to
 130 perform
 131 .Ql rename a/foo b/bar
 132 and
 133 .Ql rename b/bar a/foo ,
 134 respectively,
 135 the system may deadlock attempting to lock
 136 both directories for modification.
 137 .Pp
 138 Whether or not hard links to directories are supported is specific to
 139 the underlying filesystem implementation.
 140 .Pp
 141 It is recommended that any hard links to directories in an underlying
 142 filesystem should be replaced by symbolic links by the system administrator
 143 to avoid the possibility of deadlocks.
 144 .Pp
 145 Moving or renaming a file or directory into a directory with inheritable ACLs does not result in ACLs being set on the file or directory. Use
 146 .Xr acl 3
 147 in conjunction with
 148 .Fn rename
 149 to set ACLs on the file or directory.
 150 .Sh RETURN VALUES
 151 A 0 value is returned if the operation succeeds, otherwise
 152 .Fn rename
 153 returns -1 and the global variable
 154 .Va errno
 155 indicates the reason for the failure.
 156 .Sh ERRORS
 157 The
 158 .Fn rename
 159 system call will fail and neither of the argument files will be
 160 affected if:
 161 .Bl -tag -width Er
 162 .\" ===========
 163 .It Bq Er EACCES
 164 A component of either path prefix denies search permission.
 165 .\" ===========
 166 .It Bq Er EACCES
 167 The requested operation requires writing in a directory
 168 (e.g.,
 169 .Fa new ,
 170 new/.., or old/..) whose modes disallow this.
 171 .\" ===========
 172 .It Bq Er EDQUOT
 173 The directory in which the entry for the new name
 174 is being placed cannot be extended because the
 175 user's quota of disk blocks on the file system
 176 containing the directory has been exhausted.
 177 .\" ===========
 178 .It Bq Er EFAULT
 179 .Em Path
 180 points outside the process's allocated address space.
 181 .\" ===========
 182 .It Bq Er EINVAL
 183 .Fa Old
 184 is a parent directory of
 185 .Fa new ,
 186 or an attempt is made to rename
 187 .Ql \&.
 188 or
 189 .Ql \&.. .
 190 .\" ===========
 191 .It Bq Er EIO
 192 An I/O error occurs while making or updating a directory entry.
 193 .\" ===========
 194 .It Bq Er EISDIR
 195 .Fa new
 196 is a directory, but
 197 .Fa old
 198 is not a directory.
 199 .\" ===========
 200 .It Bq Er ELOOP
 201 Too many symbolic links are encountered in translating either pathname.
 202 This is taken to be indicative of a looping symbolic link.
 203 .\" ===========
 204 .It Bq Er ENAMETOOLONG
 205 A component of a pathname exceeds
 206 .Dv {NAME_MAX}
 207 characters, or an entire path name exceeds
 208 .Dv {PATH_MAX}
 209 characters.
 210 .\" ===========
 211 .It Bq Er ENOENT
 212 A component of the
 213 .Fa old
 214 path does not exist,
 215 or a path prefix of
 216 .Fa new
 217 does not exist.
 218 .\" ===========
 219 .It Bq Er ENOSPC
 220 The directory in which the entry for the new name is being placed
 221 cannot be extended because there is no space left on the file
 222 system containing the directory.
 223 .\" ===========
 224 .It Bq Er ENOTDIR
 225 A component of either path prefix is not a directory.
 226 .\" ===========
 227 .It Bq Er ENOTDIR
 228 .Fa old
 229 is a directory, but
 230 .Fa new
 231 is not a directory.
 232 .\" ===========
 233 .It Bq Er ENOTEMPTY
 234 .Fa New
 235 is a directory and is not empty.
 236 .\" ===========
 237 .It Bq Er EPERM
 238 The directory containing
 239 .Fa old
 240 is marked sticky,
 241 and neither the containing directory nor
 242 .Fa old
 243 are owned by the effective user ID.
 244 .\" ===========
 245 .It Bq Er EPERM
 246 The
 247 .Fa new
 248 file exists,
 249 the directory containing
 250 .Fa new
 251 is marked sticky,
 252 and neither the containing directory nor
 253 .Fa new
 254 are owned by the effective user ID.
 255 .\" ===========
 256 .It Bq Er EROFS
 257 The requested link requires writing in a directory on a read-only file
 258 system.
 259 .\" ===========
 260 .It Bq Er EXDEV
 261 The link named by
 262 .Fa new
 263 and the file named by
 264 .Fa old
 265 are on different logical devices (file systems).
 266 Note that this error code will not be returned
 267 if the implementation permits cross-device links.
 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 .Sh CONFORMANCE
 305 The restriction on renaming a directory whose permissions disallow writing
 306 is based on the fact that UFS directories contain a ".." entry.
 307 If renaming a directory would move it to another parent directory,
 308 this entry needs to be changed.
 309 .Pp
 310 This restriction has been generalized to disallow renaming
 311 of any write-disabled directory,
 312 even when this would not require a change to the ".." entry.
 313 For consistency, HFS+ directories emulate this behavior.
 314 .Sh SEE ALSO
 315 .Xr open 2 ,
 316 .Xr symlink 7
 317 .Sh STANDARDS
 318 The
 319 .Fn rename
 320 function conforms to
 321 .St -p1003.1-88 .
 322 The
 323 .Fn renameat
 324 system call is expected to conform to POSIX.1-2008 .