ReplaceFile

The ReplaceFile function replaces one file with another file, with the option of creating a backup copy of the original file. The replacement file assumes the name of the replaced file and its identity.

BOOL ReplaceFile(
  LPCTSTR lpReplacedFileName,    // file name
  LPCTSTR lpReplacementFileName, // replacement file 
  LPCTSTR lpBackupFileName,      // optional backup file
  DWORD dwReplaceFlags,          // replace options
  LPVOID lpExclude,              // reserved
  LPVOID lpReserved              // reserved
); 

Parameters

lpReplacedFileName

[in] Pointer to a null-terminated string that specifies the name of the file that will be replaced by the lpReplacementFileName file.

This file is opened with the GENERIC_READ, DELETE, and SYNCHRONIZE access rights. The sharing mode is FILE_SHARE_READ | FILE_SHARED_WRITE | FILE_SHARE_DELETE.

The caller must have write access to the file to be replaced.

lpReplacementFileName

[in] Pointer to a null-terminated string that specifies the name of the file that will replace the lpReplacedFileName file.

The function attemps to open this file with the SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE, and WRITE_DAC access rights. If this fails, the function attemps to open the file with the SYNCHRONIZE, GENERIC_READ, DELETE, and WRITE_DAC access rights. No sharing mode is specified.

lpBackupFileName

[in] Pointer to a null-terminated string that specifies the name of the file that will serve as a backup copy of the lpReplacedFileName file. If this parameter is NULL, no backup file is created.

dwReplaceFlags

[in] Specifies how the file is to be replaced. This parameter can be one or more of the following values.

Value	Meaning
REPLACEFILE_WRITE_THROUGH	Guarantees that information copied from the replaced file is flushed to disk before the function returns.
REPLACEFILE_IGNORE_MERGE_ERRORS	Ignores errors that occur while merging information from the replaced file to the replacement file.

lpExclude

Reserved for future use.

lpReserved

Reserved for future use.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes that are specific to this function.

If any other error is returned, such as ERROR_INVALID_PARAMETER, the replaced and replacement files will retain their original file names.

Remarks

The ReplaceFile function combines several of steps into a single function. An application can call ReplaceFile instead of calling separate functions to save the data to a new file, rename the original file using a temporary name, rename the new file to have the same name as the original file, and delete the original file. Another advantage is that ReplaceFile not only copies the new file data, but also preserves the following attributes of the original file:

• creation time
• last write time
• short file name
• object identifier
• DACLs
• encryption
• compression
• named streams not already in the replacement file

For example, if the replacement file is encrypted, but the replaced file is not encrypted, the resulting file is not encrypted.

The backup file, replaced file, and replacement file must all reside on the same volume.

To delete or rename a file, you must have either delete permission on the file or delete child permission in the parent directory. If you set up a directory with all access except delete and delete child and the DACLs of new files are inherited, then you should be able to create a file without being able to delete it. However, you can then create a file, and you will get all the access you request on the handle returned to you at the time you create the file. If you requested delete permission at the time you created the file, you could delete or rename the file with that handle but not with any other.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

File I/O Overview, File I/O Functions, CopyFile, CopyFileEx, MoveFile, MoveFileEx, MoveFileWithProgress