mirror of https://github.com/mkerrisk/man-pages
263 lines
8.8 KiB
Plaintext
263 lines
8.8 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "RENAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" rename
|
|
.SH NAME
|
|
rename \- rename a file
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <stdio.h>
|
|
.br
|
|
.sp
|
|
int rename(const char *\fP\fIold\fP\fB, const char *\fP\fInew\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIrename\fP() function shall change the name of a file. The \fIold\fP
|
|
argument points to the pathname of the file to be
|
|
renamed. The \fInew\fP argument points to the new pathname of the
|
|
file.
|
|
.LP
|
|
If
|
|
either the \fIold\fP or \fInew\fP argument names a symbolic link,
|
|
\fIrename\fP() shall operate on the symbolic link itself, and
|
|
shall not resolve the last component of the argument. If the \fIold\fP
|
|
argument and the \fInew\fP argument resolve to the same
|
|
existing file, \fIrename\fP() shall return successfully and perform
|
|
no other action.
|
|
.LP
|
|
If the \fIold\fP argument points to the pathname of a file that is
|
|
not a directory, the \fInew\fP argument shall not point to
|
|
the pathname of a directory. If the link named by the \fInew\fP argument
|
|
exists, it shall be removed and \fIold\fP renamed to
|
|
\fInew\fP. In this case, a link named \fInew\fP shall remain visible
|
|
to other processes throughout the renaming operation and
|
|
refer either to the file referred to by \fInew\fP or \fIold\fP before
|
|
the operation began. Write access permission is required
|
|
for both the directory containing \fIold\fP and the directory containing
|
|
\fInew\fP.
|
|
.LP
|
|
If the \fIold\fP argument points to the pathname of a directory, the
|
|
\fInew\fP argument shall not point to the pathname of a
|
|
file that is not a directory. If the directory named by the \fInew\fP
|
|
argument exists, it shall be removed and \fIold\fP renamed
|
|
to \fInew\fP. In this case, a link named \fInew\fP shall exist throughout
|
|
the renaming operation and shall refer either to the
|
|
directory referred to by \fInew\fP or \fIold\fP before the operation
|
|
began. If \fInew\fP names an existing directory, it shall
|
|
be required to be an empty directory.
|
|
.LP
|
|
If the \fIold\fP argument points to a pathname of a symbolic link,
|
|
the symbolic link shall be renamed. If the \fInew\fP
|
|
argument points to a pathname of a symbolic link, the symbolic link
|
|
shall be removed.
|
|
.LP
|
|
The \fInew\fP pathname shall not contain a path prefix that names
|
|
\fIold\fP. Write access permission is required for the
|
|
directory containing \fIold\fP and the directory containing \fInew\fP.
|
|
If the \fIold\fP argument points to the pathname of a
|
|
directory, write access permission may be required for the directory
|
|
named by \fIold\fP, and, if it exists, the directory named by
|
|
\fInew\fP.
|
|
.LP
|
|
If the link named by the \fInew\fP 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\fP() returns, but the removal of the
|
|
file contents shall be postponed until all references to the file
|
|
are closed.
|
|
.LP
|
|
Upon successful completion, \fIrename\fP() shall mark for update the
|
|
\fIst_ctime\fP and \fIst_mtime\fP fields of the parent
|
|
directory of each file.
|
|
.LP
|
|
If the \fIrename\fP() function fails for any reason other than [EIO],
|
|
any file named by \fInew\fP shall be unaffected.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIrename\fP() shall return 0; otherwise,
|
|
-1 shall be returned, \fIerrno\fP shall
|
|
be set to indicate the error, and neither the file named by
|
|
\fIold\fP nor the file named by \fInew\fP shall be changed or created.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIrename\fP() function shall fail if:
|
|
.TP 7
|
|
.B EACCES
|
|
A
|
|
component of either path prefix denies search permission; or one of
|
|
the directories containing \fIold\fP or \fInew\fP denies
|
|
write permissions; or, write permission is required and is denied
|
|
for a directory pointed to by the \fIold\fP or \fInew\fP
|
|
arguments.
|
|
.TP 7
|
|
.B EBUSY
|
|
The directory named by \fIold\fP or \fInew\fP is currently in use
|
|
by the system or another process, and the implementation
|
|
considers this an error.
|
|
.TP 7
|
|
.B EEXIST \fRor\fP ENOTEMPTY
|
|
.sp
|
|
The link named by \fInew\fP is a directory that is not an empty directory.
|
|
.TP 7
|
|
.B EINVAL
|
|
The \fInew\fP directory pathname contains a path prefix that names
|
|
the \fIold\fP directory.
|
|
.TP 7
|
|
.B EIO
|
|
A
|
|
physical I/O error has occurred.
|
|
.TP 7
|
|
.B EISDIR
|
|
The \fInew\fP argument points to a directory and the \fIold\fP argument
|
|
points to a file that is not a directory.
|
|
.TP 7
|
|
.B ELOOP
|
|
A
|
|
loop exists in symbolic links encountered during resolution of the
|
|
\fIpath\fP argument.
|
|
.TP 7
|
|
.B EMLINK
|
|
The file named by \fIold\fP is a directory, and the link count of
|
|
the parent directory of \fInew\fP would exceed {LINK_MAX}.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
.sp
|
|
The length of the \fIold\fP or \fInew\fP argument exceeds {PATH_MAX}
|
|
or a pathname component is longer than {NAME_MAX}.
|
|
.TP 7
|
|
.B ENOENT
|
|
The link named by \fIold\fP does not name an existing file, or either
|
|
\fIold\fP or \fInew\fP points to an empty string.
|
|
.TP 7
|
|
.B ENOSPC
|
|
The directory that would contain \fInew\fP cannot be extended.
|
|
.TP 7
|
|
.B ENOTDIR
|
|
A
|
|
component of either path prefix is not a directory; or the \fIold\fP
|
|
argument names a directory and \fInew\fP argument names a
|
|
non-directory file.
|
|
.TP 7
|
|
.B EPERM \fRor\fP EACCES
|
|
.sp
|
|
The S_ISVTX flag is set on the directory containing the file referred
|
|
to by \fIold\fP and the caller is not the file owner, nor is
|
|
the caller the directory owner, nor does the caller have appropriate
|
|
privileges; or \fInew\fP refers to an existing file, the
|
|
S_ISVTX flag is set on the directory containing this file, and the
|
|
caller is not the file owner, nor is the caller the directory
|
|
owner, nor does the caller have appropriate privileges.
|
|
.TP 7
|
|
.B EROFS
|
|
The requested operation requires writing in a directory on a read-only
|
|
file system.
|
|
.TP 7
|
|
.B EXDEV
|
|
The links named by \fInew\fP and \fIold\fP are on different file systems
|
|
and the implementation does not support links between
|
|
file systems.
|
|
.sp
|
|
.LP
|
|
The \fIrename\fP() function may fail if:
|
|
.TP 7
|
|
.B EBUSY
|
|
The file named by the \fIold\fP or \fInew\fP arguments is a named
|
|
STREAM.
|
|
.TP 7
|
|
.B ELOOP
|
|
More than {SYMLOOP_MAX} symbolic links were encountered during resolution
|
|
of the \fIpath\fP argument.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
.sp
|
|
As a result of encountering a symbolic link in resolution of the \fIpath\fP
|
|
argument, the length of the substituted pathname
|
|
string exceeded {PATH_MAX}.
|
|
.TP 7
|
|
.B ETXTBSY
|
|
The file to be renamed is a pure procedure (shared text) file that
|
|
is being executed.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Renaming a File
|
|
.LP
|
|
The following example shows how to rename a file named \fB/home/cnd/mod1\fP
|
|
to \fB/home/cnd/mod2\fP.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <stdio.h>
|
|
.sp
|
|
|
|
int status;
|
|
\&...
|
|
status = rename("/home/cnd/mod1", "/home/cnd/mod2");
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
Some implementations mark for update the \fIst_ctime\fP field of renamed
|
|
files and some do not. Applications which make use of
|
|
the \fIst_ctime\fP field may behave differently with respect to renamed
|
|
files unless they are designed to allow for either
|
|
behavior.
|
|
.SH RATIONALE
|
|
.LP
|
|
This \fIrename\fP() 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 \fInew\fP parameter names a file that
|
|
already exists. That specification requires that the action of the
|
|
function be atomic.
|
|
.LP
|
|
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\fP() and \fIunlink\fP()
|
|
with directories, thus constraining links to directories to those
|
|
made by \fImkdir\fP().
|
|
.LP
|
|
The specification that if \fIold\fP and \fInew\fP refer to the same
|
|
file is intended to guarantee that:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBrename("x", "x");
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
does not remove the file.
|
|
.LP
|
|
Renaming dot or dot-dot is prohibited in order to prevent cyclical
|
|
file system paths.
|
|
.LP
|
|
See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in \fIrmdir\fP()
|
|
and [EBUSY] in \fIunlink\fP() . For a discussion of [EXDEV], see \fIlink\fP()
|
|
\&.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIlink\fP() , \fIrmdir\fP() , \fIsymlink\fP() ,
|
|
\fIunlink\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<stdio.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|