# Function Reference

# _WinAPI_ReplaceFile

Replaces one file with another file, and creates a backup copy of the original file

#include <WinAPIFiles.au3>
_WinAPI_ReplaceFile ( $sReplacedFile, $sReplacementFile [, $sBackupFile = '' [, $iFlags = 0]] )

## Parameters

$sReplacedFile | The name of the file to be replaced.
$sReplacementFile | The name of the file that will replace the $sReplacedFile file.
$sBackupFile | [optional] The name of the file that will serve as a backup copy of the $sReplacedFile file. If this parameter is empty string, no backup file is created.
$iFlags | [optional] The replacement options. This parameter can be one or more of the following values. $REPLACEFILE_WRITE_THROUGH $REPLACEFILE_IGNORE_MERGE_ERRORS $REPLACEFILE_IGNORE_ACL_ERRORS

## Return Value

Success: | True.
Failure: | False (see remarks).

## Remarks

If this function fails, call _WinAPI_GetLastError() function to get extended error information. The following
are possible error codes for this function.
ERROR_UNABLE_TO_MOVE_REPLACEMENT (1176)
The replacement file could not be renamed. If $sBackupFile 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)
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 the name specified by $sReplacedFile.
ERROR_UNABLE_TO_REMOVE_REPLACED (1175)
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 (87), 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.

## See Also

Search ReplaceFile in MSDN Library.

## Example

    #include <WinAPIError.au3>
    #include <WinAPIFiles.au3>

    Opt('TrayAutoPause', 0)

    FileDelete(@TempDir & '\Test*.tmp')

    Local $sFile = @TempDir & '\Test.tmp'
    Local $hFile = FileOpen($sFile, 2)
    For $i = 1 To 10000
        FileWriteLine($hFile, "                                                     ")
    Next
    FileClose($hFile)

    Local $sNewFile = @TempDir & '\TestNew.tmp'
    FileCopy($sFile, $sNewFile)
    If Not _WinAPI_ReplaceFile($sNewFile, $sFile) Then
        _WinAPI_ShowLastError('Error replacing no backup : ' & $sFile)
    EndIf

    FileCopy($sNewFile, $sFile, 1)
    If Not _WinAPI_ReplaceFile($sNewFile, $sFile, @TempDir & '\TestBackup.tmp') Then
        _WinAPI_ShowLastError('Error replacing : ' & $sFile)
    EndIf

    FileDelete(@TempDir & '\Test*.tmp')