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 June 4, 1993
  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 CAVEAT
  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 .Sh RETURN VALUES
 111 A 0 value is returned if the operation succeeds, otherwise
 112 .Fn rename
 113 returns -1 and the global variable
 114 .Va errno
 115 indicates the reason for the failure.
 116 .Sh ERRORS
 117 The
 118 .Fn rename
 119 system call will fail and neither of the argument files will be
 120 affected if:
 121 .Bl -tag -width Er
 122 .\" ===========
 123 .It Bq Er EACCES
 124 A component of either path prefix denies search permission.
 125 .\" ===========
 126 .It Bq Er EACCES
 127 The requested operation requires writing in a directory
 128 (e.g.,
 129 .Fa new ,
 130 new/.., or old/..) whose modes disallow this.
 131 .\" ===========
 132 .It Bq Er EDQUOT
 133 The directory in which the entry for the new name
 134 is being placed cannot be extended because the
 135 user's quota of disk blocks on the file system
 136 containing the directory has been exhausted.
 137 .\" ===========
 138 .It Bq Er EFAULT
 139 .Em Path
 140 points outside the process's allocated address space.
 141 .\" ===========
 142 .It Bq Er EINVAL
 143 .Fa Old
 144 is a parent directory of
 145 .Fa new ,
 146 or an attempt is made to rename
 147 .Ql \&.
 148 or
 149 .Ql \&.. .
 150 .\" ===========
 151 .It Bq Er EIO
 152 An I/O error occurs while making or updating a directory entry.
 153 .\" ===========
 154 .It Bq Er EISDIR
 155 .Fa new
 156 is a directory, but
 157 .Fa old
 158 is not a directory.
 159 .\" ===========
 160 .It Bq Er ELOOP
 161 Too many symbolic links are encountered in translating either pathname.
 162 This is taken to be indicative of a looping symbolic link.
 163 .\" ===========
 164 .It Bq Er ENAMETOOLONG
 165 A component of a pathname exceeds
 166 .Dv {NAME_MAX}
 167 characters, or an entire path name exceeds
 168 .Dv {PATH_MAX}
 169 characters.
 170 .\" ===========
 171 .It Bq Er ENOENT
 172 A component of the
 173 .Fa old
 174 path does not exist,
 175 or a path prefix of
 176 .Fa new
 177 does not exist.
 178 .\" ===========
 179 .It Bq Er ENOSPC
 180 The directory in which the entry for the new name is being placed
 181 cannot be extended because there is no space left on the file
 182 system containing the directory.
 183 .\" ===========
 184 .It Bq Er ENOTDIR
 185 A component of either path prefix is not a directory.
 186 .\" ===========
 187 .It Bq Er ENOTDIR
 188 .Fa old
 189 is a directory, but
 190 .Fa new
 191 is not a directory.
 192 .\" ===========
 193 .It Bq Er ENOTEMPTY
 194 .Fa New
 195 is a directory and is not empty.
 196 .\" ===========
 197 .It Bq Er EPERM
 198 The directory containing
 199 .Fa old
 200 is marked sticky,
 201 and neither the containing directory nor
 202 .Fa old
 203 are owned by the effective user ID.
 204 .\" ===========
 205 .It Bq Er EPERM
 206 The
 207 .Fa new
 208 file exists,
 209 the directory containing
 210 .Fa new
 211 is marked sticky,
 212 and neither the containing directory nor
 213 .Fa new
 214 are owned by the effective user ID.
 215 .\" ===========
 216 .It Bq Er EROFS
 217 The requested link requires writing in a directory on a read-only file
 218 system.
 219 .\" ===========
 220 .It Bq Er EXDEV
 221 The link named by
 222 .Fa new
 223 and the file named by
 224 .Fa old
 225 are on different logical devices (file systems).
 226 Note that this error code will not be returned
 227 if the implementation permits cross-device links.
 228 .El
 229 .Sh CONFORMANCE
 230 The restriction on renaming a directory whose permissions disallow writing
 231 is based on the fact that UFS directories contain a ".." entry.
 232 If renaming a directory would move it to another parent directory,
 233 this entry needs to be changed.
 234 .Pp
 235 This restriction has been generalized to disallow renaming
 236 of any write-disabled directory,
 237 even when this would not require a change to the ".." entry.
 238 For consistency, HFS+ directories emulate this behavior.
 239 .Sh SEE ALSO
 240 .Xr open 2 ,
 241 .Xr symlink 7
 242 .Sh STANDARDS
 243 The
 244 .Fn rename
 245 function conforms to
 246 .St -p1003.1-88 .