CopyFile function
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Copies an existing file to a new file.
The CopyFileEx function provides two additional capabilities. CopyFileEx can call a specified callback function each time a portion of the copy operation is completed, and CopyFileEx can be canceled during the copy operation.
To perform this operation as a transacted operation, use the CopyFileTransacted function.
Syntax
BOOL WINAPI CopyFile( _In_ LPCTSTR lpExistingFileName, _In_ LPCTSTR lpNewFileName, _In_ BOOL bFailIfExists );
Parameters
- lpExistingFileName [in]
-
The name of an existing 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.
If lpExistingFileName does not exist, CopyFile fails, and GetLastError returns ERROR_FILE_NOT_FOUND.
- lpNewFileName [in]
-
The name of the new 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.
- bFailIfExists [in]
-
If this parameter is TRUE and the new file specified by lpNewFileName already exists, the function fails. If this parameter is FALSE and the new file already exists, the function overwrites the existing file and succeeds.
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
Security attributes for the existing file are copied to the new file.
Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP: Security attributes for the existing file are not copied to the new file until Windows 8 Consumer Preview and Windows Server 8 Beta. To copy security attributes, use the SHFileOperation function.
File attributes for the existing file are copied to the new file. For example, if an existing file has the FILE_ATTRIBUTE_READONLY file attribute, a copy created through a call to CopyFile will also have the FILE_ATTRIBUTE_READONLY file attribute. For more information, see Retrieving and Changing File Attributes.
This function fails with ERROR_ACCESS_DENIED if the destination file already exists and has the FILE_ATTRIBUTE_HIDDEN or FILE_ATTRIBUTE_READONLY attribute set.
When CopyFile is used to copy an encrypted file, it attempts to encrypt the destination file with the keys used in the encryption of the source file. If this cannot be done, this function attempts to encrypt the destination file with default keys. If neither of these methods can be done, CopyFile fails with an ERROR_ENCRYPTION_FAILED error code.
Symbolic link behavior—If the source file is a symbolic link, the actual file copied is the target of the symbolic link.
If the destination file already exists and is a symbolic link, the target of the symbolic link is overwritten by the source file.
Examples
For an example, see Retrieving and Changing File Attributes.
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | CopyFileW (Unicode) and CopyFileA (ANSI) |
See also
- CopyFileEx
- CopyFileTransacted
- CreateFile
- File Attribute Constants
- File Management Functions
- MoveFile
- Symbolic Links
Build date: 4/17/2012
- 8/5/2011
- David I McIntosh
- 5/11/2011
- DrEvilD
- 4/29/2011
- Leandre Gohy
- 4/29/2011
- Leandre Gohy
This article should document semantics with respect to file creation/modification/access times.
Creation time: if the target file already exists, its' creation time is preserved, otherwise it is set to the current system time.
Last Modification time: always copied from modification time of the source file.
Last Access time: always set to the current system time.
- 7/1/2009
- VC123456
[DllImport("kernel32.dll", CharSet=CharSet.Auto, SetLastError=true)]
internal static extern bool CopyFile(string src, string dst, bool failIfExists);
