path: root/upstream/archlinux/man3p/rename.3p

'\" et
.TH RENAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
rename, renameat
\(em rename file
.SH SYNOPSIS
.LP
.nf
#include <stdio.h>
.P
int rename(const char *\fIold\fP, const char *\fInew\fP);
.P
#include <fcntl.h>
.P
int renameat(int \fIoldfd\fP, const char *\fIold\fP, int \fInewfd\fP,
    const char *\fInew\fP);
.fi
.SH DESCRIPTION
For
\fIrename\fR():
The functionality described on this reference page is aligned with the
ISO\ C standard. Any conflict between the requirements described here and the
ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
.P
The
\fIrename\fR()
function shall change the name of a file. The
.IR old
argument points to the pathname of the file to be renamed. The
.IR new
argument points to the new pathname of the file.
If the
.IR new
argument does not resolve to an existing directory entry for a file of
type directory and the
.IR new
argument contains at least one non-\c
<slash>
character and ends with one or more trailing
<slash>
characters after all symbolic links have been processed,
\fIrename\fR()
shall fail.
.P
If either the
.IR old
or
.IR new
argument names a symbolic link,
\fIrename\fR()
shall operate on the symbolic link itself, and shall not resolve the
last component of the argument. If the
.IR old
argument and the
.IR new
argument resolve to either the same existing directory entry or different
directory entries for the same existing file,
\fIrename\fR()
shall return successfully and perform no other action.
.P
If the
.IR old
argument points to the pathname of a file that is not a directory, the
.IR new
argument shall not point to the pathname of a directory. If the link
named by the
.IR new
argument exists, it shall be removed and
.IR old
renamed to
.IR new .
In this case, a link named
.IR new
shall remain visible to other threads throughout the renaming operation
and refer either to the file referred to by
.IR new
or
.IR old
before the operation began. Write access permission is required for
both the directory containing
.IR old
and the directory containing
.IR new .
.P
If the
.IR old
argument points to the pathname of a directory, the
.IR new
argument shall not point to the pathname of a file that is not a
directory. If the directory named by the
.IR new
argument exists, it shall be removed and
.IR old
renamed to
.IR new .
In this case, a link named
.IR new
shall exist throughout the renaming operation and shall refer either to
the directory referred to by
.IR new
or
.IR old
before the operation began. If
.IR new
names an existing directory, it shall be required to be an empty
directory.
.P
If either
.IR pathname
argument refers to a path whose final component is either dot or
dot-dot,
\fIrename\fR()
shall fail.
.P
If the
.IR old
argument points to a pathname of a symbolic link, the symbolic link
shall be renamed. If the
.IR new
argument points to a pathname of a symbolic link, the symbolic link
shall be removed.
.P
The
.IR old
pathname shall not name an ancestor directory of the
.IR new
pathname. Write access permission is required for the directory containing
.IR old
and the directory containing
.IR new .
If the
.IR old
argument points to the pathname of a directory, write access permission
may be required for the directory named by
.IR old ,
and, if it exists, the directory named by
.IR new .
.P
If the link named by the
.IR new
argument exists and the file's link count becomes 0 when it is removed
and no process has the file open, the space occupied by the file shall
be freed and the file shall no longer be accessible. If one or more
processes have the file open when the last link is removed, the link
shall be removed before
\fIrename\fR()
returns, but the removal of the file contents shall be postponed until
all references to the file are closed.
.P
Upon successful completion,
\fIrename\fR()
shall mark for update the last data modification and last file status
change timestamps of the parent directory of each file.
.P
If the
\fIrename\fR()
function fails for any reason other than
.BR [EIO] ,
any file named by
.IR new
shall be unaffected.
.P
The
\fIrenameat\fR()
function shall be equivalent to the
\fIrename\fR()
function except in the case where either
.IR old
or
.IR new
specifies a relative path. If
.IR old
is a relative path, the file to be renamed is located relative to the
directory associated with the file descriptor
.IR oldfd
instead of the current working directory. If
.IR new
is a relative path, the same happens only relative to the directory
associated with
.IR newfd .
If the access mode of the open file description associated with the
file descriptor is not O_SEARCH, the function shall check whether
directory searches are permitted using the current permissions of
the directory underlying the file descriptor. If the access mode is
O_SEARCH, the function shall not perform the check.
.P
If
\fIrenameat\fR()
is passed the special value AT_FDCWD in the
.IR oldfd
or
.IR newfd
parameter, the current working directory shall be used in the
determination of the file for the respective
.IR path
parameter.
.SH "RETURN VALUE"
Upon successful completion, the
\fIrename\fR()
function shall return 0. Otherwise, it shall return \-1,
.IR errno
shall be set to indicate the error,
and neither the file named by
.IR old
nor the file named by
.IR new
shall be changed or created.
.P
Upon successful completion, the
\fIrenameat\fR()
function shall return 0. Otherwise, it shall return \-1 and set
.IR errno
to indicate the error.
.SH ERRORS
The
\fIrename\fR()
and
\fIrenameat\fR()
functions shall fail if:
.TP
.BR EACCES
A component of either path prefix denies search permission; or one of
the directories containing
.IR old
or
.IR new
denies write permissions; or, write permission is required and is
denied for a directory pointed to by the
.IR old
or
.IR new
arguments.
.TP
.BR EBUSY
The directory named by
.IR old
or
.IR new
is currently in use by the system or another process, and the
implementation considers this an error.
.IP "[EEXIST]\ or\ [ENOTEMPTY]" 12
.br
The link named by
.IR new
is a directory that is not an empty directory.
.TP
.BR EINVAL
The
.IR old
pathname names an ancestor directory of the
.IR new
pathname, or either pathname argument contains a final component that
is dot or dot-dot.
.TP
.BR EIO
A physical I/O error has occurred.
.TP
.BR EISDIR
The
.IR new
argument points to a directory and the
.IR old
argument points to a file that is not a directory.
.TP
.BR ELOOP
A loop exists in symbolic links encountered during resolution of the
.IR path
argument.
.TP
.BR EMLINK
The file named by
.IR old
is a directory, and the link count of the parent directory of
.IR new
would exceed
{LINK_MAX}.
.TP
.BR ENAMETOOLONG
.br
The length of a component of a pathname is longer than
{NAME_MAX}.
.TP
.BR ENOENT
The link named by
.IR old
does not name an existing file, a component of the path prefix of
.IR new
does not exist, or either
.IR old
or
.IR new
points to an empty string.
.TP
.BR ENOSPC
The directory that would contain
.IR new
cannot be extended.
.TP
.BR ENOTDIR
A component of either path prefix names an existing file that is
neither a directory nor a symbolic link to a directory; or the
.IR old
argument names a directory and the
.IR new
argument names a non-directory file; or the
.IR old
argument contains at least one non-\c
<slash>
character and ends with one or more trailing
<slash>
characters and the last pathname component names an existing file that
is neither a directory nor a symbolic link to a directory; or the
.IR old
argument names an existing non-directory file and the
.IR new
argument names a nonexistent file, contains at least one non-\c
<slash>
character, and ends with one or more trailing
<slash>
characters; or the
.IR new
argument names an existing non-directory file, contains at least one non-\c
<slash>
character, and ends with one or more trailing
<slash>
characters.
.TP
.BR EPERM " or " EACCES
.br
The S_ISVTX flag is set on the directory containing the file referred
to by
.IR old
and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 4.3" ", " "Directory Protection"
with respect to
.IR old ;
or
.IR new
refers to an existing file, the S_ISVTX flag is set on the directory
containing this file, and the process does not satisfy the criteria
specified in the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 4.3" ", " "Directory Protection"
with respect to this file.
.TP
.BR EROFS
The requested operation requires writing in a directory on a read-only
file system.
.TP
.BR EXDEV
The links named by
.IR new
and
.IR old
are on different file systems and the implementation does not support
links between file systems.
.P
In addition, the
\fIrenameat\fR()
function shall fail if:
.TP
.BR EACCES
The access mode of the open file description associated with
.IR oldfd
or
.IR newfd
is not O_SEARCH and the permissions of the directory underlying
.IR oldfd
or
.IR newfd ,
respectively, do not permit directory searches.
.TP
.BR EBADF
The
.IR old
argument does not specify an absolute path and the
.IR oldfd
argument is neither AT_FDCWD nor a valid file descriptor open for
reading or searching, or the
.IR new
argument does not specify an absolute path and the
.IR newfd
argument is neither AT_FDCWD nor a valid file descriptor open
for reading or searching.
.TP
.BR ENOTDIR
The
.IR old
or
.IR new
argument is not an absolute path and
.IR oldfd
or
.IR newfd ,
respectively, is a file descriptor associated with a non-directory file.
.P
The
\fIrename\fR()
and
\fIrenameat\fR()
functions may fail if:
.TP
.BR EBUSY
The file named by the
.IR old
or
.IR new
arguments is a named STREAM.
.TP
.BR ELOOP
More than
{SYMLOOP_MAX}
symbolic links were encountered during resolution of the
.IR path
argument.
.TP
.BR ENAMETOOLONG
.br
The length of a pathname exceeds
{PATH_MAX},
or pathname resolution of a symbolic link produced an intermediate
result with a length that exceeds
{PATH_MAX}.
.TP
.BR ETXTBSY
The file named by
.IR new
exists and is the last directory entry to a pure procedure (shared text)
file that is being executed.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
.SS "Renaming a File"
.P
The following example shows how to rename a file named
.BR /home/cnd/mod1
to
.BR /home/cnd/mod2 .
.sp
.RS 4
.nf

#include <stdio.h>
.P
int status;
\&...
status = rename("/home/cnd/mod1", "/home/cnd/mod2");
.fi
.P
.RE
.SH "APPLICATION USAGE"
Some implementations mark for update the last file status change timestamp
of renamed files and some do not. Applications which make use of the
last file status change timestamp may behave differently with respect
to renamed files unless they are designed to allow for either behavior.
.SH RATIONALE
This
\fIrename\fR()
function is equivalent for regular files to that defined by the ISO\ C standard.
Its inclusion here expands that definition to include actions on
directories and specifies behavior when the
.IR new
parameter names a file that already exists. That specification
requires that the action of the function be atomic.
.P
One of the reasons for introducing this function was to have a means of
renaming directories while permitting implementations to prohibit the
use of
\fIlink\fR()
and
\fIunlink\fR()
with directories, thus constraining links to directories to those made by
\fImkdir\fR().
.P
The specification that if
.IR old
and
.IR new
refer to the same file is intended to guarantee that:
.sp
.RS 4
.nf

rename("x", "x");
.fi
.P
.RE
.P
does not remove the file.
.P
Renaming dot or dot-dot is prohibited in order to prevent cyclical file
system paths.
.P
See also the descriptions of
.BR [ENOTEMPTY] 
and
.BR [ENAMETOOLONG] 
in
\fIrmdir\fR()
and
.BR [EBUSY] 
in
\fIunlink\fR().
For a discussion of
.BR [EXDEV] ,
see
\fIlink\fR().
.P
The purpose of the
\fIrenameat\fR()
function is to rename files in directories other than the current
working directory without exposure to race conditions. Any part of the
path of a file could be changed in parallel to a call to
\fIrename\fR(),
resulting in unspecified behavior. By opening file descriptors for the
source and target directories and using the
\fIrenameat\fR()
function it can be guaranteed that that renamed file is located correctly
and the resulting file is in the desired directory.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIlink\fR\^(\|)",
.IR "\fIrmdir\fR\^(\|)",
.IR "\fIsymlink\fR\^(\|)",
.IR "\fIunlink\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 4.3" ", " "Directory Protection",
.IR "\fB<fcntl.h>\fP",
.IR "\fB<stdio.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .