Функция CreateToolhelp32Snapshot (tlhelp32.h)

Статья
08/26/2023

Принимает snapshot указанных процессов, а также кучи, модули и потоки, используемые этими процессами.

Синтаксис

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

Параметры

[in] dwFlags

Части системы, которые будут включены в snapshot. Этот параметр может иметь одно или несколько из следующих значений.

Значение	Значение
TH32CS_INHERIT 0x80000000	Указывает, что дескриптор snapshot должен быть наследуемым.
TH32CS_SNAPALL	Включает все процессы и потоки в системе, а также кучи и модули процесса, указанного в th32ProcessID. Эквивалентно указанию значений TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS и TH32CS_SNAPTHREAD , объединенных с помощью операции OR ('\|').
TH32CS_SNAPHEAPLIST 0x00000001	Включает все кучи процесса, указанного в th32ProcessID в snapshot. Сведения о перечислении кучи см. в разделе Heap32ListFirst.
TH32CS_SNAPMODULE 0x00000008	Включает все модули процесса, указанного в th32ProcessID в snapshot. Сведения о перечислении модулей см. в разделе Module32First. Если функция завершается сбоем с ERROR_BAD_LENGTH, повторите ее до тех пор, пока она не будет выполнена успешно. 64-разрядная версия Windows: Использование этого флага в 32-разрядном процессе включает 32-разрядные модули процесса, указанного в th32ProcessID, а его использование в 64-разрядном процессе включает 64-разрядные модули. Чтобы включить 32-разрядные модули процесса, указанного в th32ProcessID , из 64-разрядного процесса, используйте флаг TH32CS_SNAPMODULE32 .
TH32CS_SNAPMODULE32 0x00000010	Включает все 32-разрядные модули процесса, указанного в th32ProcessID, в snapshot при вызове из 64-разрядного процесса. Этот флаг можно сочетать с TH32CS_SNAPMODULE или TH32CS_SNAPALL. Если функция завершается сбоем с ERROR_BAD_LENGTH, повторите ее до тех пор, пока она не будет выполнена успешно.
TH32CS_SNAPPROCESS 0x00000002	Включает все процессы в системе в snapshot. Сведения о перечислении процессов см. в разделе Process32First.
TH32CS_SNAPTHREAD 0x00000004	Включает все потоки в системе в snapshot. Сведения о перечислении потоков см. в разделе Thread32First. Чтобы определить потоки, принадлежащие конкретному процессу, сравните его идентификатор процесса с элементом th32OwnerProcessIDструктуры THREADENTRY32 при перечислении потоков.

[in] th32ProcessID

Идентификатор процесса, включаемого в snapshot. Этот параметр может быть равен нулю, чтобы указать текущий процесс. Этот параметр используется при указании значения TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 или TH32CS_SNAPALL . В противном случае он игнорируется, и все процессы включаются в snapshot.

Если указанный процесс является неактивным процессом или одним из процессов CSRSS, эта функция завершается сбоем и последний код ошибки ERROR_ACCESS_DENIED , так как их ограничения доступа препятствуют открытию кода на уровне пользователя.

Если указанный процесс является 64-разрядным, а вызывающим — 32-разрядным процессом, эта функция завершается ошибкой и последний код ошибки — ERROR_PARTIAL_COPY (299).

Возвращаемое значение

Если функция завершается успешно, она возвращает открытый дескриптор указанной snapshot.

Если функция завершается сбоем, она возвращает INVALID_HANDLE_VALUE. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Возможные коды ошибок включают ERROR_BAD_LENGTH.

Snapshot, принятые этой функцией, проверяются другими функциями справки для предоставления результатов. Доступ к snapshot доступен только для чтения. Дескриптор snapshot действует как дескриптор объекта и подчиняется тем же правилам, в отношении каких процессов и потоков он действителен.

Чтобы перечислить состояния кучи или модуля для всех процессов, укажите TH32CS_SNAPALL и присвойте th32ProcessID значение 0. Затем для каждого дополнительного процесса в snapshot снова вызовите CreateToolhelp32Snapshot, указав идентификатор процесса и значение TH32CS_SNAPHEAPLIST или TH32_SNAPMODULE.

При создании моментальных снимков, включающих кучи и модули для процесса, отличного от текущего процесса, функция CreateToolhelp32Snapshot может завершаться ошибкой или возвращать неверные сведения по различным причинам. Например, если таблица данных загрузчика в целевом процессе повреждена или не инициализирована или список модулей изменяется во время вызова функции в результате загрузки или выгрузки библиотек DLL, функция может завершиться ошибкой с ERROR_BAD_LENGTH или другим кодом ошибки. Убедитесь, что целевой процесс не запущен в приостановленном состоянии, и попробуйте вызвать функцию еще раз. Если функция завершается сбоем с ERROR_BAD_LENGTH при вызове с помощью TH32CS_SNAPMODULE или TH32CS_SNAPMODULE32, вызывайте функцию еще раз, пока она не будет успешной.

Флаги TH32CS_SNAPMODULE и TH32CS_SNAPMODULE32 не извлекают дескрипторы для модулей, загруженных с LOAD_LIBRARY_AS_DATAFILE или аналогичными флагами. Дополнительные сведения см. в разделе LoadLibraryEx.

Чтобы уничтожить snapshot, используйте функцию CloseHandle.

Обратите внимание, что функцию QueryFullProcessImageName можно использовать для получения полного имени исполняемого образа для 32- и 64-разрядных процессов из 32-разрядного процесса.

Примеры

Пример см. в разделе Создание моментального снимка и просмотр процессов.

Требования


Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	tlhelp32.h
Библиотека	Kernel32.lib
DLL	Kernel32.dll