C rename() function

Last update on September 10 2022 12:48:24 (UTC/GMT +8 hours)

C library function - rename()

The rename() function is used to change the name of a file.

If the format for both new name and old name is home/file(member), then the file cannot change. If the file name changes, rename will not work. For example, the following is not valid: home/file1(member1) home/file2(member1).

The file formats that can be used to satisfy the new name depend on the format of the old name. The following table shows the valid file formats that can be used to specify the old file name and the corresponding valid file formats for the new name.

Old Name	New Name
home/file(member)	home/file(member), home/file, file, file(member)
home/file	home/file, file
file	home/file, file
file(member)	home/file(member), home/file, file, file(member)

Syntax:

int rename(const char *old_filename, const char *new_filename)

rename() Parameters:

Name	Description	Required /Optional
old_filename	The old argument points to the pathname of the file to be renamed.	Required
new_filename	The new argument points to the new pathname of the file.	Required

Return value from rename()

Upon successful completion, the rename() function shall return 0.
Otherwise, it shall return -1, errno shall be set to indicate the error, and neither the file named by old nor the file named by new shall be changed or created.

Example: rename() function

The following example shows the usage of rename() function.

#include <stdio.h>

int main () {
   int status;
   char old_file_name[] = "test.txt";
   char new_file_name[] = "new_test.txt";
   
   status = rename(old_file_name, new_file_name);
	
   if(status == 0) {
      printf("File renamed successfully!");
   } else {
      printf("Error: unable to rename the file!");
   }
   
   return(0);
}

Output:

File renamed successfully

Errors: The value of error number can be set to:

Value	Meaning
EACCES	A component of either path prefix denies search permission; or one of the directories containing old or new denies write permissions; or, write permission is required and is denied for a directory pointed to by the old or new arguments.
EBUSY	The directory named by old or new is currently in use by the system or another process, and the implementation considers this an error.
EEXIST	The link named by new is a directory that is not an empty directory.
EINVAL	The old pathname names an ancestor directory of the new pathname, or either pathname argument contains a final component that is dot or dot-dot.
EIO	A physical I/O error has occurred.
EISDIR	The new argument points to a directory and the old argument points to a file that is not a directory.
ELOOP	A loop exists in symbolic links encountered during resolution of the path argument.
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 a component of a pathname is longer than {NAME_MAX}.

C Programming Code Editor:

Previous C Programming: C rename()
Next C Programming: C rewind()