rename()

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:

EACCESS

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

See also:

errno