Funzione CreateToolhelp32Snapshot (tlhelp32.h)

Articolo
08/26/2023

Acquisisce uno snapshot dei processi specificati, nonché gli heaps, i moduli e i thread usati da questi processi.

Sintassi

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

Parametri

[in] dwFlags

Parti del sistema da includere nello snapshot. Questo parametro può essere uno o più dei valori seguenti.

valore	Significato
TH32CS_INHERIT 0x80000000	Indica che l'handle snapshot deve essere ereditato.
TH32CS_SNAPALL	Include tutti i processi e i thread nel sistema, oltre agli heaps e ai moduli del processo specificato in th32ProcessID. Equivalente a specificare i valori TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS e TH32CS_SNAPTHREAD combinati usando un'operazione OR ('\|').
TH32CS_SNAPHEAPLIST 0x00000001	Include tutti gli heaps del processo specificato in th32ProcessID nello snapshot. Per enumerare gli heaps, vedere Heap32ListFirst.
TH32CS_SNAPMODULE 0x00000008	Include tutti i moduli del processo specificato in th32ProcessID nello snapshot. Per enumerare i moduli, vedere Module32First. Se la funzione ha esito negativo con ERROR_BAD_LENGTH, riprovare la funzione fino a quando non riesce. Windows a 64 bit: L'uso di questo flag in un processo a 32 bit include i moduli a 32 bit del processo specificato nel th32ProcessID, mentre lo usa in un processo a 64 bit include i moduli a 64 bit. Per includere i moduli a 32 bit del processo specificato in th32ProcessID da un processo a 64 bit, usare il flag di TH32CS_SNAPMODULE32 .
TH32CS_SNAPMODULE32 0x00000010	Include tutti i moduli a 32 bit del processo specificato in th32ProcessID nello snapshot quando viene chiamato da un processo a 64 bit. Questo flag può essere combinato con TH32CS_SNAPMODULE o TH32CS_SNAPALL. Se la funzione ha esito negativo con ERROR_BAD_LENGTH, riprovare la funzione fino a quando non riesce.
TH32CS_SNAPPROCESS 0x00000002	Include tutti i processi nel sistema nello snapshot. Per enumerare i processi, vedere Process32First.
TH32CS_SNAPTHREAD 0x00000004	Include tutti i thread nel sistema nello snapshot. Per enumerare i thread, vedere Thread32First. Per identificare i thread appartenenti a un processo specifico, confrontare l'identificatore del processo al membro th32OwnerProcessID della struttura THREADENTRY32 durante l'enumerazione dei thread.

[in] th32ProcessID

Identificatore del processo da includere nello snapshot. Questo parametro può essere zero per indicare il processo corrente. Questo parametro viene usato quando viene specificato il valore TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 o TH32CS_SNAPALL. In caso contrario, viene ignorato e tutti i processi vengono inclusi nello snapshot.

Se il processo specificato è il processo inattiva o uno dei processi CSRSS, questa funzione ha esito negativo e l'ultimo codice di errore viene ERROR_ACCESS_DENIED perché le restrizioni di accesso impediscono l'apertura del codice a livello di utente.

Se il processo specificato è un processo a 64 bit e il chiamante è un processo a 32 bit, questa funzione ha esito negativo e l'ultimo codice di errore è ERROR_PARTIAL_COPY (299).

Valore restituito

Se la funzione ha esito positivo, restituisce un handle aperto allo snapshot specificato.

Se la funzione ha esito negativo, restituisce INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError. I codici di errore possibili includono ERROR_BAD_LENGTH.

Commenti

Lo snapshot eseguito da questa funzione viene esaminato dall'altro strumento per fornire i risultati. L'accesso allo snapshot è di sola lettura. L'handle snapshot funge da handle oggetto ed è soggetto alle stesse regole relative ai processi e ai thread in cui è valido.

Per enumerare gli stati dell'heap o del modulo per tutti i processi, specificare TH32CS_SNAPALL e impostare th32ProcessID su zero. Quindi, per ogni processo aggiuntivo nello snapshot, chiamare di nuovo CreateToolhelp32Snapshot , specificando il relativo identificatore di processo e il TH32CS_SNAPHEAPLIST o TH32_SNAPMODULE valore.

Quando si eseguono snapshot che includono heaps e moduli per un processo diverso dal processo corrente, la funzione CreateToolhelp32Snapshot può non riuscire o restituire informazioni non corrette per un'ampia gamma di motivi. Ad esempio, se la tabella dati del caricatore nel processo di destinazione è danneggiata o non inizializzata oppure se l'elenco dei moduli cambia durante la chiamata alla funzione in seguito al caricamento o al caricamento delle DLL, la funzione potrebbe non riuscire con ERROR_BAD_LENGTH o altro codice di errore. Assicurarsi che il processo di destinazione non sia stato avviato in uno stato sospeso e provare a chiamare nuovamente la funzione. Se la funzione ha esito negativo con ERROR_BAD_LENGTH quando viene chiamata con TH32CS_SNAPMODULE o TH32CS_SNAPMODULE32, chiamare di nuovo la funzione finché non riesce.

I flag TH32CS_SNAPMODULE e TH32CS_SNAPMODULE32 non recuperano handle per i moduli caricati con i flagLOAD_LIBRARY_AS_DATAFILE o simili. Per altre informazioni, vedere LoadLibraryEx.

Per eliminare lo snapshot, usare la funzione CloseHandle .

Si noti che è possibile usare la funzione QueryFullProcessImageName per recuperare il nome completo di un'immagine eseguibile per processi a 32 e 64 bit da un processo a 32 bit.

Esempio

Per un esempio, vedere Creazione di uno snapshot e visualizzazione di processi.

Requisiti


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	tlhelp32.h
Libreria	Kernel32.lib
DLL	Kernel32.dll