ReplaceFileW function (winbase.h)
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 ReplaceFileW(
[in] LPCWSTR lpReplacedFileName,
[in] LPCWSTR lpReplacementFileName,
[in, optional] LPCWSTR lpBackupFileName,
[in] DWORD dwReplaceFlags,
LPVOID lpExclude,
LPVOID lpReserved
);
Parameters
[in] lpReplacedFileName
The name of the file to be replaced.
By default, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.
Tip
Starting with Windows 10, Version 1607, 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.
[in] lpReplacementFileName
The name of the file that will replace the lpReplacedFileName file.
By default, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.
Tip
Starting with Windows 10, Version 1607, 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.
[in, optional] lpBackupFileName
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.
By default, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.
Tip
Starting with Windows 10, Version 1607, 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.
[in] dwReplaceFlags
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
- Creation time
- Short file name
- Object identifier
- DACLs
- Security resource attributes
- Encryption
- Compression
- Named streams not already in the replacement file
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 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.
Note
The winbase.h header defines ReplaceFile as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | winbase.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |