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