C++

Reference

<cstdio> (stdio.h)

function
<cstdio>

rename

int rename ( const char * oldname, const char * newname );
Rename file
Changes the name of the file or directory specified by oldname to newname.

This is an operation performed directly on a file; No streams are involved in the operation.

If oldname and newname specify different paths and this is supported by the system, the file is moved to the new location.

If newname names an existing file, the function may either fail or override the existing file, depending on the specific system and library implementation.

Proper file access shall be available.

Parameters

oldname
C string containing the name of an existing file to be renamed and/or moved.
Its value shall follow the file name specifications of the running environment and can include a path (if supported by the system).
newname
C string containing the new name for the file.
Its value shall follow the file name specifications of the running environment and can include a path (if supported by the system).

Return value

If the file is successfully renamed, a zero value is returned.
On failure, a nonzero value is returned.
On most library implementations, the errno variable is also set to a system-specific error code on failure.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
/* rename example */
#include <stdio.h>

int main ()
{
  int result;
  char oldname[] ="oldname.txt";
  char newname[] ="newname.txt";
  result= rename( oldname , newname );
  if ( result == 0 )
    puts ( "File successfully renamed" );
  else
    perror( "Error renaming file" );
  return 0;
}

If the file oldname.txt could be successfully renamed to newname.txt the following message would be written to stdout:
File successfully renamed


Otherwise, a message similar to this will be written to stderr:
Error renaming file: Permission denied


See also

remove
Remove file (function)