HP 3000 Manuals HP 3000 Manuals
rename
Renames an existing file.
Syntax
#include <stdio.h>
int rename(const char *old, const char new);
Parameters
old The pathname of the file to be renamed.
new The new pathname of the file.
Return Values
Upon successful completion, a value of zero will be returned, Otherwise,
a value of -1 will be returned and errno will be set to indicate the
error. If -1 is returned, neither the filenamed by old nor the filenamed
by new, if either exists, will be changed by this function call.
Description
The rename() function changes 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 the old argument and the new argument both refer to links to the same
existing file, The rename() function will return successfully and perform
no other action.
The old and new arguments must be of the same type of file or directory.
If the link named by the new argument exists, it will be removed and old
renamed to new. 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 will not point to the pathname of a file that is not a
directory. If the directory named by the new argument exists, it will be
removed and old renamed to new. Thus, if new names an existing
directory, it will be required to be an empty directory.
The new pathname should not contain a path prefix that names old.
If the link named by the new argument exists and the link count of the
file becomes zero when it is removed and no process has the file open,
the space occupied by the file will be freed and the file will no longer
be accesable. If one or more processes have the file open when the last
link is removed, the link will be removed before rename() returns, but
the removal of the file contents will be postponed until all references
to the file have been closed.
Upon successful completion, the rename() function will mark for update
the st_ctime and st_mtime fields of the parent directory of each file.
Errors
If an error occurs, errno is set to one of the following values:
EINVAL CAUSE More than one of the following three open flags were
specified in oflag: O_WRONLY, O_RDONLY, and O_RDWR.
ACTION Specify only one of the open flags in oflag.
EISDIR CAUSE The pathname specifies a directory to be opened.
ACTION Use opendir() to open a directory file.
EMFILE CAUSE The number of open files and directories would exceed
{OPEN_MAX}, the limit of opened files per process.
ACTION Reduce the number of files and directories opened by
the calling process.
Table 4-0. (cont.)
ENAMETOOLONG CAUSE One of the following:
* The length of the pathname exceeds the
{PATH_MAX} limit (defined in the file
<limits.h>).
* A component of the pathname is longer than
{NAME_MAX} (defined in <limits.h>), and
{_POSIX_NO_TRUNC} is in effect for that
directory.
ACTION Make sure that both the component's length and the
full pathname length do not exceed the {NAME_MAX} or
{PATH_MAX} limits.
ENOENT CAUSE The O_CREAT option is not set, and the named file
does not exist; or the O_CREAT option is set, and the
pathname does not exist; or pathname points to an
empty string.
ACTION Specify a valid pathname.
ENOSPC CAUSE Creation of the file would exceed the disk space
limits imposed by the MPE/iX accounting facility, or
there is not enough free disk space to create the
file.
ACTION Extend accounting limits for the directory in which
the file is located, or free up disk space.
ENOTDIR CAUSE A component of the pathname is not a directory.
ACTION Specify a valid pathname.
ESYSERR CAUSE An operating system error has occurred that does not
map directly to any of the above errors.
ACTION Examine the MPE/iX error stack for the type of system
error.
See Also
close(), creat(), dup(), execl(), execv(), <fcntl.h>, lseek(), read(),
<signal.h>, fstat(), stat(), <stat.h>, write(), umask(), POSIX.1 (Section
5.3.1)