Expand Minimize

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.

Syntax


BOOL WINAPI ReplaceFile(
  _In_        LPCTSTR lpReplacedFileName,
  _In_        LPCTSTR lpReplacementFileName,
  _In_opt_    LPCTSTR lpBackupFileName,
  _In_        DWORD dwReplaceFlags,
  _Reserved_  LPVOID lpExclude,
  _Reserved_  LPVOID lpReserved
);

Parameters

lpReplacedFileName [in]

The name of the file to be replaced.

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

The caller must have write access to the file to be replaced. For more information, see File Security and Access Rights.

lpReplacementFileName [in]

The name of the file that will replace the lpReplacedFileName file.

The function attempts to open this file with the SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE, and WRITE_DAC access rights so that it can preserve all attributes and ACLs. If this fails, the function attempts to open the file with the SYNCHRONIZE, GENERIC_READ, DELETE, and WRITE_DAC access rights. No sharing mode is specified.

lpBackupFileName [in, optional]

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]

The replacement options. This parameter can be one or more of the following values.

ValueMeaning
REPLACEFILE_WRITE_THROUGH
0x00000001

This value is not supported.

REPLACEFILE_IGNORE_MERGE_ERRORS
0x00000002

Ignores errors that occur while merging information (such as attributes and ACLs) from the replaced file to the replacement file. Therefore, if you specify this flag and do not have WRITE_DAC access, the function succeeds but the ACLs are not preserved.

REPLACEFILE_IGNORE_ACL_ERRORS
0x00000004

Ignores errors that occur while merging ACL information from the replaced file to the replacement file. Therefore, if you specify this flag and do not have WRITE_DAC access, the function succeeds but the ACLs are not preserved. To compile an application that uses this value, define the _WIN32_WINNT macro as 0x0600 or later.

Windows Server 2003 and Windows XP:  This value is not supported.

 

lpExclude

Reserved for future use.

lpReserved

Reserved for future use.

Return value

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. The following are possible error codes for this function.

Return code/valueDescription
ERROR_UNABLE_TO_MOVE_REPLACEMENT
1176 (0x498)

The replacement file could not be renamed. If lpBackupFileName was specified, the replaced and replacement files retain their original file names. Otherwise, the replaced file no longer exists and the replacement file exists under its original name.

ERROR_UNABLE_TO_MOVE_REPLACEMENT_2
1177 (0x499)

The replacement file could not be moved. The replacement file still exists under its original name; however, it has inherited the file streams and attributes from the file it is replacing. The file to be replaced still exists with a different name. If lpBackupFileName is specified, it will be the name of the replaced file.

ERROR_UNABLE_TO_REMOVE_REPLACED
1175 (0x497)

The replaced file could not be deleted. The replaced and replacement files retain their original file names.

 

If any other error is returned, such as ERROR_INVALID_PARAMETER, the replaced and replacement files will retain their original file names. In this scenario, a backup file does not exist and it is not guaranteed that the replacement file will have inherited all of the attributes and streams of the replaced file.

Remarks

The ReplaceFile function combines several steps within 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
  • Short file name
  • Object identifier
  • DACLs
  • Security resource attributes
  • 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.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:  Security resource attributes (ATTRIBUTE_SECURITY_INFORMATION) for the original file are not preserved until Windows 8 and Windows Server 2012.

Note  

If the replacement file is protected using Selective Wipe, then the replaced file will be protected by the enterprise id of the replacement file.

The resulting file has the same file ID as the replacement file.

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

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

WinBase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

ReplaceFileW (Unicode) and ReplaceFileA (ANSI)

See also

CopyFile
CopyFileEx
File Management Functions
MoveFile
MoveFileEx
MoveFileWithProgress

 

 

Community Additions

ADD
Show:
© 2014 Microsoft