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