gtpc2m5vC/C++ Language Support User's Guide

rename-Rename a File

This function renames a file.

TPF deviation from POSIX

The TPF system does not support the ctime (change time) time stamp.

Format

#include <stdio.h>
int rename(const char *oldname, const char *newname);

oldname
The name by which the file is currently known.

newname
The name by which the file will now be known.

This function 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.

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. Therefore, 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. The rename function does not affect any file or directory named by the contents of the symbolic link.

For the rename function to be successful, the process needs write permission on the directory containing oldname and the directory containing newname. If oldname and newname are directories, the rename function 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 the rename function is successful, it updates the modification times for the parent directories of oldname and newname.

Normal Return

The rename function returns a value of 0 if it is successful.

Error Return

If not successful, the rename function returns a nonzero value and sets errno to one of the following:

EACCES
An error occurred for one of the following reasons:

EBUSY
oldname and newname specify directories, but one of them is the root directory (/).

EINVAL
This error occurs for one of the following reasons:

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 found while resolving the oldname or newname argument is greater than POSIX_SYMLOOP.

ENAMETOOLONG
pathname is longer than PATH_MAX characters or some component of pathname is longer than NAME_MAX characters. For symbolic links, the length of the path name string substituted for a symbolic link exceeds PATH_MAX.

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 pathname 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.

ETPFNPIPWSYS
In a loosely coupled environment, there was an attempt to access a FIFO special file (or named pipe) from a processor other than the processor on which the file was created.

Programming Considerations

 The TPF system does not support creating, updating, or deleting files in 1052 or UTIL state. Special files may or may not be writable in 1052 or UTIL state depending on the device driver implementation. 

Because the rename function requires an update to at least one directory file, files cannot be renamed in 1052 or UTIL state.

Examples

The following 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" );
}

Related Information

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.