C Programming/stdio.h/rename

From Wikibooks, open books for an open world
Jump to navigation Jump to search

rename is a function in the C programming language that renames a certain file.[1]

The prototype of the function is:

int rename(const char *oldname, const char *newname)

Zero is returned upon success. Other integers are returned upon failure and errno is set to an error code in this case.

The rename function is specified in the stdio.h library header file in C and the cstdio header in C++. It is specified in ANSI C.

In POSIX, rename will fail (with EXDEV) if the old and new names are on different mounted file systems.[2] If a call to rename succeeds it is guaranteed to have been atomic from the point of view of the current host (i.e., another program would only see the file with the old name or the file with the new name, not both or neither of them).

The Windows C library version of rename fails if the destination file already exists (POSIX would only fail if the user does not have permission to remove the destination file). Although the underlying WIN32 call has (since Win2K) had an option to replicate the POSIX atomic behavior, the library has never been fixed to use this.

References[edit | edit source]

  1. ISO/IEC 9899:1999 specification (PDF). p. 268, § 7.19.4.2.
  2. rename: rename a file – System Interfaces Reference, The Single UNIX® Specification, Issue 7 from The Open Group

External links[edit | edit source]