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 .\" 4. 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$
  30 .\"
  31 .Dd December 9, 2006
  32 .Dt RENAME 2
  33 .Os
  34 .Sh NAME
  35 .Nm rename
  36 .Nd change the name of a file
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In stdio.h
  41 .Ft int
  42 .Fn rename "const char *from" "const char *to"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn rename
  46 system call
  47 causes the link named
  48 .Fa from
  49 to be renamed as
  50 .Fa to .
  51 If
  52 .Fa to
  53 exists, it is first removed.
  54 Both
  55 .Fa from
  56 and
  57 .Fa to
  58 must be of the same type (that is, both directories or both
  59 non-directories), and must reside on the same file system.
  60 .Pp
  61 The
  62 .Fn rename
  63 system call
  64 guarantees that if
  65 .Fa to
  66 already exists, an instance of
  67 .Fa to
  68 will always exist, even if the system should crash in
  69 the middle of the operation.
  70 .Pp
  71 If the final component of
  72 .Fa from
  73 is a symbolic link,
  74 the symbolic link is renamed,
  75 not the file or directory to which it points.
  76 .\".Sh CAVEAT
  77 .\"The system can deadlock if a loop in the file system graph is present.
  78 .\"This loop takes the form of an entry in directory
  79 .\".Pa a ,
  80 .\"say
  81 .\".Pa a/foo ,
  82 .\"being a hard link to directory
  83 .\".Pa b ,
  84 .\"and an entry in
  85 .\"directory
  86 .\".Pa b ,
  87 .\"say
  88 .\".Pa b/bar ,
  89 .\"being a hard link
  90 .\"to directory
  91 .\".Pa a .
  92 .\"When such a loop exists and two separate processes attempt to
  93 .\"perform
  94 .\".Ql rename a/foo b/bar
  95 .\"and
  96 .\".Ql rename b/bar a/foo ,
  97 .\"respectively,
  98 .\"the system may deadlock attempting to lock
  99 .\"both directories for modification.
 100 .\"Hard links to directories should be
 101 .\"replaced by symbolic links by the system administrator.
 102 .Sh RETURN VALUES
 103 .Rv -std rename
 104 .Sh ERRORS
 105 The
 106 .Fn rename
 107 system call
 108 will fail and neither of the argument files will be
 109 affected if:
 110 .Bl -tag -width Er
 111 .It Bq Er ENAMETOOLONG
 112 A component of either pathname exceeded 255 characters,
 113 or the entire length of either path name exceeded 1023 characters.
 114 .It Bq Er ENOENT
 115 A component of the
 116 .Fa from
 117 path does not exist,
 118 or a path prefix of
 119 .Fa to
 120 does not exist.
 121 .It Bq Er EACCES
 122 A component of either path prefix denies search permission.
 123 .It Bq Er EACCES
 124 The requested link requires writing in a directory with a mode
 125 that denies write permission.
 126 .It Bq Er EPERM
 127 The file pointed at by the
 128 .Fa from
 129 argument has its immutable, undeletable or append-only flag set, see the
 130 .Xr chflags 2
 131 manual page for more information.
 132 .It Bq Er EPERM
 133 The parent directory of the file pointed at by the
 134 .Fa from
 135 argument has its immutable or append-only flag set.
 136 .It Bq Er EPERM
 137 The parent directory of the file pointed at by the
 138 .Fa to
 139 argument has its immutable flag set.
 140 .It Bq Er EPERM
 141 The directory containing
 142 .Fa from
 143 is marked sticky,
 144 and neither the containing directory nor
 145 .Fa from
 146 are owned by the effective user ID.
 147 .It Bq Er EPERM
 148 The file pointed at by the
 149 .Fa to
 150 argument
 151 exists,
 152 the directory containing
 153 .Fa to
 154 is marked sticky,
 155 and neither the containing directory nor
 156 .Fa to
 157 are owned by the effective user ID.
 158 .It Bq Er ELOOP
 159 Too many symbolic links were encountered in translating either pathname.
 160 .It Bq Er ENOTDIR
 161 A component of either path prefix is not a directory.
 162 .It Bq Er ENOTDIR
 163 The
 164 .Fa from
 165 argument
 166 is a directory, but
 167 .Fa to
 168 is not a directory.
 169 .It Bq Er EISDIR
 170 The
 171 .Fa to
 172 argument
 173 is a directory, but
 174 .Fa from
 175 is not a directory.
 176 .It Bq Er EXDEV
 177 The link named by
 178 .Fa to
 179 and the file named by
 180 .Fa from
 181 are on different logical devices (file systems).
 182 Note that this error
 183 code will not be returned if the implementation permits cross-device
 184 links.
 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 .It Bq Er EDQUOT
 190 The directory in which the entry for the new name
 191 is being placed cannot be extended because the
 192 user's quota of disk blocks on the file system
 193 containing the directory has been exhausted.
 194 .It Bq Er EIO
 195 An I/O error occurred while making or updating a directory entry.
 196 .It Bq Er EROFS
 197 The requested link requires writing in a directory on a read-only file
 198 system.
 199 .It Bq Er EFAULT
 200 Path
 201 points outside the process's allocated address space.
 202 .It Bq Er EINVAL
 203 The
 204 .Fa from
 205 argument
 206 is a parent directory of
 207 .Fa to ,
 208 or an attempt is made to rename
 209 .Ql .\&
 210 or
 211 .Ql \&.. .
 212 .It Bq Er ENOTEMPTY
 213 The
 214 .Fa to
 215 argument
 216 is a directory and is not empty.
 217 .El
 218 .Sh SEE ALSO
 219 .Xr chflags 2 ,
 220 .Xr open 2 ,
 221 .Xr symlink 7
 222 .Sh STANDARDS
 223 The
 224 .Fn rename
 225 system call is expected to conform to
 226 .St -p1003.1-96 .