rename - Rename a directory or a file within a file system
#include <stdio.h>
int rename(
const char *from,
const char *to );
[Tru64 UNIX] The following definition of the rename()
function does not conform to industry standards and is
supported only for backward compatibility (see standards(5)): int rename(
char *from,
char *to );
Interfaces documented on this reference page conform to
industry standards as follows:
rename(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Identifies the file or directory to be renamed. Identifies
the new pathname of the file or directory to be
renamed. If the to parameter is an existing file or empty
directory, it is replaced by the from parameter. If the to
parameter is a nonempty directory, the rename() function
exits with an error.
The rename() function renames a directory or a file within
a file system.
For rename() to complete successfully, the calling process
must have write and search permission to the parent directories
of both the from and to parameters. If the from
parameter is a directory and the parent directories of
from and to are different, then the calling process must
have write and search permission to the from parameter as
well.
If the from and to parameters both refer to the same
existing file, the rename() function returns successfully
and performs no other action.
Both the from and to parameters must be of the same type
(that is, both are directories or both are not directories)
and must reside on the same file system. If the to
parameter already exists, it is first removed. In this
case it is guaranteed that a link named the to parameter
will exist throughout the operation. This link refers to
the file named by either the to or from parameter before
the operation began.
If the final component of the from parameter is a symbolic
link, the symbolic link (not the file or directory to
which it points) is renamed. If the final component of the
to parameter is a symbolic link, the symbolic link is
destroyed.
If the from and to parameters name directories, the following
must be true: The from parameter is not an ancestor
of the to parameter. For example, the to pathname must not
contain a path prefix that names from. The from parameter
is well-formed. For example, the (dot) entry in
from, if it exists, refers to the same directory as from,
exactly one directory has a link to from (excluding the
self-referential (dot-dot) entry in from, if it exists,
refers to the directory that contains an entry for from.
The to parameter, if it exists, must be well-formed (as
defined previously).
Upon successful completion, the rename() function marks
the st_ctime and st_mtime fields of the parent directory
of each file for update.
Upon successful completion, the rename() function returns
a value of 0 (zero). Otherwise, a value of -1 is returned,
and errno is set to indicate the error.
If the rename() function fails, the file or directory name
remains unchanged and errno may be set to one of the following
values: Creating the requested link requires writing
in a directory with a mode that denies write permission,
or a component of either pathname denies search permission.
The directory named by the from or to parameter
is currently in use by the system or by another process.
[Tru64 UNIX] The directory that would contain to cannot
be extended because the user's quota of disk blocks on the
file system containing the directory is exhausted. The to
parameter is an existing nonempty directory. [Tru64
UNIX] Either the to or from parameter is an invalid
address. Either the from or to parameter is not a wellformed
directory, an attempt is made to rename . (dot) or
.. (dot-dot), or the from parameter is an ancestor of the
to parameter. A physical I/O error occurred. The to
parameter names a directory and the from parameter names a
nondirectory. Too many links were encountered in translating
either to or from. The from parameter is a directory
and the link count of the to parameter's parent
directory would exceed LINK_MAX. The length of the to or
from parameter exceeds PATH_MAX or a pathname component is
longer than NAME_MAX. [Tru64 UNIX] Indicates either that
the system file table is full, or that there are too many
files currently open in the system. A component of either
path does not exist, or either path is the empty string,
or the file named by the from parameter does not exist.
The directory that would contain to cannot be extended
because the file system is out of space. The from parameter
names a directory and the to parameter names a nondirectory.
The S_ISVTX flag is set on the directory containing
the file to be renamed, and the caller is not the
file owner. The requested operation requires writing in a
directory on a read-only file system. The link named by
the to parameter and the file named by the from parameter
are on different file systems.
Commands: chmod(1), mkdir(1), mv(1), mvdir(1)
Functions: chmod(2), link(2), mkdir(2), rmdir(2),
unlink(2)
Standards: standards(5)
rename(2)
[ Back ] |
