CopyFile 함수(winbase.h)

아티클
03/06/2024

새 파일에 기존 파일을 복사합니다.

CopyFileEx 함수는 두 가지 추가 기능을 제공합니다. CopyFileEx 는 복사 작업의 일부가 완료될 때마다 지정된 콜백 함수를 호출할 수 있으며 복사 작업 중에 CopyFileEx 를 취소할 수 있습니다.

이 작업을 트랜잭션 작업으로 수행하려면 CopyFileTransacted 함수를 사용합니다.

구문

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

매개 변수

[in] lpExistingFileName

기존 파일의 이름입니다.

기본적으로 이름은 MAX_PATH 문자로 제한됩니다. 이 제한을 32,767자로 확장하려면 경로에 "\\?\"를 앞에 추가합니다. 자세한 내용은 파일 이름 지정, 경로 및 네임스페이스를 참조하세요.

팁

Windows 10 버전 1607부터 "\\?\"를 앞에 추가하지 않고 MAX_PATH 제한을 제거하도록 옵트인할 수 있습니다. 자세한 내용은 파일, 경로 및 네임스페이스의 "최대 경로 길이 제한" 섹션을 참조하세요.

lpExistingFileName이 없으면 CopyFile이 실패하고 GetLastError가 ERROR_FILE_NOT_FOUND 반환합니다.

[in] lpNewFileName

새 파일의 이름입니다.

팁

[in] bFailIfExists

이 매개 변수가 TRUE 이고 lpNewFileName 으로 지정된 새 파일이 이미 있는 경우 함수가 실패합니다. 이 매개 변수가 FALSE 이고 새 파일이 이미 있는 경우 함수는 기존 파일을 덮어쓰고 성공합니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

기존 파일에 대한 보안 리소스 속성(ATTRIBUTE_SECURITY_INFORMATION)이 새 파일에 복사됩니다.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 기존 파일의 보안 리소스 속성은 Windows 8 Windows Server 2012 때까지 새 파일에 복사되지 않습니다.

기존 파일의 파일 특성이 새 파일에 복사됩니다. 예를 들어 기존 파일에 FILE_ATTRIBUTE_READONLY 파일 특성이 있는 경우 CopyFile 호출을 통해 만든 복사본에는 FILE_ATTRIBUTE_READONLY 파일 특성도 있습니다. 자세한 내용은 파일 특성 검색 및 변경을 참조하세요.

대상 파일이 이미 있고 FILE_ATTRIBUTE_HIDDEN또는 FILE_ATTRIBUTE_READONLY 특성이 설정된 경우 이 함수는 ERROR_ACCESS_DENIED 실패합니다.

CopyFile을 사용하여 암호화된 파일을 복사하면 원본 파일 암호화에 사용된 키로 대상 파일을 암호화하려고 시도합니다. 이 작업을 수행할 수 없는 경우 이 함수는 기본 키를 사용하여 대상 파일을 암호화하려고 시도합니다. 이러한 메서드 중 어느 것도 수행할 수 없는 경우 copyFile 은 ERROR_ENCRYPTION_FAILED 오류 코드와 함께 실패합니다.

기호 링크 동작 - 원본 파일이 기호 링크인 경우 복사된 실제 파일은 기호 링크의 대상입니다.

대상 파일이 이미 있고 기호 링크인 경우 기호 링크의 대상은 원본 파일에서 덮어씁니다.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	Yes
SMB 3.0 TFO(투명 장애 조치(failover))	Yes
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	Yes
CsvFS(클러스터 공유 볼륨 파일 시스템)	Yes
ReFS(Resilient File System)	예

예제

예제는 파일 특성 검색 및 변경을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	winbase.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll