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