rename(2) CLIX rename(2)
NAME
rename - Renames a directory or a file within a file system
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <stdio.h>
int rename(
char *from_path ,
char *to_path );
PARAMETERS
from_path Points to the file or directory to be renamed.
to_path Points to the new pathname of the file or directory to be
renamed. If to_path is an existing file or empty directory,
it is replaced by from_path. If to_path is a nonempty
directory, rename() exits with an error.
DESCRIPTION
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 from_path and
to_path. If from_path is a directory and the parent directories of
from_path and to_path are different, the calling process must have write
and search permission to from_path as well.
If both from_path and to_path both refer to the same existing file,
rename() returns successfully and performs no other action.
Both from_path and to_path must be of the same type (that is, both
directories or both non-directories) and must reside on the same file
system. If to_path already exists, it is first removed. In this case it
is guaranteed that a link named to_path will exist throughout the
operation. This link refers to the file named by either to_path or
from_path before the operation began.
If the from_path and to_path parameters name directories, the following
must be true:
⊕ The from_path parameter is not an ancestor of to_path. For example,
the from_path pathname must not contain a path prefix that names
to_path.
2/94 - Intergraph Corporation 1
rename(2) CLIX rename(2)
⊕ The to_path parameter must be empty.
EXAMPLES
if (rename(existing_file, new_file) == -1)
perror("Rename failed");
RETURN VALUES
Upon successful completion, rename() returns a value of 0. If rename()
fails, a value of -1 is returned, and the global variable errno is set to
indicate the error.
ERRORS
The rename function fails and the file or directory name remains unchanged
if one or more of the following are true:
[ENOTDIR]
A component of either path prefix is not a directory; or from_path
names a directory and to_path names a non-directory.
[EISDIR]
The to_path parameter names a directory and the from_path parameter
names a nondirectory.
[ENOENT]
A component of either path does not exist or the file named by
from_path does not exist.
[EACCES]
A component of either path prefix denies search permission, or one
of the directories containing from_path or to_path denies write
permission. This error also occurs if write permission is denied
for a directory pointed to by the from_path or to_path parameters.
[EXDEV]
The link named by to_path and the file named by from_path are on
different file systems.
[EINVAL]
The from_path parameter is an ancestor of to_path.
[EROFS]
The requested operation requires writing in a directory on a read-
only file system.
[EEXIST]
The to_path parameter is an existing non-empty directory.
2 Intergraph Corporation - 2/94
rename(2) CLIX rename(2)
[ENOSPC]
The directory that would contain to_path cannot be extended.
[ENAMETOOLONG]
The length of the from_path or to_path argument exceeds PATH_MAX,
or a pathname component is longer that NAME_MAX while
_POSIX_NO_TRUNC is in effect.
[EFAULT]
Either from_path or to_path points outside the allocated address
space of the process.
[EMLINK]
The maximum number of links to a file would be exceeded.
RELATED INFORMATION
Commands: chmod(8), mkdir(1), mv(1), mvdir(8)
Functions: chmod(2), link(2), mkdir(2), rmdir(2), unlink(2)
2/94 - Intergraph Corporation 3