MoveFileExA 함수(winbase.h)

아티클
06/02/2023

다양한 이동 옵션을 사용하여 자식을 포함한 기존 파일 또는 디렉터리를 이동합니다.

MoveFileWithProgress 함수는 MoveFileWithProgress를 사용하면 진행률 알림을 받는 콜백 함수를 제공할 수 있다는 점을 제외하고 MoveFileEx 함수와 동일합니다.

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

구문

BOOL MoveFileExA(
  [in]           LPCSTR lpExistingFileName,
  [in, optional] LPCSTR lpNewFileName,
  [in]           DWORD  dwFlags
);

매개 변수

[in] lpExistingFileName

로컬 컴퓨터의 파일 또는 디렉터리의 현재 이름입니다.

dwFlags에서 MOVEFILE_DELAY_UNTIL_REBOOT 지정하는 경우 네트워크를 사용할 수 있기 전에 지연된 작업이 수행되므로 원격 공유에 파일이 있을 수 없습니다.

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

팁

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

[in, optional] lpNewFileName

로컬 컴퓨터의 파일 또는 디렉터리의 새 이름입니다.

파일을 이동할 때 대상은 다른 파일 시스템 또는 볼륨에 있을 수 있습니다. 대상이 다른 드라이브에 있는 경우 dwFlags에서 MOVEFILE_COPY_ALLOWED 플래그를 설정해야 합니다.

디렉터리를 이동할 때 대상은 동일한 드라이브에 있어야 합니다.

dwFlags가 MOVEFILE_DELAY_UNTIL_REBOOT 지정하고 lpNewFileName이 NULL인 경우 MoveFileEx는 시스템이 다시 시작될 때 삭제할 lpExistingFileName 파일을 등록합니다. lpExistingFileName이 디렉터리를 참조하는 경우 시스템은 디렉터리가 비어 있는 경우에만 다시 시작할 때 디렉터리를 제거합니다.

팁

[in] dwFlags

이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

값	의미
MOVEFILE_COPY_ALLOWED 2(0x2)	파일을 다른 볼륨으로 이동하는 경우 함수는 CopyFile 및 DeleteFile 함수를 사용하여 이동을 시뮬레이션합니다. 파일이 다른 볼륨에 성공적으로 복사되고 원래 파일을 삭제할 수 없는 경우 함수는 원본 파일을 그대로 유지합니다. 이 값은 MOVEFILE_DELAY_UNTIL_REBOOT 사용할 수 없습니다.
MOVEFILE_CREATE_HARDLINK 16(0x10)	다음에 사용하도록 예약됩니다.
MOVEFILE_DELAY_UNTIL_REBOOT 4(0x4)	운영 체제가 다시 시작될 때까지 시스템은 파일을 이동하지 않습니다. 시스템은 AUTOCHK가 실행된 직후에 페이징 파일을 만들기 전에 파일을 이동합니다. 따라서 이 매개 변수를 사용하면 함수가 이전 시작에서 페이징 파일을 삭제할 수 있습니다. 이 값은 프로세스가 관리자 그룹 또는 LocalSystem 계정에 속한 사용자의 컨텍스트에 있는 경우에만 사용할 수 있습니다. 이 값은 MOVEFILE_COPY_ALLOWED 사용할 수 없습니다.
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32(0x20)	원본 파일이 링크 원본이지만 이동 후 파일을 추적할 수 없으면 함수가 실패합니다. 대상이 FAT 파일 시스템으로 포맷된 볼륨인 경우 이 상황이 발생할 수 있습니다.
MOVEFILE_REPLACE_EXISTING 1(0x1)	lpNewFileName이라는 파일이 있는 경우 ACL(액세스 제어 목록)에 대한 보안 요구 사항이 충족되는 경우 함수는 해당 내용을 lpExistingFileName 파일의 콘텐츠로 바꿉니다. 자세한 내용은 이 항목의 ‘주의’ 섹션을 참조하세요. lpNewFileName이 기존 디렉터리의 이름을 지정하면 오류가 보고됩니다.
MOVEFILE_WRITE_THROUGH 8(0x8)	파일이 실제로 디스크에서 이동될 때까지 함수는 반환되지 않습니다. 이 값을 설정하면 함수가 반환되기 전에 복사 및 삭제 작업으로 수행된 이동이 디스크로 플러시됩니다. 플러시 는 복사 작업이 끝날 때 발생합니다. MOVEFILE_DELAY_UNTIL_REBOOT 설정된 경우에는 이 값이 적용되지 않습니다.

반환 값

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

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

설명

dwFlags 매개 변수가 MOVEFILE_DELAY_UNTIL_REBOOT 지정하면 레지스트리에 액세스할 수 없으면 MoveFileEx가 실패합니다. 함수는 다시 시작할 때 이름을 바꿀 파일의 위치를 다음 레지스트리 값에 저장합니다. HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations

이 레지스트리 값은 REG_MULTI_SZ 형식입니다. 각 이름 바꾸기 작업은 이름 바꾸기가 삭제인지 여부에 따라 다음 NULL로 끝나는 문자열 중 하나를 저장합니다.

szDstFile\0\0
szSrcFile\0szDstFile\0

szDstFile\0\0 문자열은 다시 부팅 시 szDstFile 파일이 삭제됨을 나타냅니다. szSrcFile\0szDstFile\0 문자열은 다시 부팅 시 szSrcFile의 이름을 szDstFile으로 변경해야 했음을 나타냅니다.

참고 \0\0은(는) 기술적으로 REG_MULTI_SZ 노드에서 허용되지 않지만 파일 이름이 null 이름으로 변경된 것으로 간주되기 때문일 수 있습니다.

시스템은 이러한 레지스트리 항목을 사용하여 실행된 순서와 동일한 순서로 다시 시작할 때 작업을 완료합니다. 예를 들어 다음 코드 조각은 다시 시작할 때 szDstFile을 삭제하고 szSrcFile의 이름을 szDstFile로 바꾸는 레지스트리 항목을 만듭니다.

MoveFileEx(szDstFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);
MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

호출 애플리케이션의 실행이 중단된 후 MOVEFILE_DELAY_UNTIL_REBOOT 플래그로 지정된 실제 이동 및 삭제 작업이 수행되므로 반환 값은 파일 이동 또는 삭제의 성공 또는 실패를 반영할 수 없습니다. 대신 레지스트리에 적절한 항목을 배치하는 데 성공 또는 실패가 반영됩니다.

시스템은 비어 있는 경우에만 MOVEFILE_DELAY_UNTIL_REBOOT 플래그를 사용하여 삭제할 수 있도록 태그가 지정된 디렉터리를 삭제합니다. 디렉터리를 삭제하려면 디렉터리 삭제를 시도하기 전에 디렉터리에서 모든 파일을 이동하거나 삭제합니다. 파일이 부팅 시 디렉터리에 있을 수 있지만 시스템에서 디렉터리를 삭제하려면 먼저 파일을 삭제하거나 이동해야 합니다.

이동 및 삭제 작업은 호출 애플리케이션에 지정된 순서대로 부팅 시 수행됩니다. 부팅 시 파일이 있는 디렉터리를 삭제하려면 먼저 파일을 삭제합니다.

파일이 볼륨 간에 이동되는 경우 MoveFileEx 는 파일과 함께 보안 설명자를 이동하지 않습니다. 파일에는 대상 디렉터리에 기본 보안 설명자가 할당됩니다.

MoveFileEx 함수는 링크 추적 서비스와 연산을 조정하므로 링크 원본이 이동될 때 추적할 수 있습니다.

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

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