CopyFile
The CopyFile function 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.
BOOL CopyFile(
LPCTSTR lpExistingFileName,
LPCTSTR lpNewFileName,
BOOL bFailIfExists
);
Parameters
lpExistingFileName
[in] Pointer to a null-terminated string that specifies 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.
Windows Me/98/95: This string must not exceed MAX_PATH characters.
lpNewFileName
[in] Pointer to a null-terminated string that specifies 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.
Windows Me/98/95: This string must not exceed MAX_PATH characters.
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 Values
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 not copied to the new file. 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, as in Windows 2000. If both of these methods cannot be done, CopyFile fails with an ERROR_ENCRYPTION_FAILED error code.
Windows 2000: When CopyFile is used to copy an encrypted file, the function attempts to encrypt the destination file with the default keys. No attempt is made to encrypt the destination file with the keys used in the encryption of the source file. If it cannot be encrypted, CopyFile completes the copy operation without encrypting the destination file.
Windows Me/98/95: CopyFileW is supported by the Microsoft Layer for
Unicode. To use this, you must add certain files to your application, as outlined in Microsoft Layer for
Unicode on Windows 95/98/Me Systems.
Example Code
For an example, see Searching for Files and Changing File Attributes.
Requirements
Client: Included in Windows XP, Windows 2000 Professional, Windows NT Workstation, Windows Me, Windows 98, and Windows 95.
Server: Included in Windows Server 2003, Windows 2000 Server, and Windows NT Server.
Unicode: Implemented as
Unicode and
ANSI versions. Note that
Unicode support on Windows Me/98/95 requires Microsoft Layer for
Unicode.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.
See Also
File Management Functions, CopyFileEx, CreateFile, MoveFile