lib/libc/sys/rename.2

   1 .\"     $NetBSD: rename.2,v 1.23 2010/05/31 12:16:20 njoly 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. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)rename.2    8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd December 27, 2005
  33 .Dt RENAME 2
  34 .Os
  35 .Sh NAME
  36 .Nm rename
  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 .Sh DESCRIPTION
  45 .Fn rename
  46 causes the link named
  47 .Fa from
  48 to be renamed as
  49 .Fa to .
  50 If
  51 .Fa to
  52 exists, it is first removed.
  53 Both
  54 .Fa from
  55 and
  56 .Fa to
  57 must be of the same type (that is, both directories or both
  58 non-directories), and must reside on the same file system.
  59 .Pp
  60 .Fn rename
  61 guarantees that an instance of
  62 .Fa to
  63 will always exist, even if the system should crash in
  64 the middle of the operation.
  65 .Pp
  66 If the final component of
  67 .Fa from
  68 is a symbolic link,
  69 the symbolic link is renamed,
  70 not the file or directory to which it points.
  71 .Pp
  72 If both
  73 .Fa from
  74 and
  75 .Fa to
  76 are pathnames of the same existing file in the file system's name space,
  77 .Fn rename
  78 returns successfully and performs no other action.
  79 .Sh RETURN VALUES
  80 A 0 value is returned if the operation succeeds, otherwise
  81 .Fn rename
  82 returns \-1 and the global variable
  83 .Va errno
  84 indicates the reason for the failure.
  85 .Sh ERRORS
  86 .Fn rename
  87 will fail and neither of the argument files will be
  88 affected if:
  89 .Bl -tag -width Er
  90 .It Bq Er ENAMETOOLONG
  91 A component of a pathname exceeded
  92 .Brq Dv NAME_MAX
  93 characters, or an entire path name exceeded
  94 .Brq Dv PATH_MAX
  95 characters.
  96 .It Bq Er ENOENT
  97 A component of the
  98 .Fa from
  99 path does not exist,
 100 or a path prefix of
 101 .Fa to
 102 does not exist.
 103 .It Bq Er EACCES
 104 A component of either path prefix denies search permission, or
 105 the requested link requires writing in a directory with a mode
 106 that denies write permission.
 107 .It Bq Er EPERM
 108 The directory containing
 109 .Fa from
 110 is marked sticky,
 111 and neither the containing directory nor
 112 .Fa from
 113 are owned by the effective user ID.
 114 Or the
 115 .Fa to
 116 file exists,
 117 the directory containing
 118 .Fa to
 119 is marked sticky,
 120 and neither the containing directory nor
 121 .Fa to
 122 are owned by the effective user ID.
 123 .It Bq Er ELOOP
 124 Too many symbolic links were encountered in translating either pathname.
 125 .It Bq Er ENOTDIR
 126 A component of either path prefix is not a directory, or
 127 .Fa from
 128 is a directory, but
 129 .Fa to
 130 is not a directory.
 131 .It Bq Er EISDIR
 132 .Fa to
 133 is a directory, but
 134 .Fa from
 135 is not a directory.
 136 .It Bq Er EXDEV
 137 The link named by
 138 .Fa to
 139 and the file named by
 140 .Fa from
 141 are on different logical devices (file systems).
 142 Note that this error code will not be returned if the implementation
 143 permits cross-device links.
 144 .It Bq Er ENOSPC
 145 The directory in which the entry for the new name is being placed
 146 cannot be extended because there is no space left on the file
 147 system containing the directory.
 148 .It Bq Er EDQUOT
 149 The directory in which the entry for the new name
 150 is being placed cannot be extended because the
 151 user's quota of disk blocks on the file system
 152 containing the directory has been exhausted.
 153 .It Bq Er EIO
 154 An I/O error occurred while making or updating a directory entry.
 155 .It Bq Er EROFS
 156 The requested link requires writing in a directory on a read-only file
 157 system.
 158 .It Bq Er EFAULT
 159 .Em Path
 160 points outside the process's allocated address space.
 161 .It Bq Er EINVAL
 162 .Fa from
 163 is a parent directory of
 164 .Fa to ,
 165 or an attempt is made to rename
 166 .Ql \&.
 167 or
 168 .Ql \&.. .
 169 .It Bq Er ENOTEMPTY
 170 .Fa to
 171 is a directory and is not empty.
 172 .It Bq Er EBUSY
 173 .Fa from
 174 or
 175 .Fa to
 176 is the mount point for a mounted file system.
 177 .El
 178 .Sh SEE ALSO
 179 .Xr open 2 ,
 180 .Xr symlink 7
 181 .Sh STANDARDS
 182 The
 183 .Fn rename
 184 function deviates from the semantics defined in
 185 .St -p1003.1-90 ,
 186 which specifies that if both
 187 .Fa from
 188 and
 189 .Fa to
 190 .Em link
 191 to the same existing file,
 192 .Fn rename
 193 shall return successfully and performs no further action, whereas this
 194 implementation will remove the file specified by
 195 .Fa from
 196 unless both
 197 .Fa from
 198 and
 199 .Fa to
 200 are pathnames of the same file in the file system's name space.
 201 .Pp
 202 To retain conformance, a compatibility interface is provided by the
 203 .Lb libposix
 204 which is also be brought into scope if any of the
 205 .Dv _POSIX_SOURCE ,
 206 .Dv _POSIX_C_SOURCE
 207 or
 208 .Dv _XOPEN_SOURCE
 209 preprocessor symbols are defined at compile-time:
 210 the
 211 .Fn rename
 212 function conforms to
 213 .St -p1003.1-90
 214 and
 215 .St -xpg4.2 .
 216 .Sh BUGS
 217 The system can deadlock if a loop in the file system graph is present.
 218 This loop takes the form of an entry in directory
 219 .Ql Pa a ,
 220 say
 221 .Ql Pa a/foo ,
 222 being a hard link to directory
 223 .Ql Pa b ,
 224 and an entry in
 225 directory
 226 .Ql Pa b ,
 227 say
 228 .Ql Pa b/bar ,
 229 being a hard link
 230 to directory
 231 .Ql Pa a .
 232 When such a loop exists and two separate processes attempt to
 233 perform
 234 .Ql rename a/foo b/bar
 235 and
 236 .Ql rename b/bar a/foo ,
 237 respectively,
 238 the system may deadlock attempting to lock
 239 both directories for modification.
 240 Hard links to directories should be
 241 replaced by symbolic links by the system administrator.