rename() — Rename file

Standards

Standards / Extensions	C or C++	Dependencies
ISO C POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#include <stdio.h>

int rename(const char *oldname, const char *newname);

General description

Changes the name of the file, from the name pointed to by oldname to the name pointed to by newname.

The oldname pointer must point to the name of an existing file. The newname pointer must not specify the name of an existing file. You cannot rename an open file. In case of an error, the name of the file is not changed.

The rename() function renames memory files and DASD data sets. (Non-DASD data sets, such as tapes, are not supported.) It also renames individual members of PDSs (and PDSEs); it even renames files that simulate PDSs.

Special behavior for POSIX C: Memory files must be closed unless you are working under z/OS® UNIX services.

The interpretation of the file name passed to rename() depends on whether the program is running POSIX(ON) or POSIX(OFF).

You cannot rename an HFS file to an MVS™ data set name or rename an MVS data set to an HFS file name.

Both oldname and newname must be of the same type, that is, both directories or both files.

If newname already exists, it is removed before oldname is renamed to newname. Thus, if newname specifies the name of an existing directory, it must be an empty directory.

If the oldname argument points to a symbolic link, the symbolic link is renamed. If the newname argument points to a symbolic link, the link is removed and oldname is renamed to newname. rename() does not affect any file or directory named by the contents of the symbolic link.

For rename() to succeed, the process needs write permission on the directory containing oldname and the directory containing newname. If oldname and newname are directories, rename() also needs write permission on the directories themselves.

If oldname and newname both refer to the same file, rename() returns successfully and performs no other action.

When rename() is successful, it updates the change and modification times for the parent directories of oldname and newname.

Returned value

If successful, rename() returns 0.

If unsuccessful, rename() returns nonzero and sets errno to one of the following values:

Error Code

Description

EACCES

An error occurred for one of these reasons:

The process did not have search permission on some component of the old or new path name.
The process did not have write permission on the parent directory of the file or directory to be renamed.
oldname or newname were directories.
The process did not have write permission on oldname or newname.

EBUSY

oldname and newname specify directories, but one of them cannot be renamed because it is in use as a root or a mount point.

EINVAL

This error occurs for one of these reasons:

oldname is part of the path name prefix of newname.
oldname or newname refers to either . (dot) or .. (dot-dot).

EIO

A physical I/O error has occurred.

EISDIR

newname is a directory, but oldname is not a directory.

ELOOP

A loop exists in symbolic links. This error is issued if the number of symbolic links encountered during resolution of oldname or newname is greater than POSIX_SYMLOOP.

ENAMETOOLONG

pathname is longer than PATH_MAX characters, or some component of pathname is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the path name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using pathconf().

ENOENT

No file or directory named oldname was found, or either oldname or newname was not specified.

ENOSPC

The directory intended to contain newname cannot be extended.

ENOTDIR

A component of the path name prefix for oldname or newname is not a directory, or oldname is a directory and newname is a file that is not a directory.

ENOTEMPTY

newname specifies a directory, but the directory is not empty.

EPERM or EACCES

The S_ISVTX flag is set on the directory containing the file referred to by oldname and the caller is not the file owner, nor is the caller the directory owner, nor does the caller have appropriate privileges; or newname 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

Renaming would require writing on a read-only file system.

EXDEV

oldname and newname identify files or directories on different file systems. z/OS UNIX services do not support links between different files systems.

Example

CELEBR13

⁄* CELEBR13                                      

   This example takes two file names as input and uses rename() to change       
   the file name from the first name to the second name.                        

 *⁄                                                                             
#include <stdio.h>                                                              
                                                                                
int main(int argc, char ** argv )                                               
{                                                                               
  if ( argc != 3 )                                                              
    printf( "Usage: %s old_fn new_fn\n", argv[0] );                             
  else if ( rename( argv[1], argv[2] ) != 0 )                                   
    printf( "Could not rename file\n" );                                        
}