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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)rename.2    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/sys/rename.2,v 1.8.2.7 2001/12/14 18:34:01 ru Exp $
  34 .\"
  35 .Dd July 31, 2010
  36 .Dt RENAME 2
  37 .Os
  38 .Sh NAME
  39 .Nm rename ,
  40 .Nm renameat
  41 .Nd change the name of a file
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In stdio.h
  46 .Ft int
  47 .Fn rename "const char *from" "const char *to"
  48 .Ft int
  49 .Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to"
  50 .Sh DESCRIPTION
  51 .Fn Rename
  52 causes the link named
  53 .Fa from
  54 to be renamed as
  55 .Fa to .
  56 If
  57 .Fa to
  58 exists, it is first removed.
  59 Both
  60 .Fa from
  61 and
  62 .Fa to
  63 must be of the same type (that is, both directories or both
  64 non-directories), and must reside on the same file system.
  65 .Pp
  66 .Fn Rename
  67 guarantees that if
  68 .Fa to
  69 already exists, an instance of
  70 .Fa to
  71 will always exist, even if the system should crash in
  72 the middle of the operation.
  73 .Pp
  74 If the final component of
  75 .Fa from
  76 is a symbolic link,
  77 the symbolic link is renamed,
  78 not the file or directory to which it points.
  79 .Pp
  80 The
  81 .Fn renameat
  82 system call is equivalent to
  83 .Fn rename
  84 except in the case where either
  85 .Fa from
  86 or
  87 .Fa to
  88 specifies a relative path.
  89 If
  90 .Fa from
  91 is a relative path, the file to be renamed is located
  92 relative to the directory associated with the file descriptor
  93 .Fa fromfd
  94 instead of the current working directory.
  95 If the
  96 .Fa to
  97 is a relative path, the same happens only relative to the directory associated
  98 with
  99 .Fa tofd .
 100 If the
 101 .Fn renameat
 102 is passed the special value
 103 .Dv AT_FDCWD
 104 in the
 105 .Fa fromfd
 106 or
 107 .Fa tofd
 108 parameter, the current working directory is used in the determination
 109 of the file for the respective path parameter.
 110 .\".Sh CAVEAT
 111 .\"The system can deadlock if a loop in the file system graph is present.
 112 .\"This loop takes the form of an entry in directory
 113 .\".Ql Pa a ,
 114 .\"say
 115 .\".Ql Pa a/foo ,
 116 .\"being a hard link to directory
 117 .\".Ql Pa b ,
 118 .\"and an entry in
 119 .\"directory
 120 .\".Ql Pa b ,
 121 .\"say
 122 .\".Ql Pa b/bar ,
 123 .\"being a hard link
 124 .\"to directory
 125 .\".Ql Pa a .
 126 .\"When such a loop exists and two separate processes attempt to
 127 .\"perform
 128 .\".Ql rename a/foo b/bar
 129 .\"and
 130 .\".Ql rename b/bar a/foo ,
 131 .\"respectively,
 132 .\"the system may deadlock attempting to lock
 133 .\"both directories for modification.
 134 .\"Hard links to directories should be
 135 .\"replaced by symbolic links by the system administrator.
 136 .Sh RETURN VALUES
 137 .Rv -std rename renameat
 138 .Sh ERRORS
 139 .Fn Rename
 140 will fail and neither of the argument files will be
 141 affected if:
 142 .Bl -tag -width Er
 143 .It Bq Er ENAMETOOLONG
 144 A component of either pathname exceeded 255 characters,
 145 or the entire length of either path name exceeded 1023 characters.
 146 .It Bq Er ENOENT
 147 A component of the
 148 .Fa from
 149 path does not exist,
 150 or a path prefix of
 151 .Fa to
 152 does not exist.
 153 .It Bq Er EACCES
 154 A component of either path prefix denies search permission.
 155 .It Bq Er EACCES
 156 The requested link requires writing in a directory with a mode
 157 that denies write permission.
 158 .It Bq Er EPERM
 159 The directory containing
 160 .Fa from
 161 is marked sticky,
 162 and neither the containing directory nor
 163 .Fa from
 164 are owned by the effective user ID.
 165 .It Bq Er EPERM
 166 The
 167 .Fa to
 168 file exists,
 169 the directory containing
 170 .Fa to
 171 is marked sticky,
 172 and neither the containing directory nor
 173 .Fa to
 174 are owned by the effective user ID.
 175 .It Bq Er ELOOP
 176 Too many symbolic links were encountered in translating either pathname.
 177 .It Bq Er ENOTDIR
 178 A component of either path prefix is not a directory.
 179 .It Bq Er ENOTDIR
 180 .Fa from
 181 is a directory, but
 182 .Fa to
 183 is not a directory.
 184 .It Bq Er EISDIR
 185 .Fa to
 186 is a directory, but
 187 .Fa from
 188 is not a directory.
 189 .It Bq Er EXDEV
 190 The link named by
 191 .Fa to
 192 and the file named by
 193 .Fa from
 194 are on different logical devices (file systems).  Note that this error
 195 code will not be returned if the implementation permits cross-device
 196 links.
 197 .It Bq Er ENOSPC
 198 The directory in which the entry for the new name is being placed
 199 cannot be extended because there is no space left on the file
 200 system containing the directory.
 201 .It Bq Er EDQUOT
 202 The directory in which the entry for the new name
 203 is being placed cannot be extended because the
 204 user's quota of disk blocks on the file system
 205 containing the directory has been exhausted.
 206 .It Bq Er EIO
 207 An I/O error occurred while making or updating a directory entry.
 208 .It Bq Er EROFS
 209 The requested link requires writing in a directory on a read-only file
 210 system.
 211 .It Bq Er EFAULT
 212 .Em Path
 213 points outside the process's allocated address space.
 214 .It Bq Er EINVAL
 215 .Fa From
 216 is a parent directory of
 217 .Fa to ,
 218 or an attempt is made to rename
 219 .Ql .\&
 220 or
 221 .Ql \&.. .
 222 .It Bq Er ENOTEMPTY
 223 .Fa To
 224 is a directory and is not empty.
 225 .El
 226 .Pp
 227 In addition to the errors returned by the
 228 .Fn rename ,
 229 the
 230 .Fn renameat
 231 may fail if:
 232 .Bl -tag -width Er
 233 .It Bq Er EBADF
 234 The
 235 .Fa from
 236 argument does not specify an absolute path and the
 237 .Fa fromfd
 238 argument is neither
 239 .Dv AT_FDCWD
 240 nor a valid file descriptor open for searching, or the
 241 .Fa to
 242 argument does not specify an absolute path and the
 243 .Fa tofd
 244 argument is neither
 245 .Dv AT_FDCWD
 246 nor a valid file descriptor open for searching.
 247 .It Bq Er ENOTDIR
 248 The
 249 .Fa from
 250 argument is not an absolute path and
 251 .Fa fromfd
 252 is neither
 253 .Dv AT_FDCWD
 254 nor a file descriptor associated with a directory, or the
 255 .Fa to
 256 argument is not an absolute path and
 257 .Fa tofd
 258 is neither
 259 .Dv AT_FDCWD
 260 nor a file descriptor associated with a directory.
 261 .El
 262 .Sh SEE ALSO
 263 .Xr open 2 ,
 264 .Xr symlink 7
 265 .Sh STANDARDS
 266 The
 267 .Fn rename
 268 system call is expected to conform to
 269 .St -p1003.1-96 .
 270 The
 271 .Fn renameat
 272 system call follows The Open Group Extended API Set 2 specification.
 273 .Sh HISTORY
 274 The
 275 .Fn renameat
 276 system call appeared in
 277 .Dx 2.7 .