bsd/man/man2/rename.2

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