ReplaceFileA 함수(winbase.h)

아티클
06/02/2023

한 파일을 다른 파일로 바꾸며, 원본 파일의 백업 복사본을 만드는 옵션을 제공합니다. 대체 파일은 대체된 파일의 이름과 해당 ID를 가정합니다.

구문

BOOL ReplaceFileA(
  [in]           LPCSTR lpReplacedFileName,
  [in]           LPCSTR lpReplacementFileName,
  [in, optional] LPCSTR lpBackupFileName,
  [in]           DWORD  dwReplaceFlags,
                 LPVOID lpExclude,
                 LPVOID lpReserved
);

매개 변수

[in] lpReplacedFileName

바꿀 파일의 이름입니다.

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

팁

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

이 파일은 GENERIC_READ, DELETE 및 SYNCHRONIZE 액세스 권한으로 열립니다. 공유 모드는 FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

호출자는 바꿀 파일에 대한 쓰기 권한이 있어야 합니다. 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.

[in] lpReplacementFileName

lpReplacedFileName 파일을 대체할 파일의 이름입니다.

팁

함수는 모든 특성 및 ACL을 유지할 수 있도록 SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE 및 WRITE_DAC 액세스 권한으로 이 파일을 열려고 시도합니다. 이 오류가 발생하면 함수는 SYNCHRONIZE, GENERIC_READ, DELETE 및 WRITE_DAC 액세스 권한으로 파일을 열려고 시도합니다. 공유 모드가 지정되지 않았습니다.

[in, optional] lpBackupFileName

lpReplacedFileName 파일의 백업 복사본으로 사용할 파일의 이름입니다. 이 매개 변수가 NULL이면 백업 파일이 만들어지지 않습니다. 백업 파일에 대한 구현 세부 정보는 설명 섹션을 참조하세요.

팁

[in] dwReplaceFlags

대체 옵션입니다. 이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

값	의미
REPLACEFILE_WRITE_THROUGH 0x00000001	이 값은 지원되지 않습니다.
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	대체된 파일에서 대체 파일로 정보(예: 특성 및 ACL)를 병합하는 동안 발생하는 오류를 무시합니다. 따라서 이 플래그를 지정하고 WRITE_DAC 액세스 권한이 없는 경우 함수는 성공하지만 ACL은 유지되지 않습니다.
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	대체된 파일에서 대체 파일로 ACL 정보를 병합하는 동안 발생하는 오류를 무시합니다. 따라서 이 플래그를 지정하고 WRITE_DAC 액세스 권한이 없는 경우 함수는 성공하지만 ACL은 유지되지 않습니다. 이 값을 사용하는 애플리케이션을 컴파일하려면 _WIN32_WINNT 매크로를 0x0600 이상으로 정의합니다. Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다.

lpExclude

나중에 사용하기 위해 예약되어 있습니다.

lpReserved

나중에 사용하기 위해 예약되어 있습니다.

반환 값

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

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다. 다음은 이 함수에 대한 가능한 오류 코드입니다.

반환 코드/값	설명
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176(0x498)	대체 파일의 이름을 바꿀 수 없습니다. lpBackupFileName을 지정한 경우 대체 파일과 대체 파일은 원래 파일 이름을 유지합니다. 그렇지 않으면 대체된 파일이 더 이상 존재하지 않으며 대체 파일이 원래 이름 아래에 있습니다.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177(0x499)	대체 파일을 이동할 수 없습니다. 대체 파일은 원래 이름으로 계속 존재합니다. 그러나 대체 중인 파일에서 파일 스트림 및 특성을 상속했습니다. 바꿀 파일은 여전히 다른 이름으로 존재합니다. lpBackupFileName을 지정하면 대체된 파일의 이름이 됩니다.
ERROR_UNABLE_TO_REMOVE_REPLACED 1175(0x497)	대체된 파일을 삭제할 수 없습니다. 대체된 파일과 대체 파일은 원래 파일 이름을 유지합니다.

ERROR_INVALID_PARAMETER 같은 다른 오류가 반환되면 대체 파일과 대체 파일은 원래 파일 이름을 유지합니다. 이 시나리오에서는 백업 파일이 존재하지 않으며 대체 파일이 대체된 파일의 모든 특성과 스트림을 상속한다고 보장할 수 없습니다.

설명

팁 이 함수의 유니코드 버전(ReplaceFileW)의 경우 Windows 10 버전 1607부터 옵트인하여 MAX_PATH 제한을 제거할 수 있습니다. 자세한 내용은 파일, 경로 및 네임스페이스의 "최대 경로 길이 제한" 섹션을 참조하세요.

ReplaceFile 함수는 단일 함수 내에서 여러 단계를 결합합니다. 애플리케이션은 별도의 함수를 호출하는 대신 ReplaceFile 을 호출하여 데이터를 새 파일에 저장하고, 임시 이름을 사용하여 원래 파일의 이름을 바꾸고, 새 파일의 이름을 원래 파일과 동일한 이름으로 바꾸고, 원본 파일을 삭제할 수 있습니다. 또 다른 장점은 ReplaceFile 이 새 파일 데이터를 복사할 뿐만 아니라 원래 파일의 다음 특성을 유지한다는 것입니다.

생성 시간
짧은 파일 이름
개체 식별자
DACL
보안 리소스 특성
암호화
압축
대체 파일에 명명된 스트림이 아직 없습니다.

예를 들어 대체 파일이 암호화되었지만 대체된 파일이 암호화되지 않은 경우 결과 파일은 암호화되지 않습니다.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 원래 파일에 대한 보안 리소스 특성(ATTRIBUTE_SECURITY_INFORMATION)은 Windows 8 Windows Server 2012 때까지 유지되지 않습니다.

참고

선택적 초기화를 사용하여 대체 파일을 보호하는 경우 대체 파일은 대체 파일의 엔터프라이즈 ID로 보호됩니다.

결과 파일의 파일 ID는 대체 파일과 동일합니다.

백업 파일, 교체된 파일 및 대체 파일은 모두 동일한 볼륨에 있어야 합니다.

파일을 삭제하거나 이름을 바꾸려면 파일에 대한 삭제 권한이 있거나 부모 디렉터리에서 자식 권한을 삭제해야 합니다. 자식 삭제 및 삭제를 제외한 모든 액세스 권한이 있는 디렉터리를 설정하고 새 파일의 DACL을 상속하는 경우 파일을 삭제하지 않고도 만들 수 있어야 합니다. 그러나 파일을 만들 수 있으며 파일을 만들 때 반환된 핸들에 대해 요청하는 모든 액세스 권한을 얻을 수 있습니다. 파일을 만들 때 삭제 권한을 요청한 경우 해당 핸들을 사용하여 파일을 삭제하거나 이름을 바꿀 수 있지만 다른 핸들은 삭제하거나 이름을 바꿀 수 없습니다.

참고

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

요구 사항


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