CreateToolhelp32Snapshot-Funktion (tlhelp32.h)

Artikel
08/26/2023

Übernimmt eine Momentaufnahme der angegebenen Prozesse sowie der Heaps, Module und Threads, die von diesen Prozessen verwendet werden.

Syntax

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

Parameter

[in] dwFlags

Die Teile des Systems, die in die Momentaufnahme einbezogen werden sollen. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
TH32CS_INHERIT 0x80000000	Gibt an, dass das Momentaufnahme Handle vererbt werden soll.
TH32CS_SNAPALL	Umfasst alle Prozesse und Threads im System sowie die Heaps und Module des Prozesses, die in th32ProcessID angegeben sind. Entspricht der Angabe der werte TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS und TH32CS_SNAPTHREAD , die mithilfe eines OR-Vorgangs ('\|') kombiniert werden.
TH32CS_SNAPHEAPLIST 0x00000001	Enthält alle Heaps des Prozesses, die in th32ProcessID im Momentaufnahme angegeben sind. Informationen zum Auflisten der Heaps finden Sie unter Heap32ListFirst.
TH32CS_SNAPMODULE 0x00000008	Enthält alle Module des in th32ProcessID angegebenen Prozesses im Momentaufnahme. Informationen zum Auflisten der Module finden Sie unter Module32First. Wenn die Funktion mit ERROR_BAD_LENGTH fehlschlägt, wiederholen Sie die Funktion, bis sie erfolgreich ist. 64-Bit-Windows: Die Verwendung dieses Flags in einem 32-Bit-Prozess umfasst die 32-Bit-Module des in th32ProcessID angegebenen Prozesses, während die Verwendung in einem 64-Bit-Prozess die 64-Bit-Module umfasst. Verwenden Sie das Flag TH32CS_SNAPMODULE32, um die 32-Bit-Module des in th32ProcessID angegebenen Prozesses aus einem 64-Bit-Prozess einzuschließen.
TH32CS_SNAPMODULE32 0x00000010	Enthält alle 32-Bit-Module des Prozesses, der in th32ProcessID in der Momentaufnahme angegeben ist, wenn von einem 64-Bit-Prozess aufgerufen wird. Dieses Flag kann mit TH32CS_SNAPMODULE oder TH32CS_SNAPALL kombiniert werden. Wenn die Funktion mit ERROR_BAD_LENGTH fehlschlägt, wiederholen Sie die Funktion, bis sie erfolgreich ist.
TH32CS_SNAPPROCESS 0x00000002	Umfasst alle Prozesse im System in der Momentaufnahme. Informationen zum Auflisten der Prozesse finden Sie unter Process32First.
TH32CS_SNAPTHREAD 0x00000004	Enthält alle Threads im System im Momentaufnahme. Informationen zum Auflisten der Threads finden Sie unter Thread32First. Um die Threads zu identifizieren, die zu einem bestimmten Prozess gehören, vergleichen Sie seinen Prozessbezeichner mit dem th32OwnerProcessID-Member der THREADENTRY32-Struktur , wenn die Threads aufgelistet werden.

[in] th32ProcessID

Der Prozessbezeichner des Prozesses, der in den Momentaufnahme eingeschlossen werden soll. Dieser Parameter kann null sein, um den aktuellen Prozess anzugeben. Dieser Parameter wird verwendet, wenn der wert TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 oder TH32CS_SNAPALL angegeben wird. Andernfalls wird sie ignoriert, und alle Prozesse sind in der Momentaufnahme enthalten.

Wenn der angegebene Prozess der Leerlaufprozess oder einer der CSRSS-Prozesse ist, schlägt diese Funktion fehl, und der letzte Fehlercode wird ERROR_ACCESS_DENIED , da ihre Zugriffsbeschränkungen verhindern, dass Code auf Benutzerebene geöffnet wird.

Wenn der angegebene Prozess ein 64-Bit-Prozess und der Aufrufer ein 32-Bit-Prozess ist, schlägt diese Funktion fehl, und der letzte Fehlercode ist ERROR_PARTIAL_COPY (299).

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie ein geöffnetes Handle an die angegebene Momentaufnahme zurück.

Wenn die Funktion fehlschlägt, gibt sie INVALID_HANDLE_VALUE zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Mögliche Fehlercodes sind ERROR_BAD_LENGTH.

Hinweise

Die von dieser Funktion übernommenen Momentaufnahme werden von den anderen Toolhilfsfunktionen untersucht, um ihre Ergebnisse bereitzustellen. Der Zugriff auf die Momentaufnahme ist schreibgeschützt. Das Momentaufnahme-Handle fungiert als Objekthandle und unterliegt den gleichen Regeln hinsichtlich der Prozesse und Threads, in denen es gültig ist.

Um die Heap- oder Modulzustände für alle Prozesse aufzulisten, geben Sie TH32CS_SNAPALL an, und legen Sie th32ProcessID auf 0 fest. Rufen Sie dann für jeden weiteren Prozess in der Momentaufnahme CreateToolhelp32Snapshot erneut auf, und geben Sie den Prozessbezeichner und den TH32CS_SNAPHEAPLIST oder TH32_SNAPMODULE Wert an.

Beim Erstellen von Momentaufnahmen, die Heaps und Module für einen anderen Prozess als den aktuellen Prozess enthalten, kann die CreateToolhelp32Snapshot-Funktion aus verschiedenen Gründen fehlschlagen oder falsche Informationen zurückgeben. Wenn beispielsweise die Ladedatentabelle im Zielprozess beschädigt oder nicht initialisiert ist oder wenn sich die Modulliste während des Funktionsaufrufs ändert, weil DLLs geladen oder entladen werden, schlägt die Funktion möglicherweise mit ERROR_BAD_LENGTH oder einem anderen Fehlercode fehl. Stellen Sie sicher, dass der Zielprozess nicht in einem angehaltenen Zustand gestartet wurde, und versuchen Sie erneut, die Funktion aufzurufen. Wenn die Funktion mit ERROR_BAD_LENGTH fehlschlägt, wenn sie mit TH32CS_SNAPMODULE oder TH32CS_SNAPMODULE32 aufgerufen wird, rufen Sie die Funktion erneut auf, bis sie erfolgreich ist.

Die TH32CS_SNAPMODULE - und TH32CS_SNAPMODULE32-Flags rufen keine Handles für Module ab, die mit dem LOAD_LIBRARY_AS_DATAFILE oder ähnlichen Flags geladen wurden. Weitere Informationen finden Sie unter LoadLibraryEx.

Um die Momentaufnahme zu zerstören, verwenden Sie die CloseHandle-Funktion.

Beachten Sie, dass Sie die QueryFullProcessImageName-Funktion verwenden können, um den vollständigen Namen eines ausführbaren Images für 32- und 64-Bit-Prozesse aus einem 32-Bit-Prozess abzurufen.

Beispiele

Ein Beispiel finden Sie unter Erstellen einer Momentaufnahme und Anzeigen von Prozessen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	tlhelp32.h
Bibliothek	Kernel32.lib
DLL	Kernel32.dll