diff options
Diffstat (limited to 'lib/libc/sys/rename.2')
| -rw-r--r-- | lib/libc/sys/rename.2 | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/lib/libc/sys/rename.2 b/lib/libc/sys/rename.2 new file mode 100644 index 0000000..b98edd5 --- /dev/null +++ b/lib/libc/sys/rename.2 @@ -0,0 +1,308 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)rename.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd April 10, 2008 +.Dt RENAME 2 +.Os +.Sh NAME +.Nm rename +.Nd change the name of a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn rename "const char *from" "const char *to" +.Ft int +.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" +.Sh DESCRIPTION +The +.Fn rename +system call +causes the link named +.Fa from +to be renamed as +.Fa to . +If +.Fa to +exists, it is first removed. +Both +.Fa from +and +.Fa to +must be of the same type (that is, both directories or both +non-directories), and must reside on the same file system. +.Pp +The +.Fn rename +system call +guarantees that if +.Fa to +already exists, an instance of +.Fa to +will always exist, even if the system should crash in +the middle of the operation. +.Pp +If the final component of +.Fa from +is a symbolic link, +the symbolic link is renamed, +not the file or directory to which it points. +.Pp +The +.Fn renameat +system call is equivalent to +.Fn rename +except in the case where either +.Fa from +or +.Fa to +specifies a relative path. +If +.Fa from +is a relative path, the file to be renamed is located +relative to the directory associated with the file descriptor +.Fa fromfd +instead of the current working directory. +If the +.Fa to +is a relative path, the same happens only relative to the directory associated +with +.Fa tofd . +If the +.Fn renameat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fromfd +or +.Fa tofd +parameter, the current working directory is used in the determination +of the file for the respective path parameter. +.\".Sh CAVEAT +.\"The system can deadlock if a loop in the file system graph is present. +.\"This loop takes the form of an entry in directory +.\".Pa a , +.\"say +.\".Pa a/foo , +.\"being a hard link to directory +.\".Pa b , +.\"and an entry in +.\"directory +.\".Pa b , +.\"say +.\".Pa b/bar , +.\"being a hard link +.\"to directory +.\".Pa a . +.\"When such a loop exists and two separate processes attempt to +.\"perform +.\".Ql rename a/foo b/bar +.\"and +.\".Ql rename b/bar a/foo , +.\"respectively, +.\"the system may deadlock attempting to lock +.\"both directories for modification. +.\"Hard links to directories should be +.\"replaced by symbolic links by the system administrator. +.Sh RETURN VALUES +.Rv -std rename +.Sh ERRORS +The +.Fn rename +system call +will fail and neither of the argument files will be +affected if: +.Bl -tag -width Er +.It Bq Er ENAMETOOLONG +A component of either pathname exceeded 255 characters, +or the entire length of either path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the +.Fa from +path does not exist, +or a path prefix of +.Fa to +does not exist. +.It Bq Er EACCES +A component of either path prefix denies search permission. +.It Bq Er EACCES +The requested link requires writing in a directory with a mode +that denies write permission. +.It Bq Er EACCES +The directory pointed at by the +.Fa from +argument denies write permission, and the operation would move +it to another parent directory. +.It Bq Er EPERM +The file pointed at by the +.Fa from +argument has its immutable, undeletable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the file pointed at by the +.Fa from +argument has its immutable or append-only flag set. +.It Bq Er EPERM +The parent directory of the file pointed at by the +.Fa to +argument has its immutable flag set. +.It Bq Er EPERM +The directory containing +.Fa from +is marked sticky, +and neither the containing directory nor +.Fa from +are owned by the effective user ID. +.It Bq Er EPERM +The file pointed at by the +.Fa to +argument +exists, +the directory containing +.Fa to +is marked sticky, +and neither the containing directory nor +.Fa to +are owned by the effective user ID. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating either pathname. +.It Bq Er ENOTDIR +A component of either path prefix is not a directory. +.It Bq Er ENOTDIR +The +.Fa from +argument +is a directory, but +.Fa to +is not a directory. +.It Bq Er EISDIR +The +.Fa to +argument +is a directory, but +.Fa from +is not a directory. +.It Bq Er EXDEV +The link named by +.Fa to +and the file named by +.Fa from +are on different logical devices (file systems). +Note that this error +code will not be returned if the implementation permits cross-device +links. +.It Bq Er ENOSPC +The directory in which the entry for the new name is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er EDQUOT +The directory in which the entry for the new name +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EIO +An I/O error occurred while making or updating a directory entry. +.It Bq Er EROFS +The requested link requires writing in a directory on a read-only file +system. +.It Bq Er EFAULT +Path +points outside the process's allocated address space. +.It Bq Er EINVAL +The +.Fa from +argument +is a parent directory of +.Fa to , +or an attempt is made to rename +.Ql .\& +or +.Ql \&.. . +.It Bq Er ENOTEMPTY +The +.Fa to +argument +is a directory and is not empty. +.El +.Pp +In addition to the errors returned by the +.Fn rename , +the +.Fn renameat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa from +argument does not specify an absolute path and the +.Fa fromfd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching, or the +.Fa to +argument does not specify an absolute path and the +.Fa tofd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa from +argument is not an absolute path and +.Fa fromfd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory, or the +.Fa to +argument is not an absolute path and +.Fa tofd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr open 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn rename +system call is expected to conform to +.St -p1003.1-96 . +The +.Fn renameat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn renameat +system call appeared in +.Fx 8.0 . |
