CopyFile function (winbase.h) - Win32 apps (original) (raw)

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, andCopyFileEx can be canceled during the copy operation.

To perform this operation as a transacted operation, use theCopyFileTransacted function.

Syntax

BOOL CopyFile(
  [in] LPCTSTR lpExistingFileName,
  [in] LPCTSTR lpNewFileName,
  [in] BOOL    bFailIfExists
);

Parameters

[in] lpExistingFileName

The name of an existing 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.

If lpExistingFileName does not exist,CopyFile fails, andGetLastError returnsERROR_FILE_NOT_FOUND.

[in] lpNewFileName

The name of the new 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] bFailIfExists

If this parameter is TRUE and the new file specified by_lpNewFileName_ already exists, the function fails. If this parameter isFALSE 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, callGetLastError.

The security resource properties (ATTRIBUTE_SECURITY_INFORMATION) 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 resource properties for the existing file are not copied to the new file until Windows 8 and Windows Server 2012.

File attributes for the existing file are copied to the new file. For example, if an existing file has theFILE_ATTRIBUTE_READONLY file attribute, a copy created through a call toCopyFile will also have theFILE_ATTRIBUTE_READONLY file attribute. For more information, seeRetrieving 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_READONLYattribute 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 anERROR_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.

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Examples

For an example, seeRetrieving and Changing File Attributes.

Requirements

See also

CopyFileEx

CopyFileTransacted

CreateFile

File Attribute Constants

File Management Functions

MoveFile

Symbolic Links