diff options
Diffstat (limited to 'man2/rename.2')
| -rw-r--r-- | man2/rename.2 | 549 |
1 files changed, 0 insertions, 549 deletions
diff --git a/man2/rename.2 b/man2/rename.2 deleted file mode 100644 index 1391e2023..000000000 --- a/man2/rename.2 +++ /dev/null @@ -1,549 +0,0 @@ -.\" This manpage is Copyright (C) 1992 Drew Eckhardt; -.\" and Copyright (C) 1993 Michael Haardt; -.\" and Copyright (C) 1993,1995 Ian Jackson -.\" and Copyright (C) 2006, 2014 Michael Kerrisk -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" Modified Sat Jul 24 00:35:52 1993 by Rik Faith <faith@cs.unc.edu> -.\" Modified Thu Jun 4 12:21:13 1998 by Andries Brouwer <aeb@cwi.nl> -.\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt <michael@moria.de> -.\" 2007-03-25, mtk, added various text to DESCRIPTION. -.\" -.TH rename 2 (date) "Linux man-pages (unreleased)" -.SH NAME -rename, renameat, renameat2 \- change the name or location of a file -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <stdio.h> -.PP -.BI "int rename(const char *" oldpath ", const char *" newpath ); -.PP -.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" -.B #include <stdio.h> -.PP -.BI "int renameat(int " olddirfd ", const char *" oldpath , -.BI " int " newdirfd ", const char *" newpath ); -.BI "int renameat2(int " olddirfd ", const char *" oldpath , -.BI " int " newdirfd ", const char *" newpath \ -", unsigned int " flags ); -.fi -.PP -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.PP -.nf -.BR renameat (): - Since glibc 2.10: - _POSIX_C_SOURCE >= 200809L - Before glibc 2.10: - _ATFILE_SOURCE -.PP -.BR renameat2 (): - _GNU_SOURCE -.fi -.SH DESCRIPTION -.BR rename () -renames a file, moving it between directories if required. -Any other hard links to the file (as created using -.BR link (2)) -are unaffected. -Open file descriptors for -.I oldpath -are also unaffected. -.PP -Various restrictions determine whether or not the rename operation succeeds: -see ERRORS below. -.PP -If -.I newpath -already exists, it will be atomically replaced, so that there is -no point at which another process attempting to access -.I newpath -will find it missing. -However, there will probably be a window in which both -.I oldpath -and -.I newpath -refer to the file being renamed. -.PP -If -.I oldpath -and -.I newpath -are existing hard links referring to the same file, then -.BR rename () -does nothing, and returns a success status. -.PP -If -.I newpath -exists but the operation fails for some reason, -.BR rename () -guarantees to leave an instance of -.I newpath -in place. -.PP -.I oldpath -can specify a directory. -In this case, -.I newpath -must either not exist, or it must specify an empty directory. -.PP -If -.I oldpath -refers to a symbolic link, the link is renamed; if -.I newpath -refers to a symbolic link, the link will be overwritten. -.SS renameat() -The -.BR renameat () -system call operates in exactly the same way as -.BR rename (), -except for the differences described here. -.PP -If the pathname given in -.I oldpath -is relative, then it is interpreted relative to the directory -referred to by the file descriptor -.I olddirfd -(rather than relative to the current working directory of -the calling process, as is done by -.BR rename () -for a relative pathname). -.PP -If -.I oldpath -is relative and -.I olddirfd -is the special value -.BR AT_FDCWD , -then -.I oldpath -is interpreted relative to the current working -directory of the calling process (like -.BR rename ()). -.PP -If -.I oldpath -is absolute, then -.I olddirfd -is ignored. -.PP -The interpretation of -.I newpath -is as for -.IR oldpath , -except that a relative pathname is interpreted relative -to the directory referred to by the file descriptor -.IR newdirfd . -.PP -See -.BR openat (2) -for an explanation of the need for -.BR renameat (). -.SS renameat2() -.BR renameat2 () -has an additional -.I flags -argument. -A -.BR renameat2 () -call with a zero -.I flags -argument is equivalent to -.BR renameat (). -.PP -The -.I flags -argument is a bit mask consisting of zero or more of the following flags: -.TP -.B RENAME_EXCHANGE -Atomically exchange -.I oldpath -and -.IR newpath . -Both pathnames must exist -but may be of different types (e.g., one could be a non-empty directory -and the other a symbolic link). -.TP -.B RENAME_NOREPLACE -Don't overwrite -.I newpath -of the rename. -Return an error if -.I newpath -already exists. -.IP -.B RENAME_NOREPLACE -can't be employed together with -.BR RENAME_EXCHANGE . -.IP -.B RENAME_NOREPLACE -requires support from the underlying filesystem. -Support for various filesystems was added as follows: -.RS -.IP \[bu] 3 -ext4 (Linux 3.15); -.\" ext4: commit 0a7c3937a1f23f8cb5fc77ae01661e9968a51d0c -.IP \[bu] -btrfs, tmpfs, and cifs (Linux 3.17); -.IP \[bu] -xfs (Linux 4.0); -.\" btrfs: commit 80ace85c915d0f41016f82917218997b72431258 -.\" tmpfs: commit 3b69ff51d087d265aa4af3a532fc4f20bf33e718 -.\" cifs: commit 7c33d5972ce382bcc506d16235f1e9b7d22cbef8 -.\" -.\" gfs2 in Linux 4.2? -.IP \[bu] -Support for many other filesystems was added in Linux 4.9, including -ext2, minix, reiserfs, jfs, vfat, and bpf. -.\" Also affs, bfs, exofs, hfs, hfsplus, jffs2, logfs, msdos, -.\" nilfs2, omfs, sysvfs, ubifs, udf, ufs -.\" hugetlbfs, ramfs -.\" local filesystems: commit f03b8ad8d38634d13e802165cc15917481b47835 -.\" libfs: commit e0e0be8a835520e2f7c89f214dfda570922a1b90 -.RE -.TP -.BR RENAME_WHITEOUT " (since Linux 3.18)" -.\" commit 0d7a855526dd672e114aff2ac22b60fc6f155b08 -.\" commit 787fb6bc9682ec7c05fb5d9561b57100fbc1cc41 -This operation makes sense only for overlay/union -filesystem implementations. -.IP -Specifying -.B RENAME_WHITEOUT -creates a "whiteout" object at the source of -the rename at the same time as performing the rename. -The whole operation is atomic, -so that if the rename succeeds then the whiteout will also have been created. -.IP -A "whiteout" is an object that has special meaning in union/overlay -filesystem constructs. -In these constructs, -multiple layers exist and only the top one is ever modified. -A whiteout on an upper layer will effectively hide a -matching file in the lower layer, -making it appear as if the file didn't exist. -.IP -When a file that exists on the lower layer is renamed, -the file is first copied up (if not already on the upper layer) -and then renamed on the upper, read-write layer. -At the same time, the source file needs to be "whiteouted" -(so that the version of the source file in the lower layer -is rendered invisible). -The whole operation needs to be done atomically. -.IP -When not part of a union/overlay, -the whiteout appears as a character device with a {0,0} device number. -.\" https://www.freebsd.org/cgi/man.cgi?query=mount_unionfs&manpath=FreeBSD+11.0-RELEASE -(Note that other union/overlay implementations may employ different methods -for storing whiteout entries; specifically, BSD union mount employs -a separate inode type, -.BR DT_WHT , -which, while supported by some filesystems available in Linux, -such as CODA and XFS, is ignored by the kernel's whiteout support code, -as of Linux 4.19, at least.) -.IP -.B RENAME_WHITEOUT -requires the same privileges as creating a device node (i.e., the -.B CAP_MKNOD -capability). -.IP -.B RENAME_WHITEOUT -can't be employed together with -.BR RENAME_EXCHANGE . -.IP -.B RENAME_WHITEOUT -requires support from the underlying filesystem. -Among the filesystems that support it are -tmpfs (since Linux 3.18), -.\" tmpfs: commit 46fdb794e3f52ef18b859ebc92f0a9d7db21c5df -ext4 (since Linux 3.18), -.\" ext4: commit cd808deced431b66b5fa4e5c193cb7ec0059eaff -XFS (since Linux 4.1), -.\" XFS: commit 7dcf5c3e4527cfa2807567b00387cf2ed5e07f00 -f2fs (since Linux 4.2), -.\" f2fs: commit 7e01e7ad746bc8198a8b46163ddc73a1c7d22339 -btrfs (since Linux 4.7), -.\" btrfs: commit cdd1fedf8261cd7a73c0596298902ff4f0f04492 -and ubifs (since Linux 4.9). -.\" ubifs: commit 9e0a1fff8db56eaaebb74b4a3ef65f86811c4798 -.SH RETURN VALUE -On success, zero is returned. -On error, \-1 is returned, and -.I errno -is set to indicate the error. -.SH ERRORS -.TP -.B EACCES -Write permission is denied for the directory containing -.I oldpath -or -.IR newpath , -or, search permission is denied for one of the directories -in the path prefix of -.I oldpath -or -.IR newpath , -or -.I oldpath -is a directory and does not allow write permission (needed to update -the -.I .. -entry). -(See also -.BR path_resolution (7).) -.TP -.B EBUSY -The rename fails because -.IR oldpath " or " newpath -is a directory that is in use by some process (perhaps as -current working directory, or as root directory, or because -it was open for reading) or is in use by the system -(for example as a mount point), while the system considers -this an error. -(Note that there is no requirement to return -.B EBUSY -in such -cases\[em]there is nothing wrong with doing the rename anyway\[em]but -it is allowed to return -.B EBUSY -if the system cannot otherwise -handle such situations.) -.TP -.B EDQUOT -The user's quota of disk blocks on the filesystem has been exhausted. -.TP -.B EFAULT -.IR oldpath " or " newpath " points outside your accessible address space." -.TP -.B EINVAL -The new pathname contained a path prefix of the old, or, more generally, -an attempt was made to make a directory a subdirectory of itself. -.TP -.B EISDIR -.I newpath -is an existing directory, but -.I oldpath -is not a directory. -.TP -.B ELOOP -Too many symbolic links were encountered in resolving -.IR oldpath " or " newpath . -.TP -.B EMLINK -.I oldpath -already has the maximum number of links to it, or -it was a directory and the directory containing -.I newpath -has the maximum number of links. -.TP -.B ENAMETOOLONG -.IR oldpath " or " newpath " was too long." -.TP -.B ENOENT -The link named by -.I oldpath -does not exist; -or, a directory component in -.I newpath -does not exist; -or, -.I oldpath -or -.I newpath -is an empty string. -.TP -.B ENOMEM -Insufficient kernel memory was available. -.TP -.B ENOSPC -The device containing the file has no room for the new directory -entry. -.TP -.B ENOTDIR -A component used as a directory in -.IR oldpath " or " newpath -is not, in fact, a directory. -Or, -.I oldpath -is a directory, and -.I newpath -exists but is not a directory. -.TP -.BR ENOTEMPTY " or " EEXIST -.I newpath -is a nonempty directory, that is, contains entries other than "." and "..". -.TP -.BR EPERM " or " EACCES -The directory containing -.I oldpath -has the sticky bit -.RB ( S_ISVTX ) -set and the process's effective user ID is neither -the user ID of the file to be deleted nor that of the directory -containing it, and the process is not privileged -(Linux: does not have the -.B CAP_FOWNER -capability); -or -.I newpath -is an existing file and the directory containing it has the sticky bit set -and the process's effective user ID is neither the user ID of the file -to be replaced nor that of the directory containing it, -and the process is not privileged -(Linux: does not have the -.B CAP_FOWNER -capability); -or the filesystem containing -.I oldpath -does not support renaming of the type requested. -.TP -.B EROFS -The file is on a read-only filesystem. -.TP -.B EXDEV -.IR oldpath " and " newpath -are not on the same mounted filesystem. -(Linux permits a filesystem to be mounted at multiple points, but -.BR rename () -does not work across different mount points, -even if the same filesystem is mounted on both.) -.PP -The following additional errors can occur for -.BR renameat () -and -.BR renameat2 (): -.TP -.B EBADF -.I oldpath -.RI ( newpath ) -is relative but -.I olddirfd -.RI ( newdirfd ) -is not a valid file descriptor. -.TP -.B ENOTDIR -.I oldpath -is relative and -.I olddirfd -is a file descriptor referring to a file other than a directory; -or similar for -.I newpath -and -.I newdirfd -.PP -The following additional errors can occur for -.BR renameat2 (): -.TP -.B EEXIST -.I flags -contains -.B RENAME_NOREPLACE -and -.I newpath -already exists. -.TP -.B EINVAL -An invalid flag was specified in -.IR flags . -.TP -.B EINVAL -Both -.B RENAME_NOREPLACE -and -.B RENAME_EXCHANGE -were specified in -.IR flags . -.TP -.B EINVAL -Both -.B RENAME_WHITEOUT -and -.B RENAME_EXCHANGE -were specified in -.IR flags . -.TP -.B EINVAL -The filesystem does not support one of the flags in -.IR flags . -.TP -.B ENOENT -.I flags -contains -.B RENAME_EXCHANGE -and -.I newpath -does not exist. -.TP -.B EPERM -.B RENAME_WHITEOUT -was specified in -.IR flags , -but the caller does not have the -.B CAP_MKNOD -capability. -.SH STANDARDS -.TP -.BR rename () -C11, POSIX.1-2008. -.TP -.BR renameat () -POSIX.1-2008. -.TP -.BR renameat2 () -Linux. -.SH HISTORY -.TP -.BR rename () -4.3BSD, C89, POSIX.1-2001. -.TP -.BR renameat () -Linux 2.6.16, -glibc 2.4. -.TP -.BR renameat2 () -Linux 3.15, -glibc 2.28. -.SS glibc notes -On older kernels where -.BR renameat () -is unavailable, the glibc wrapper function falls back to the use of -.BR rename (). -When -.I oldpath -and -.I newpath -are relative pathnames, -glibc constructs pathnames based on the symbolic links in -.I /proc/self/fd -that correspond to the -.I olddirfd -and -.I newdirfd -arguments. -.SH BUGS -On NFS filesystems, you can not assume that if the operation -failed, the file was not renamed. -If the server does the rename operation -and then crashes, the retransmitted RPC which will be processed when the -server is up again causes a failure. -The application is expected to -deal with this. -See -.BR link (2) -for a similar problem. -.SH SEE ALSO -.BR mv (1), -.BR rename (1), -.BR chmod (2), -.BR link (2), -.BR symlink (2), -.BR unlink (2), -.BR path_resolution (7), -.BR symlink (7) |