Rename a file
Synopsis:
#include <stdio.h>
int rename( const char* old,
const char* new );
Arguments:
- old
- The path to the file that you want to rename.
If the path doesn't include a directory, rename() looks for the file in the
current working directory.
- new
- The new name for the file.
If the path doesn't include a directory, rename() creates
the file in the current working directory.
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Description:
The rename() function changes the name of the file indicated by
old to the name given in new.
If new identifies an existing file or empty directory,
rename() overwrites it.
Returns:
- 0
- Success.
- Nonzero
- An error occurred (errno is set ).
Errors:
- EACCES
- The calling program doesn't have permission to search one of the
components of either path prefix, or one of the directories
containing old or new denies write permission.
- EBUSY
- The directory named by old or new can't be
renamed because another process is using it.
- EEXIST
- The file specified by new is a directory that contains files.
- EINVAL
- The new directory pathname contains the old directory.
- EISDIR
- The file specified by new is a directory and old is a file.
- ELOOP
- Too many levels of symbolic links.
- EMLINK
- The file named by old is a directory, and the link count
of the parent directory of new would exceed LINK_MAX.
- ENAMETOOLONG
- The length of old or new exceeds PATH_MAX.
- ENOENT
- The old file doesn't exist, or old or new
is an empty string.
- ENOSPC
- The directory that would contain new can't be extended.
- ENOSYS
- The rename() function isn't implemented for the filesystem specified
in old or new.
- ENOTDIR
- A component of either path prefix isn't a directory, or
old is a directory and new isn't.
- ENOTEMPTY
- The file specified by new is a directory that contains files.
- EROFS
- The rename() would affect files on a read-only filesystem.
- EXDEV
- The files or directories named by old and new
are on different filesystems.
Examples:
#include <stdio.h>
#include <stdlib.h>
int main( void )
{
if( rename( "old.dat", "new.dat" ) ) {
puts( "Error renaming old.dat to new.dat." );
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
Classification:
ANSI,
POSIX 1003.1
| Safety: |
|
|---|
| Cancellation point |
Yes |
| Interrupt handler |
No |
| Signal handler |
Yes |
| Thread |
Yes |