Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 549 insertions, 0 deletions

diff --git a/man/man2/rename.2 b/man/man2/rename.2
new file mode 100644
index 0000000..1ab88ba
--- /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 2024-05-02 "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)