CopyFileA 함수(winbase.h)

아티클
06/02/2023

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

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

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

구문

BOOL CopyFileA(
  [in] LPCSTR lpExistingFileName,
  [in] LPCSTR 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)	예

예제

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

참고

winbase.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 CopyFile을 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

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