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