w3resource

C rename() function

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()



Follow us on Facebook and Twitter for latest update.