CreateToolhelp32Snapshot 함수(tlhelp32.h)

아티클
08/26/2023

지정된 프로세스의 스냅샷 이러한 프로세스에서 사용되는 힙, 모듈 및 스레드를 사용합니다.

구문

HANDLE CreateToolhelp32Snapshot(
  [in] DWORD dwFlags,
  [in] DWORD th32ProcessID
);

매개 변수

[in] dwFlags

스냅샷 포함할 시스템의 부분입니다. 이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

값	의미
TH32CS_INHERIT 0x80000000	스냅샷 핸들을 상속할 수 있음을 나타냅니다.
TH32CS_SNAPALL	시스템의 모든 프로세스 및 스레드와 th32ProcessID에 지정된 프로세스의 힙 및 모듈을 포함합니다. OR 연산('\|')을 사용하여 결합된 TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS 및 TH32CS_SNAPTHREAD 값을 지정하는 것과 같습니다.
TH32CS_SNAPHEAPLIST 0x00000001	스냅샷 th32ProcessID에 지정된 프로세스의 모든 힙을 포함합니다. 힙을 열거하려면 Heap32ListFirst를 참조하세요.
TH32CS_SNAPMODULE 0x00000008	스냅샷 th32ProcessID에 지정된 프로세스의 모든 모듈을 포함합니다. 모듈을 열거하려면 Module32First를 참조하세요. 함수가 ERROR_BAD_LENGTH 실패하면 성공할 때까지 함수를 다시 시도합니다. 64비트 Windows: 32비트 프로세스에서 이 플래그를 사용하려면 th32ProcessID에 지정된 프로세스의 32비트 모듈이 포함되며, 64비트 프로세스에서 이 플래그를 사용하면 64비트 모듈이 포함됩니다. 64비트 프로세스에서 th32ProcessID 에 지정된 프로세스의 32비트 모듈을 포함하려면 TH32CS_SNAPMODULE32 플래그를 사용합니다.
TH32CS_SNAPMODULE32 0x00000010	64비트 프로세스에서 호출될 때 스냅샷 th32ProcessID에 지정된 프로세스의 모든 32비트 모듈을 포함합니다. 이 플래그는 TH32CS_SNAPMODULE 또는 TH32CS_SNAPALL 결합할 수 있습니다. 함수가 ERROR_BAD_LENGTH 실패하면 성공할 때까지 함수를 다시 시도합니다.
TH32CS_SNAPPROCESS 0x00000002	스냅샷 시스템의 모든 프로세스를 포함합니다. 프로세스를 열거하려면 Process32First를 참조하세요.
TH32CS_SNAPTHREAD 0x00000004	스냅샷 시스템의 모든 스레드를 포함합니다. 스레드를 열거하려면 Thread32First를 참조하세요. 특정 프로세스에 속하는 스레드를 식별하려면 스레드를 열거할 때 해당 프로세스 식별자를 THREADENTRY32 구조체의 th32OwnerProcessID 멤버와 비교합니다.

[in] th32ProcessID

스냅샷 포함할 프로세스의 프로세스 식별자입니다. 이 매개 변수는 현재 프로세스를 나타내는 0일 수 있습니다. 이 매개 변수는 TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 또는 TH32CS_SNAPALL 값을 지정할 때 사용됩니다. 그렇지 않으면 무시되고 모든 프로세스가 스냅샷 포함됩니다.

지정된 프로세스가 유휴 프로세스이거나 CSRSS 프로세스 중 하나인 경우 이 함수는 실패하고 액세스 제한으로 인해 사용자 수준 코드가 열리지 않으므로 마지막 오류 코드가 ERROR_ACCESS_DENIED .

지정된 프로세스가 64비트 프로세스이고 호출자가 32비트 프로세스인 경우 이 함수는 실패하고 마지막 오류 코드는 ERROR_PARTIAL_COPY (299)입니다.

반환 값

함수가 성공하면 지정된 스냅샷 열린 핸들을 반환합니다.

함수가 실패하면 INVALID_HANDLE_VALUE 반환합니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다. 가능한 오류 코드에는 ERROR_BAD_LENGTH 포함됩니다.

설명

이 함수에서 수행한 스냅샷 결과를 제공하기 위해 다른 도구 도움말 함수에서 검사합니다. 스냅샷 대한 액세스는 읽기 전용입니다. 스냅샷 핸들은 개체 핸들 역할을 하며 유효한 프로세스 및 스레드에 대해 동일한 규칙이 적용됩니다.

모든 프로세스에 대한 힙 또는 모듈 상태를 열거하려면 TH32CS_SNAPALL 지정하고 th32ProcessID 를 0으로 설정합니다. 그런 다음, 스냅샷 각 추가 프로세스에 대해 CreateToolhelp32Snapshot을 다시 호출하고 프로세스 식별자와 TH32CS_SNAPHEAPLIST 또는 TH32_SNAPMODULE 값을 지정합니다.

현재 프로세스 이외의 프로세스에 대한 힙 및 모듈을 포함하는 스냅샷을 만들 때 CreateToolhelp32Snapshot 함수는 다양한 이유로 잘못된 정보를 실패하거나 반환할 수 있습니다. 예를 들어 대상 프로세스의 로더 데이터 테이블이 손상되었거나 초기화되지 않았거나 DLL이 로드되거나 언로드된 결과로 함수 호출 중에 모듈 목록이 변경되면 ERROR_BAD_LENGTH 또는 기타 오류 코드로 인해 함수가 실패할 수 있습니다. 대상 프로세스가 일시 중단된 상태에서 시작되지 않았는지 확인하고 함수를 다시 호출해 봅니다. TH32CS_SNAPMODULE 또는 TH32CS_SNAPMODULE32 함께 호출될 때 함수가 ERROR_BAD_LENGTH 실패하면 성공할 때까지 함수를 다시 호출합니다.

TH32CS_SNAPMODULE 및 TH32CS_SNAPMODULE32 플래그는 LOAD_LIBRARY_AS_DATAFILE 또는 유사한 플래그로 로드된 모듈에 대한 핸들을 검색하지 않습니다. 자세한 내용은 LoadLibraryEx를 참조하세요.

스냅샷 삭제하려면 CloseHandle 함수를 사용합니다.

QueryFullProcessImageName 함수를 사용하여 32비트 프로세스에서 32비트 및 64비트 프로세스 모두에 대한 실행 파일 이미지의 전체 이름을 검색할 수 있습니다.

예제

예제는 스냅샷 만들기 및 프로세스 보기를 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	tlhelp32.h
라이브러리	Kernel32.lib
DLL	Kernel32.dll