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 .Nd change the name of a file
  42 .Sh SYNOPSIS
  43 .Fd #include <stdio.h>
  44 .Ft int
  45 .Fo rename
  46 .Fa "const char *old"
  47 .Fa "const char *new"
  48 .Fc
  49 .Sh DESCRIPTION
  50 The
  51 .Fn rename
  52 system call causes the link named
  53 .Fa old
  54 to be renamed as
  55 .Fa new .
  56 If
  57 .Fa new
  58 exists, it is first removed.
  59 Both
  60 .Fa old
  61 and
  62 .Fa new
  63 must be of the same type
  64 (that is, both must be either directories or non-directories)
  65 and must reside on the same file system.
  66 .Pp
  67 The
  68 .Fn rename
  69 system call guarantees that an instance of
  70 .Fa new
  71 will always exist,
  72 even if the system should crash in the middle of the operation.
  73 .Pp
  74 If the final component of
  75 .Fa old
  76 is a symbolic link,
  77 the symbolic link is renamed,
  78 not the file or directory to which it points.
  79 .Sh CAVEATS
  80 The system can deadlock if a loop is present in the file system graph.
  81 This loop takes the form of an entry in directory
  82 .Ql Pa a ,
  83 say
  84 .Ql Pa a/foo ,
  85 being a hard link to directory
  86 .Ql Pa b ,
  87 and an entry in
  88 directory
  89 .Ql Pa b ,
  90 say
  91 .Ql Pa b/bar ,
  92 being a hard link
  93 to directory
  94 .Ql Pa a .
  95 When such a loop exists and two separate processes attempt to
  96 perform
  97 .Ql rename a/foo b/bar
  98 and
  99 .Ql rename b/bar a/foo ,
 100 respectively,
 101 the system may deadlock attempting to lock
 102 both directories for modification.
 103 .Pp
 104 Whether or not hard links to directories are supported is specific to
 105 the underlying filesystem implementation.
 106 .Pp
 107 It is recommended that any hard links to directories in an underlying
 108 filesystem should be replaced by symbolic links by the system administrator
 109 to avoid the possibility of deadlocks.
 110 .Pp
 111 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
 112 .Xr acl 3
 113 in conjunction with
 114 .Fn rename
 115 to set ACLs on the file or directory.
 116 .Sh RETURN VALUES
 117 A 0 value is returned if the operation succeeds, otherwise
 118 .Fn rename
 119 returns -1 and the global variable
 120 .Va errno
 121 indicates the reason for the failure.
 122 .Sh ERRORS
 123 The
 124 .Fn rename
 125 system call will fail and neither of the argument files will be
 126 affected if:
 127 .Bl -tag -width Er
 128 .\" ===========
 129 .It Bq Er EACCES
 130 A component of either path prefix denies search permission.
 131 .\" ===========
 132 .It Bq Er EACCES
 133 The requested operation requires writing in a directory
 134 (e.g.,
 135 .Fa new ,
 136 new/.., or old/..) whose modes disallow this.
 137 .\" ===========
 138 .It Bq Er EDQUOT
 139 The directory in which the entry for the new name
 140 is being placed cannot be extended because the
 141 user's quota of disk blocks on the file system
 142 containing the directory has been exhausted.
 143 .\" ===========
 144 .It Bq Er EFAULT
 145 .Em Path
 146 points outside the process's allocated address space.
 147 .\" ===========
 148 .It Bq Er EINVAL
 149 .Fa Old
 150 is a parent directory of
 151 .Fa new ,
 152 or an attempt is made to rename
 153 .Ql \&.
 154 or
 155 .Ql \&.. .
 156 .\" ===========
 157 .It Bq Er EIO
 158 An I/O error occurs while making or updating a directory entry.
 159 .\" ===========
 160 .It Bq Er EISDIR
 161 .Fa new
 162 is a directory, but
 163 .Fa old
 164 is not a directory.
 165 .\" ===========
 166 .It Bq Er ELOOP
 167 Too many symbolic links are encountered in translating either pathname.
 168 This is taken to be indicative of a looping symbolic link.
 169 .\" ===========
 170 .It Bq Er ENAMETOOLONG
 171 A component of a pathname exceeds
 172 .Dv {NAME_MAX}
 173 characters, or an entire path name exceeds
 174 .Dv {PATH_MAX}
 175 characters.
 176 .\" ===========
 177 .It Bq Er ENOENT
 178 A component of the
 179 .Fa old
 180 path does not exist,
 181 or a path prefix of
 182 .Fa new
 183 does not exist.
 184 .\" ===========
 185 .It Bq Er ENOSPC
 186 The directory in which the entry for the new name is being placed
 187 cannot be extended because there is no space left on the file
 188 system containing the directory.
 189 .\" ===========
 190 .It Bq Er ENOTDIR
 191 A component of either path prefix is not a directory.
 192 .\" ===========
 193 .It Bq Er ENOTDIR
 194 .Fa old
 195 is a directory, but
 196 .Fa new
 197 is not a directory.
 198 .\" ===========
 199 .It Bq Er ENOTEMPTY
 200 .Fa New
 201 is a directory and is not empty.
 202 .\" ===========
 203 .It Bq Er EPERM
 204 The directory containing
 205 .Fa old
 206 is marked sticky,
 207 and neither the containing directory nor
 208 .Fa old
 209 are owned by the effective user ID.
 210 .\" ===========
 211 .It Bq Er EPERM
 212 The
 213 .Fa new
 214 file exists,
 215 the directory containing
 216 .Fa new
 217 is marked sticky,
 218 and neither the containing directory nor
 219 .Fa new
 220 are owned by the effective user ID.
 221 .\" ===========
 222 .It Bq Er EROFS
 223 The requested link requires writing in a directory on a read-only file
 224 system.
 225 .\" ===========
 226 .It Bq Er EXDEV
 227 The link named by
 228 .Fa new
 229 and the file named by
 230 .Fa old
 231 are on different logical devices (file systems).
 232 Note that this error code will not be returned
 233 if the implementation permits cross-device links.
 234 .El
 235 .Sh CONFORMANCE
 236 The restriction on renaming a directory whose permissions disallow writing
 237 is based on the fact that UFS directories contain a ".." entry.
 238 If renaming a directory would move it to another parent directory,
 239 this entry needs to be changed.
 240 .Pp
 241 This restriction has been generalized to disallow renaming
 242 of any write-disabled directory,
 243 even when this would not require a change to the ".." entry.
 244 For consistency, HFS+ directories emulate this behavior.
 245 .Sh SEE ALSO
 246 .Xr open 2 ,
 247 .Xr symlink 7
 248 .Sh STANDARDS
 249 The
 250 .Fn rename
 251 function conforms to
 252 .St -p1003.1-88 .