rename()

Updated: April 19, 2023

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 underlying the path 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