6/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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)rename.2    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd June 4, 1993
  36 .Dt RENAME 2
  37 .Os
  38 .Sh NAME
  39 .Nm rename
  40 .Nd change the name of a file
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In stdio.h
  45 .Ft int
  46 .Fn rename "const char *from" "const char *to"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn rename
  50 system call
  51 causes the link named
  52 .Fa from
  53 to be renamed as
  54 .Fa to .
  55 If
  56 .Fa to
  57 exists, it is first removed.
  58 Both
  59 .Fa from
  60 and
  61 .Fa to
  62 must be of the same type (that is, both directories or both
  63 non-directories), and must reside on the same file system.
  64 .Pp
  65 The
  66 .Fn rename
  67 system call
  68 guarantees that if
  69 .Fa to
  70 already exists, an instance of
  71 .Fa to
  72 will always exist, even if the system should crash in
  73 the middle of the operation.
  74 .Pp
  75 If the final component of
  76 .Fa from
  77 is a symbolic link,
  78 the symbolic link is renamed,
  79 not the file or directory to which it points.
  80 .\".Sh CAVEAT
  81 .\"The system can deadlock if a loop in the file system graph is present.
  82 .\"This loop takes the form of an entry in directory
  83 .\".Pa a ,
  84 .\"say
  85 .\".Pa a/foo ,
  86 .\"being a hard link to directory
  87 .\".Pa b ,
  88 .\"and an entry in
  89 .\"directory
  90 .\".Pa b ,
  91 .\"say
  92 .\".Pa b/bar ,
  93 .\"being a hard link
  94 .\"to directory
  95 .\".Pa a .
  96 .\"When such a loop exists and two separate processes attempt to
  97 .\"perform
  98 .\".Ql rename a/foo b/bar
  99 .\"and
 100 .\".Ql rename b/bar a/foo ,
 101 .\"respectively,
 102 .\"the system may deadlock attempting to lock
 103 .\"both directories for modification.
 104 .\"Hard links to directories should be
 105 .\"replaced by symbolic links by the system administrator.
 106 .Sh RETURN VALUES
 107 .Rv -std rename
 108 .Sh ERRORS
 109 The
 110 .Fn rename
 111 system call
 112 will fail and neither of the argument files will be
 113 affected if:
 114 .Bl -tag -width Er
 115 .It Bq Er ENAMETOOLONG
 116 A component of either pathname exceeded 255 characters,
 117 or the entire length of either path name exceeded 1023 characters.
 118 .It Bq Er ENOENT
 119 A component of the
 120 .Fa from
 121 path does not exist,
 122 or a path prefix of
 123 .Fa to
 124 does not exist.
 125 .It Bq Er EACCES
 126 A component of either path prefix denies search permission.
 127 .It Bq Er EACCES
 128 The requested link requires writing in a directory with a mode
 129 that denies write permission.
 130 .It Bq Er EPERM
 131 The directory containing
 132 .Fa from
 133 is marked sticky,
 134 and neither the containing directory nor
 135 .Fa from
 136 are owned by the effective user ID.
 137 .It Bq Er EPERM
 138 The file pointed at by the
 139 .Fa to
 140 argument
 141 exists,
 142 the directory containing
 143 .Fa to
 144 is marked sticky,
 145 and neither the containing directory nor
 146 .Fa to
 147 are owned by the effective user ID.
 148 .It Bq Er ELOOP
 149 Too many symbolic links were encountered in translating either pathname.
 150 .It Bq Er ENOTDIR
 151 A component of either path prefix is not a directory.
 152 .It Bq Er ENOTDIR
 153 The
 154 .Fa from
 155 argument
 156 is a directory, but
 157 .Fa to
 158 is not a directory.
 159 .It Bq Er EISDIR
 160 The
 161 .Fa to
 162 argument
 163 is a directory, but
 164 .Fa from
 165 is not a directory.
 166 .It Bq Er EXDEV
 167 The link named by
 168 .Fa to
 169 and the file named by
 170 .Fa from
 171 are on different logical devices (file systems).
 172 Note that this error
 173 code will not be returned if the implementation permits cross-device
 174 links.
 175 .It Bq Er ENOSPC
 176 The directory in which the entry for the new name is being placed
 177 cannot be extended because there is no space left on the file
 178 system containing the directory.
 179 .It Bq Er EDQUOT
 180 The directory in which the entry for the new name
 181 is being placed cannot be extended because the
 182 user's quota of disk blocks on the file system
 183 containing the directory has been exhausted.
 184 .It Bq Er EIO
 185 An I/O error occurred while making or updating a directory entry.
 186 .It Bq Er EROFS
 187 The requested link requires writing in a directory on a read-only file
 188 system.
 189 .It Bq Er EFAULT
 190 Path
 191 points outside the process's allocated address space.
 192 .It Bq Er EINVAL
 193 The
 194 .Fa from
 195 argument
 196 is a parent directory of
 197 .Fa to ,
 198 or an attempt is made to rename
 199 .Ql .\&
 200 or
 201 .Ql \&.. .
 202 .It Bq Er ENOTEMPTY
 203 The
 204 .Fa to
 205 argument
 206 is a directory and is not empty.
 207 .El
 208 .Sh SEE ALSO
 209 .Xr open 2 ,
 210 .Xr symlink 7
 211 .Sh STANDARDS
 212 The
 213 .Fn rename
 214 system call is expected to conform to
 215 .St -p1003.1-96 .