gtpc2m5v | C/C++ Language Support User's Guide |
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);
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:
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.