rename() Function

The rename() function in C stdio.h changes the name of a file or directory, or moves it to a new location if a different path is specified. This operation is performed directly on the file without using any streams, and its behavior may vary depending on the system, such as whether it overrides an existing file with the new name.

Syntax of rename()

</>
Copy
int rename(const char *oldname, const char *newname);

Parameters

ParameterDescription
oldnameA C string containing the name (and optionally the path) of an existing file to be renamed or moved.
newnameA C string containing the new name (and optionally the path) for the file.

It is worth noting that if oldname and newname specify different paths, and if the system supports it, the file will be moved to the new location. In addition, if a file with the name specified by newname already exists, the function may either fail or override the file, based on the system and library implementation. Proper file access rights are required to perform this operation.

Return Value

If the file is successfully renamed, the function returns 0. On failure, a nonzero value is returned, and in most implementations, the errno variable is set to indicate the specific error.

Examples for rename()

Example 1: Renaming a File in the Same Directory

This example demonstrates how to rename a file within the same directory.

Program

</>
Copy
#include <stdio.h>

int main() {
    /* Attempt to rename "oldfile.txt" to "newfile.txt" in the same directory */
    if (rename("oldfile.txt", "newfile.txt") == 0) {
        printf("File renamed successfully.\n");
    } else {
        printf("Error renaming file.\n");
    }
    return 0;
}

Explanation:

  1. The program attempts to rename the file “oldfile.txt” to “newfile.txt”.
  2. The rename() function is called and its return value is checked.
  3. If the return value is 0, the renaming was successful and a success message is printed.
  4. If the function returns a nonzero value, an error message is printed.

Program Output:

File renamed successfully.

Example 2: Renaming and Moving a File to a Different Directory

This example shows how to rename a file and simultaneously move it to a different directory, assuming the system supports moving files with the rename() function.

Program

</>
Copy
#include <stdio.h>

int main() {
    /* Rename and move the file from the current directory to "backup/newfile.txt" */
    if (rename("oldfile.txt", "backup/newfile.txt") == 0) {
        printf("File moved and renamed successfully.\n");
    } else {
        printf("Error moving and renaming file.\n");
    }
    return 0;
}

Explanation:

  1. The program attempts to move and rename “oldfile.txt” to “backup/newfile.txt”.
  2. The rename() function is invoked with the new path and name.
  3. If the function returns 0, it indicates that the file has been successfully moved and renamed.
  4. If a nonzero value is returned, an error occurred during the operation, and an error message is printed.

Program Output:

File moved and renamed successfully.

Example 3: Handling Errors When Renaming a Non-existent File

This example demonstrates error handling when attempting to rename a file that does not exist.

Program

</>
Copy
#include <stdio.h>

int main() {
    /* Attempt to rename a non-existent file "nofile.txt" */
    if (rename("nofile.txt", "newname.txt") == 0) {
        printf("File renamed successfully.\n");
    } else {
        printf("Error renaming file: file does not exist.\n");
    }
    return 0;
}

Explanation:

  1. The program tries to rename “nofile.txt” to “newname.txt”.
  2. Since “nofile.txt” does not exist, the rename() function returns a nonzero value.
  3. The program then prints an error message indicating that the file does not exist.

Program Output:

Error renaming file: file does not exist.