The rename() function has the following prototype:

int rename(char const *src_file, char const *dest_file);

If the file referenced by dest_file exists prior to calling rename(), the behavior is implementation-defined. On POSIX systems, the destination file is removed. On Windows systems, the rename() fails.

This creates issues when trying to write portable code, or when trying to implement alternative behavior.

Preserve Existing Destination File

If the desired behavior is to ensure that the destination file is not erased or overwritten, POSIX programmers must implement additional safeguards.

Non-Compliant Code Example (POSIX)

This code example is non-compliant because any existing destination file is removed by rename().

char const *src_file = /* ... */;
char const *dest_file = /* ... */;
if (rename(src_file, dest_file) != 0) {
  /* Handle Error */
}

Compliant Solution (POSIX)

If the programmer's intent is to not remove an existing destination file, the POSIX access() function can be used to check for the existence of a file [[Open Group 04]]. This compliant solution only renames the source file if the destination file does not exist.

char const *src_file = /* ... */;
char const *dest_file = /* ... */;

if (access(dest_file, F_OK) != 0) {
  if (rename(src_file, dest_file) != 0) {
    /* Handle error condition */
  }
} 
else {
  /* Handle file-exists condition */
}

This code contains an unavoidable race condition between the call to access() and the call to rename() and can consequently only be safely executed within a secure directory (see FIO15-A. Ensure that file operations are performed in a secure directory).

On file systems where the program does not have sufficient permissions in the directory to view the file, access() may return -1 even when the file exists. In such cases, rename() will also fail because the program lacks adequate permissions to perform the operation.

Compliant Solution (Windows)

On Windows, the rename() function fails if [[MSDN]]:

File or directory specified by newname already exists or could not be created (invalid path)

Consequently, it is unnecessary to explicitly check for the existence of the destination file before calling rename().

char const *src_file = /* ... */;
char const *dest_file = /* ... */;
if (rename(src_file, dest_file) != 0) {
  /* Handle Error */
}

Remove Existing Destination File

If the desired behavior is to ensure that the destination file is erased by the rename() operation, Windows programmers must write additional code.

Non-Compliant Code Example (Windows)

If the intent of the programmer is to remove the file referenced by dest_file if it exists prior to calling rename(), this code example is non-compliant on Windows platforms because rename() will fail.

char const *src_file = /* ... */;
char const *dest_file = /* ... */;
if (rename(src_file, dest_file) != 0) {
  /* Handle Error */
}

Compliant Solution (Windows)

On Windows systems, it is necessary to explicitly remove the destination file before calling rename(), if you want the file to be overwritten and the rename() operation to succeed.

char const *src_file = /* ... */;
char const *dest_file = /* ... */;

if (_access_s(dest_file,0) == 0) {
  if (remove(dest_file) != 0) {
    /* Handle error condition */
  }
}

if (rename(src_file, dest_file) != 0) {
  /* Handle error condition */
}

This code contains unavoidable race conditions between the calls to _access_s(), remove() and rename() and can consequently only be safely executed within a secure directory (see FIO15-A. Ensure that file operations are performed in a secure directory).

Compliant Solution (POSIX)

On POSIX systems, if the destination file exists prior to calling rename(), the file is automatically removed.

char const *src_file = /* ... */;
char const *dest_file = /* ... */;
if (rename(src_file, dest_file) != 0) {
  /* Handle error condition */
}

Portable Behavior

A programmer that wants an application to behave the same on any C99 implementation must first determine what behavior to implement.

Compliant Solution (Remove Existing Destination File)

This compliant solution ensures that any destination file is portably removed.

char const *src_file = /* ... */;
char const *dest_file = /* ... */;

(void)remove(dest_file);

if (rename(src_file, dest_file) != 0) {
  /* Handle error condition */
}

This code contains an unavoidable race condition between the call to remove() and the call to rename() and consequently can only be safely executed within a secure directory (see FIO15-A. Ensure that file operations are performed in a secure directory).

The return value of remove() is deliberately not checked, because it is expected to fail in the case where the file does not exist. If the file exists but cannot be removed, the rename() call will also fail and the error will be detected at that point. This is a valid exception (EXP12-EX1) to recommendation EXP12-C. Do not ignore values returned by functions.

Compliant Solution (Preserve Existing Destination File)

This compliant solution only renames the source file if the destination file does not exist.

char const *src_file = /* ... */;
char const *dest_file = /* ... */;

if (!file_exists(dest_file)) {
  if (rename(src_file, dest_file) != 0) {
    /* Handle error condition */
  }
} 
else {
  /* Handle file-exists condition */
}

This code contains an unavoidable race condition between the call to file_exists() and the call to rename() and can consequently only be safely executed within a secure directory (see FIO15-A. Ensure that file operations are performed in a secure directory).

The file_exists() function is provided by the application, and is not shown here as it must be implemented differently on different platforms. (On POSIX systems it would use access(), on Windows _access_s(), and on other platforms whatever function is available to test file existence.)

Risk Assessment

Calling rename() has implementation-defined behavior when the new file name refers to an existing file. Incorrect use of rename() can result in a file being unexpectedly overwritten or other unexpected behavior.

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

References

[[ISO/IEC 9899:1999]] Section 7.9.4.2, "The rename function"
[[MSDN]] rename()
[[Open Group 04]] access()

      09. Input Output (FIO)       FIO11-A. Take care when specifying the mode parameter of fopen()