mirror of https://github.com/mkerrisk/man-pages
535 lines
12 KiB
Groff
535 lines
12 KiB
Groff
.\" 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
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 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 2016-10-08 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
rename, renameat, renameat2 \- change the name or location of a file
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <stdio.h>
|
|
.sp
|
|
.BI "int rename(const char *" oldpath ", const char *" newpath );
|
|
.sp
|
|
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
|
|
.B #include <stdio.h>
|
|
.sp
|
|
.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
|
|
|
|
.IR Note :
|
|
There is no glibc wrapper for
|
|
.BR renameat2 ();
|
|
see NOTES.
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR renameat ():
|
|
.PD 0
|
|
.ad l
|
|
.RS 4
|
|
.TP 4
|
|
Since glibc 2.10:
|
|
_POSIX_C_SOURCE\ >=\ 200809L
|
|
.TP
|
|
Before glibc 2.10:
|
|
_ATFILE_SOURCE
|
|
.\" FIXME . need to define FTMs for renameat2(), once it hits glibc
|
|
.RE
|
|
.ad
|
|
.PD
|
|
.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.
|
|
|
|
Various restrictions determine whether or not the rename operation succeeds:
|
|
see ERRORS below.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
If
|
|
.I newpath
|
|
exists but the operation fails for some reason,
|
|
.BR rename ()
|
|
guarantees to leave an instance of
|
|
.I newpath
|
|
in place.
|
|
|
|
.I oldpath
|
|
can specify a directory.
|
|
In this case,
|
|
.I newpath
|
|
must either not exist, or it must specify an empty directory.
|
|
|
|
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.
|
|
|
|
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).
|
|
|
|
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 ()).
|
|
|
|
If
|
|
.I oldpath
|
|
is absolute, then
|
|
.I olddirfd
|
|
is ignored.
|
|
|
|
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 .
|
|
|
|
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 ().
|
|
|
|
The
|
|
.I flags
|
|
argument is a bit mask consisting of zero or more of the following flags:
|
|
.TP
|
|
.B RENAME_EXCHANGE
|
|
Atomically exchange
|
|
.IR 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
|
|
.IR newpath
|
|
of the rename.
|
|
Return an error if
|
|
.IR newpath
|
|
already exists.
|
|
|
|
.B RENAME_NOREPLACE
|
|
can't be employed together with
|
|
.BR RENAME_EXCHANGE .
|
|
.TP
|
|
.BR RENAME_WHITEOUT " (since Linux 3.18)"
|
|
.\" commit 0d7a855526dd672e114aff2ac22b60fc6f155b08
|
|
.\" commit 787fb6bc9682ec7c05fb5d9561b57100fbc1cc41
|
|
This operation makes sense only for overlay/union
|
|
filesystem implementations.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
When not part of a union/overlay,
|
|
the whiteout appears as a character device with a {0,0} device number.
|
|
|
|
.B RENAME_WHITEOUT
|
|
requires the same privileges as creating a device node (i.e., the
|
|
.BR CAP_MKNOD
|
|
capability).
|
|
|
|
.B RENAME_WHITEOUT
|
|
can't be employed together with
|
|
.BR RENAME_EXCHANGE .
|
|
|
|
.B RENAME_WHITEOUT
|
|
requires support from the underlying filesystem.
|
|
Among the filesystems that provide that support are
|
|
shmem (since Linux 3.18),
|
|
.\" shmem: commit 46fdb794e3f52ef18b859ebc92f0a9d7db21c5df
|
|
ext4 (since Linux 3.18),
|
|
.\" ext4: commit cd808deced431b66b5fa4e5c193cb7ec0059eaff
|
|
and XFS (since Linux 4.1).
|
|
.\" XFS: commit 7dcf5c3e4527cfa2807567b00387cf2ed5e07f00
|
|
.SH RETURN VALUE
|
|
On success, zero is returned.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.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 mount point), while the system considers
|
|
this an error.
|
|
(Note that there is no requirement to return
|
|
.B EBUSY
|
|
in such
|
|
cases\(emthere is nothing wrong with doing the rename anyway\(embut
|
|
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 pathname
|
|
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 olddirfd
|
|
or
|
|
.I 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
|
|
.IR 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 VERSIONS
|
|
.BR renameat ()
|
|
was added to Linux in kernel 2.6.16;
|
|
library support was added to glibc in version 2.4.
|
|
|
|
.BR renameat2 ()
|
|
was added to Linux in kernel 3.15.
|
|
.\" FIXME . glibc support is pending.
|
|
.SH CONFORMING TO
|
|
.BR rename ():
|
|
4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.
|
|
|
|
.BR renameat ():
|
|
POSIX.1-2008.
|
|
|
|
.BR renameat2 ()
|
|
is Linux-specific.
|
|
.SH NOTES
|
|
Glibc does not provide a wrapper for the
|
|
.BR renameat2 ()
|
|
system call; call it using
|
|
.BR syscall (2).
|
|
.\"
|
|
.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
|
|
.IR /proc/self/fd
|
|
that correspond to the
|
|
.I olddirfd
|
|
and
|
|
.IR 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 chmod (2),
|
|
.BR link (2),
|
|
.BR symlink (2),
|
|
.BR unlink (2),
|
|
.BR path_resolution (7),
|
|
.BR symlink (7)
|