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.
In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see Naming a File.
Tip Starting with Windows 10, version 1607, for the unicode version of this function (ReplaceFileW), you can opt-in to remove the MAX_PATH limitation without prepending "\\?\". See the "Maximum Path Length Limitation" section of Naming Files, Paths, and Namespaces for details.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.
In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see Naming a File.
Tip Starting with Windows 10, version 1607, for the unicode version of this function (ReplaceFileW), you can opt-in to remove the MAX_PATH limitation without prepending "\\?\". See the "Maximum Path Length Limitation" section of Naming Files, Paths, and Namespaces for details.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. See the Remarks section for implementation details on the backup file.
In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see Naming a File.
Tip Starting with Windows 10, version 1607, for the unicode version of this function (ReplaceFileW), you can opt-in to remove the MAX_PATH limitation without prepending "\\?\". See the "Maximum Path Length Limitation" section of Naming Files, Paths, and Namespaces for details. - dwReplaceFlags [in]
-
The replacement options. This parameter can be one or more of the following values.
- 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/value | Description |
|---|---|
|
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. |
|
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. |
|
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.
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 | Windows Store apps] |
|---|---|
|
Minimum supported server |
Windows Server 2003 [desktop apps | Windows Store apps] |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names |
ReplaceFileW (Unicode) and ReplaceFileA (ANSI) |
See also