rename()

rename file 

Function

SYNOPSIS

#include <stdio.h>

#include <unistd.h>

int rename(const char *old, const char *new);

DESCRIPTION

The rename() function renames a file. Specifically, it changes the name of the old file to the name of the new file. If the old parameter and the new parameter refer to links to the same existing file, rename() returns successfully and performs no other action.

If old points to the path name of a file that is not a directory, new cannot point to the path name of a directory. If the link that new names exists, it is removed and old is renamed to new. If this happens, a link named new exists throughout the renaming operation and refers either to the file referred to by new or by old before the operation began. Write access permission is required for both the old and the new directories.

If old points to the path name of a directory, new cannot point to the path name of a file that is not a directory. If the directory that new named exists, it is removed and old is renamed to new. If this happens, a link named new exists throughout the renaming operation and refers either to the file referred to by new or by old before the operation began. Therefore, new can only name an existing directory that is empty.

The new path name cannot contain a path name prefix that names old. Write access permission is required for both the directories that contain old and new. If the old parameter points to the path name of a directory, write access permission may be required for the directory that old named and (if it exists) for the directory that new named.

If the link that new named exists and the link count of the file becomes zero when it is removed and no process has the file open, the file space is freed and the file is no longer accessible. If one or more processes have the file open when the last link is removed, the link is removed before rename() returns. However, removing the file contents is postponed until all references to the file have been closed.

When successfully completed, rename() marks the st_ctime and st_mtime fields of the parent directory of each file for update.

If new exists and is open in another process, it is unlinked.

PARAMETERS

old 

Points to the path name of the file to be renamed. The path name can be absolute or relative. If a relative path name is given, the file is searched from the current working directory.

new 

Points to the path name of the file. The path name can be absolute or relative. If a relative path name is given, the file is searched from the current working directory.

RETURN VALUES

If successful, rename() returns a value of zero. On failure, rename() does not change either the file named by old or the file named by new (if either exists). And on failure, it returns a value of -1 and sets errno to one of the following values:

EACCES 

A component of either path name 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 that old or new points to.

EBUSY 

The path named by old or new is currently in use by the system or another process.

EEXIST 

The link that new named is a directory that contains entries other than dot (.) and dot-dot (..).

EFAULT 

old or new is an invalid pointer.

EINVAL 

old is a parent directory of new, or an attempt is made to rename dot (.) or dot-dot (..).

EIO 

An I/O error occurred while making or updating a directory entry.

EISDIR 

new points to a directory, but old points to a file that is not a directory.

EMLINK 

The file that old named is a directory, and the link count of the parent directory of new exceeds LINK_MAX.

ENAMETOOLONG 

The length of the old or new parameter exceeds PATH_MAX, or the length of an old or a new component exceeds 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 

old names a directory and new names a regular file.

EXDEV 

The links that new and old named are on different file systems.

CONFORMANCE

POSIX.1 (1996), with exceptions

MULTITHREAD SAFETY LEVEL

Async-signal-safe.

PORTING ISSUES

Windows does not allow you to rename an open file on a network drive, or a file open for writing. Under this situation, rename() fails with errno set to EBUSY.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
link(), rmdir(), unlink()

PTC MKS Toolkit 10.4 Documentation Build 39.