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 .\"
  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 .Fn Rename
  49 causes the link named
  50 .Fa from
  51 to be renamed as
  52 .Fa to .
  53 If
  54 .Fa to
  55 exists, it is first removed.
  56 Both
  57 .Fa from
  58 and
  59 .Fa to
  60 must be of the same type (that is, both directories or both
  61 non-directories), and must reside on the same file system.
  62 .Pp
  63 .Fn Rename
  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 .\".Ql Pa a ,
  80 .\"say
  81 .\".Ql Pa a/foo ,
  82 .\"being a hard link to directory
  83 .\".Ql Pa b ,
  84 .\"and an entry in
  85 .\"directory
  86 .\".Ql Pa b ,
  87 .\"say
  88 .\".Ql Pa b/bar ,
  89 .\"being a hard link
  90 .\"to directory
  91 .\".Ql 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 .Fn Rename
 106 will fail and neither of the argument files will be
 107 affected if:
 108 .Bl -tag -width Er
 109 .It Bq Er ENAMETOOLONG
 110 A component of either pathname exceeded 255 characters,
 111 or the entire length of either path name exceeded 1023 characters.
 112 .It Bq Er ENOENT
 113 A component of the
 114 .Fa from
 115 path does not exist,
 116 or a path prefix of
 117 .Fa to
 118 does not exist.
 119 .It Bq Er EACCES
 120 A component of either path prefix denies search permission.
 121 .It Bq Er EACCES
 122 The requested link requires writing in a directory with a mode
 123 that denies write permission.
 124 .It Bq Er EPERM
 125 The directory containing
 126 .Fa from
 127 is marked sticky,
 128 and neither the containing directory nor
 129 .Fa from
 130 are owned by the effective user ID.
 131 .It Bq Er EPERM
 132 The
 133 .Fa to
 134 file exists,
 135 the directory containing
 136 .Fa to
 137 is marked sticky,
 138 and neither the containing directory nor
 139 .Fa to
 140 are owned by the effective user ID.
 141 .It Bq Er ELOOP
 142 Too many symbolic links were encountered in translating either pathname.
 143 .It Bq Er ENOTDIR
 144 A component of either path prefix is not a directory.
 145 .It Bq Er ENOTDIR
 146 .Fa from
 147 is a directory, but
 148 .Fa to
 149 is not a directory.
 150 .It Bq Er EISDIR
 151 .Fa to
 152 is a directory, but
 153 .Fa from
 154 is not a directory.
 155 .It Bq Er EXDEV
 156 The link named by
 157 .Fa to
 158 and the file named by
 159 .Fa from
 160 are on different logical devices (file systems).  Note that this error
 161 code will not be returned if the implementation permits cross-device
 162 links.
 163 .It Bq Er ENOSPC
 164 The directory in which the entry for the new name is being placed
 165 cannot be extended because there is no space left on the file
 166 system containing the directory.
 167 .It Bq Er EDQUOT
 168 The directory in which the entry for the new name
 169 is being placed cannot be extended because the
 170 user's quota of disk blocks on the file system
 171 containing the directory has been exhausted.
 172 .It Bq Er EIO
 173 An I/O error occurred while making or updating a directory entry.
 174 .It Bq Er EROFS
 175 The requested link requires writing in a directory on a read-only file
 176 system.
 177 .It Bq Er EFAULT
 178 .Em Path
 179 points outside the process's allocated address space.
 180 .It Bq Er EINVAL
 181 .Fa From
 182 is a parent directory of
 183 .Fa to ,
 184 or an attempt is made to rename
 185 .Ql .\&
 186 or
 187 .Ql \&.. .
 188 .It Bq Er ENOTEMPTY
 189 .Fa To
 190 is a directory and is not empty.
 191 .El
 192 .Sh SEE ALSO
 193 .Xr open 2 ,
 194 .Xr symlink 7
 195 .Sh STANDARDS
 196 The
 197 .Fn rename
 198 function call is expected to conform to
 199 .St -p1003.1-96 .