diff options
Diffstat (limited to 'man/man2/rename.2')
| -rw-r--r-- | man/man2/rename.2 | 549 |
1 files changed, 549 insertions, 0 deletions
diff --git a/man/man2/rename.2 b/man/man2/rename.2 new file mode 100644 index 000000000..617d8c29a --- /dev/null +++ b/man/man2/rename.2 @@ -0,0 +1,549 @@ +.\" 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> +.P +.BI "int rename(const char *" oldpath ", const char *" newpath ); +.P +.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" +.B #include <stdio.h> +.P +.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 +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf +.BR renameat (): + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.P +.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. +.P +Various restrictions determine whether or not the rename operation succeeds: +see ERRORS below. +.P +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. +.P +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. +.P +If +.I newpath +exists but the operation fails for some reason, +.BR rename () +guarantees to leave an instance of +.I newpath +in place. +.P +.I oldpath +can specify a directory. +In this case, +.I newpath +must either not exist, or it must specify an empty directory. +.P +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. +.P +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). +.P +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 ()). +.P +If +.I oldpath +is absolute, then +.I olddirfd +is ignored. +.P +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 . +.P +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 (). +.P +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.) +.P +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 +.P +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) |