Originální popis anglicky:
rename - rename a file
Návod, kniha: POSIX Programmer's Manual
#include <stdio.h>
int rename(const char *
old, const char
*new );
The
rename() function shall change the name of a file. The
old
argument points to the pathname of the file to be renamed. The
new
argument points to the new pathname of the file.
If either the
old or
new argument names a symbolic link,
rename() shall operate on the symbolic link itself, and shall not
resolve the last component of the argument. If the
old argument and the
new argument resolve to the same existing file,
rename() shall
return successfully and perform no other action.
If the
old argument points to the pathname of a file that is not a
directory, the
new argument shall not point to the pathname of a
directory. If the link named by the
new argument exists, it shall be
removed and
old renamed to
new. In this case, a link named
new shall remain visible to other processes throughout the renaming
operation and refer either to the file referred to by
new or
old
before the operation began. Write access permission is required for both the
directory containing
old and the directory containing
new.
If the
old argument points to the pathname of a directory, the
new
argument shall not point to the pathname of a file that is not a directory. If
the directory named by the
new argument exists, it shall be removed and
old renamed to
new. In this case, a link named
new shall
exist throughout the renaming operation and shall refer either to the
directory referred to by
new or
old before the operation began.
If
new names an existing directory, it shall be required to be an empty
directory.
If the
old argument points to a pathname of a symbolic link, the symbolic
link shall be renamed. If the
new argument points to a pathname of a
symbolic link, the symbolic link shall be removed.
The
new pathname shall not contain a path prefix that names
old.
Write access permission is required for the directory containing
old
and the directory containing
new. If the
old argument points to
the pathname of a directory, write access permission may be required for the
directory named by
old, and, if it exists, the directory named by
new.
If the link named by the
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
rename() returns, but the
removal of the file contents shall be postponed until all references to the
file are closed.
Upon successful completion,
rename() shall mark for update the
st_ctime and
st_mtime fields of the parent directory of each
file.
If the
rename() function fails for any reason other than [EIO], any file
named by
new shall be unaffected.
Upon successful completion,
rename() shall return 0; otherwise, -1 shall
be returned,
errno shall be set to indicate the error, and neither the
file named by
old nor the file named by
new shall be changed or
created.
The
rename() function shall fail if:
- EACCES
- A component of either path prefix denies search permission;
or one of the directories containing old or new denies write
permissions; or, write permission is required and is denied for a
directory pointed to by the old or new arguments.
- EBUSY
- The directory named by old or new is
currently in use by the system or another process, and the implementation
considers this an error.
- EEXIST or ENOTEMPTY
-
The link named by new is a directory that is not an empty
directory.
- EINVAL
- The new directory pathname contains a path prefix
that names the old directory.
- EIO
- A physical I/O error has occurred.
- EISDIR
- The new argument points to a directory and the
old argument points to a file that is not a directory.
- ELOOP
- A loop exists in symbolic links encountered during
resolution of the path argument.
- EMLINK
- The file named by old is a directory, and the link
count of the parent directory of new would exceed {LINK_MAX}.
- ENAMETOOLONG
-
The length of the old or new argument exceeds {PATH_MAX} or a
pathname component is longer than {NAME_MAX}.
- ENOENT
- The link named by old does not name an existing
file, or either old or new points to an empty string.
- ENOSPC
- The directory that would contain new cannot be
extended.
- ENOTDIR
- A component of either path prefix is not a directory; or
the old argument names a directory and new argument names a
non-directory file.
- EPERM or EACCES
-
The S_ISVTX flag is set on the directory containing the file referred to by
old and the caller is not the file owner, nor is the caller the
directory owner, nor does the caller have appropriate privileges; or
new 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.
- EROFS
- The requested operation requires writing in a directory on
a read-only file system.
- EXDEV
- The links named by new and old are on
different file systems and the implementation does not support links
between file systems.
The
rename() function may fail if:
- EBUSY
- The file named by the old or new arguments is
a named STREAM.
- ELOOP
- More than {SYMLOOP_MAX} symbolic links were encountered
during resolution of the path argument.
- ENAMETOOLONG
-
As a result of encountering a symbolic link in resolution of the path
argument, the length of the substituted pathname string exceeded
{PATH_MAX}.
- ETXTBSY
- The file to be renamed is a pure procedure (shared text)
file that is being executed.
The following sections are informative.
The following example shows how to rename a file named
/home/cnd/mod1 to
/home/cnd/mod2.
#include <stdio.h>
int status;
...
status = rename("/home/cnd/mod1", "/home/cnd/mod2");
Some implementations mark for update the
st_ctime field of renamed files
and some do not. Applications which make use of the
st_ctime field may
behave differently with respect to renamed files unless they are designed to
allow for either behavior.
This
rename() 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
new
parameter names a file that already exists. That specification requires that
the action of the function be atomic.
One of the reasons for introducing this function was to have a means of renaming
directories while permitting implementations to prohibit the use of
link() and
unlink() with directories, thus constraining links to
directories to those made by
mkdir().
The specification that if
old and
new refer to the same file is
intended to guarantee that:
does not remove the file.
Renaming dot or dot-dot is prohibited in order to prevent cyclical file system
paths.
See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in
rmdir()
and [EBUSY] in
unlink() . For a discussion of [EXDEV], see
link() .
None.
link() ,
rmdir() ,
symlink() ,
unlink() , the Base
Definitions volume of IEEE Std 1003.1-2001,
<stdio.h>
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
.
