Função CreateToolhelp32Snapshot (tlhelp32.h)

Artigo
08/26/2023

Usa uma instantâneo dos processos especificados, bem como os heaps, módulos e threads usados por esses processos.

Sintaxe

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

Parâmetros

[in] dwFlags

As partes do sistema a serem incluídas no instantâneo. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
TH32CS_INHERIT 0x80000000	Indica que o identificador instantâneo deve ser herdável.
TH32CS_SNAPALL	Inclui todos os processos e threads no sistema, além dos heaps e módulos do processo especificado no th32ProcessID. Equivalente a especificar os valores TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS e TH32CS_SNAPTHREAD combinados usando uma operação OR ('\|').
TH32CS_SNAPHEAPLIST 0x00000001	Inclui todos os heaps do processo especificado no th32ProcessID no instantâneo. Para enumerar os heaps, consulte Heap32ListFirst.
TH32CS_SNAPMODULE 0x00000008	Inclui todos os módulos do processo especificado no th32ProcessID no instantâneo. Para enumerar os módulos, consulte Module32First. Se a função falhar com ERROR_BAD_LENGTH, tente novamente a função até que ela seja bem-sucedida. Windows de 64 bits: Usar esse sinalizador em um processo de 32 bits inclui os módulos de 32 bits do processo especificado em th32ProcessID, enquanto usá-lo em um processo de 64 bits inclui os módulos de 64 bits. Para incluir os módulos de 32 bits do processo especificado no th32ProcessID de um processo de 64 bits, use o sinalizador TH32CS_SNAPMODULE32 .
TH32CS_SNAPMODULE32 0x00000010	Inclui todos os módulos de 32 bits do processo especificado em th32ProcessID no instantâneo quando chamado de um processo de 64 bits. Esse sinalizador pode ser combinado com TH32CS_SNAPMODULE ou TH32CS_SNAPALL. Se a função falhar com ERROR_BAD_LENGTH, tente novamente a função até que ela seja bem-sucedida.
TH32CS_SNAPPROCESS 0x00000002	Inclui todos os processos no sistema no instantâneo. Para enumerar os processos, consulte Process32First.
TH32CS_SNAPTHREAD 0x00000004	Inclui todos os threads no sistema no instantâneo. Para enumerar os threads, consulte Thread32First. Para identificar os threads que pertencem a um processo específico, compare seu identificador de processo com o membro th32OwnerProcessID da estrutura THREADENTRY32 ao enumerar os threads.

[in] th32ProcessID

O identificador de processo do processo a ser incluído no instantâneo. Esse parâmetro pode ser zero para indicar o processo atual. Esse parâmetro é usado quando o valor TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 ou TH32CS_SNAPALL é especificado. Caso contrário, ele será ignorado e todos os processos serão incluídos no instantâneo.

Se o processo especificado for o processo ocioso ou um dos processos CSRSS, essa função falhará e o último código de erro será ERROR_ACCESS_DENIED porque suas restrições de acesso impedem que o código no nível do usuário os abra.

Se o processo especificado for um processo de 64 bits e o chamador for um processo de 32 bits, essa função falhará e o último código de erro será ERROR_PARTIAL_COPY (299).

Valor retornado

Se a função for bem-sucedida, ela retornará um identificador aberto para o instantâneo especificado.

Se a função falhar, ela retornará INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError. Os códigos de erro possíveis incluem ERROR_BAD_LENGTH.

Comentários

Os instantâneo obtidos por essa função são examinados pelas outras funções de ajuda da ferramenta para fornecer seus resultados. O acesso ao instantâneo é somente leitura. O identificador instantâneo atua como um identificador de objeto e está sujeito às mesmas regras em relação a quais processos e threads ele é válido.

Para enumerar os estados de heap ou módulo para todos os processos, especifique TH32CS_SNAPALL e defina th32ProcessID como zero. Em seguida, para cada processo adicional no instantâneo, chame CreateToolhelp32Snapshot novamente, especificando seu identificador de processo e o valor TH32CS_SNAPHEAPLIST ou TH32_SNAPMODULE.

Ao tirar instantâneos que incluem heaps e módulos para um processo diferente do processo atual, a função CreateToolhelp32Snapshot pode falhar ou retornar informações incorretas por vários motivos. Por exemplo, se a tabela de dados do carregador no processo de destino estiver corrompida ou não for inicializada, ou se a lista de módulos for alterada durante a chamada de função como resultado de DLLs sendo carregadas ou descarregadas, a função poderá falhar com ERROR_BAD_LENGTH ou outro código de erro. Verifique se o processo de destino não foi iniciado em um estado suspenso e tente chamar a função novamente. Se a função falhar com ERROR_BAD_LENGTH quando chamada com TH32CS_SNAPMODULE ou TH32CS_SNAPMODULE32, chame a função novamente até que ela seja bem-sucedida.

Os sinalizadores TH32CS_SNAPMODULE e TH32CS_SNAPMODULE32 não recuperam identificadores para módulos que foram carregados com o LOAD_LIBRARY_AS_DATAFILE ou sinalizadores semelhantes. Para obter mais informações, consulte LoadLibraryEx.

Para destruir o instantâneo, use a função CloseHandle.

Observe que você pode usar a função QueryFullProcessImageName para recuperar o nome completo de uma imagem executável para processos de 32 e 64 bits de um processo de 32 bits.

Exemplos

Para obter um exemplo, consulte Tomando um instantâneo e exibindo processos.

Requisitos


Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	tlhelp32.h
Biblioteca	Kernel32.lib
DLL	Kernel32.dll