MoveFile function (Windows)

Switch View :

Classic

Lightweight

ScriptFree

Site Feedback

MoveFile function

Applies to: desktop apps only

Moves an existing file or a directory, including its children.

To specify how to move the file, use the MoveFileEx or MoveFileWithProgress function.

To perform this operation as a transacted operation, use the MoveFileTransacted function.

Syntax

BOOL WINAPI MoveFile(
  __in  LPCTSTR lpExistingFileName,
  __in  LPCTSTR lpNewFileName
);

Parameters

lpExistingFileName [in]

The current name of the file or directory on the local computer.

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.

lpNewFileName [in]

The new name for the file or directory. The new name must not already exist. A new file may be on a different file system or drive. A new directory must be on the same drive.

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.

Remarks

The MoveFile function will move (rename) either a file or a directory (including its children) either in the same directory or across directories. The one caveat is that the MoveFile function will fail on directory moves when the destination is on a different volume.

If a file is moved across volumes, MoveFile does not move the security descriptor with the file. The file will be assigned the default security descriptor in the destination directory.

The MoveFile function coordinates its operation with the link tracking service, so link sources can be tracked as they are moved.

Requirements

Minimum supported client	Windows XP
Minimum supported server	Windows Server 2003
Header	WinBase.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll
Unicode and ANSI names	MoveFileW (Unicode) and MoveFileA (ANSI)

In the following scenario a MoveFile operation fails with an incorrect error code:*) Create file Foo.log and keep it open*) Create at least one child process with inherited file handles by using CreateProcess *) Close file Foo.log and try to move it to a valid location by using MoveFile*) This operation fails (at least on Windows 7 x64 and Visual Studio 2010 SP1) with error code 183 (Cannot create a file when that file already exists.) even the target file name does not exists and has never existed before.As soon as the child process is ended the move operation is successful. An other solution is, forbid explicit the handle inheritance for file Foo.log if a general inheritance of handles is needed (because of using pipes between child and parent process eg). This could either be done by using the CreateFile method and set an appropriate security attribute or by using the following: FILE *stream = fopen("Foo.log", _eolTranslation ? "at" : "ab"); SetHandleInformation((HANDLE)_get_osfhandle(_fileno(stream)), HANDLE_FLAG_INHERIT, 0);

dmex

C# syntax

[DllImport("kernel32", CharSet=CharSet.Auto, SetLastError=true)]
internal static extern int MoveFile([In, MarshalAs(UnmanagedType.LPTStr)] string lpExistingFileName, [In, MarshalAs(UnmanagedType.LPTStr)] string lpNewFileName);