summaryrefslogtreecommitdiffstats
path: root/man2/rename.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/rename.2')
-rw-r--r--man2/rename.2549
1 files changed, 0 insertions, 549 deletions
diff --git a/man2/rename.2 b/man2/rename.2
deleted file mode 100644
index 6b538d4..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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)