Función CreateToolhelp32Snapshot (tlhelp32.h)

Artículo
03/08/2023

Toma una instantánea de los procesos especificados, así como los montones, módulos y subprocesos usados por estos procesos.

Sintaxis

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

Parámetros

[in] dwFlags

Partes del sistema que se incluirán en la instantánea. Este parámetro puede ser uno o más de los siguientes valores.

Value	Significado
TH32CS_INHERIT 0x80000000	Indica que el identificador de instantánea debe ser heredable.
TH32CS_SNAPALL	Incluye todos los procesos y subprocesos del sistema, además de los montones y módulos del proceso especificados en th32ProcessID. Equivalente a especificar los valores de TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS y TH32CS_SNAPTHREAD combinados mediante una operación OR ('\|').
TH32CS_SNAPHEAPLIST 0x00000001	Incluye todos los montones del proceso especificado en th32ProcessID en la instantánea. Para enumerar los montones, consulte Heap32ListFirst.
TH32CS_SNAPMODULE 0x00000008	Incluye todos los módulos del proceso especificados en th32ProcessID en la instantánea. Para enumerar los módulos, consulte Module32First. Si se produce un error en la función con ERROR_BAD_LENGTH, vuelva a intentar la función hasta que se realice correctamente. Windows de 64 bits: El uso de esta marca en un proceso de 32 bits incluye los módulos de 32 bits del proceso especificado en th32ProcessID, mientras que su uso en un proceso de 64 bits incluye los módulos de 64 bits. Para incluir los módulos de 32 bits del proceso especificado en th32ProcessID desde un proceso de 64 bits, use la marca TH32CS_SNAPMODULE32 .
TH32CS_SNAPMODULE32 0x00000010	Incluye todos los módulos de 32 bits del proceso especificado en th32ProcessID en la instantánea cuando se llama desde un proceso de 64 bits. Esta marca se puede combinar con TH32CS_SNAPMODULE o TH32CS_SNAPALL. Si se produce un error en la función con ERROR_BAD_LENGTH, vuelva a intentar la función hasta que se realice correctamente.
TH32CS_SNAPPROCESS 0x00000002	Incluye todos los procesos del sistema en la instantánea. Para enumerar los procesos, consulte Process32First.
TH32CS_SNAPTHREAD 0x00000004	Incluye todos los subprocesos del sistema en la instantánea. Para enumerar los subprocesos, consulte Thread32First. Para identificar los subprocesos que pertenecen a un proceso específico, compare su identificador de proceso con el miembro th32OwnerProcessID de la estructura THREADENTRY32 al enumerar los subprocesos.

[in] th32ProcessID

Identificador de proceso del proceso que se va a incluir en la instantánea. Este parámetro puede ser cero para indicar el proceso actual. Este parámetro se usa cuando se especifica el valor de TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32 o TH32CS_SNAPALL . De lo contrario, se omite y todos los procesos se incluyen en la instantánea.

Si el proceso especificado es el proceso Inactivo o uno de los procesos CSRSS, se produce un error en esta función y el último código de error se ERROR_ACCESS_DENIED porque sus restricciones de acceso impiden que el código de nivel de usuario los abra.

Si el proceso especificado es un proceso de 64 bits y el autor de la llamada es un proceso de 32 bits, se produce un error en esta función y el último código de error es ERROR_PARTIAL_COPY (299).

Valor devuelto

Si la función se ejecuta correctamente, devuelve un identificador abierto a la instantánea especificada.

Si se produce un error en la función, devuelve INVALID_HANDLE_VALUE. Para obtener información de error extendida, llame a GetLastError. Entre los posibles códigos de error se incluyen ERROR_BAD_LENGTH.

Comentarios

La otra herramienta examina la instantánea tomada por esta función para proporcionar sus resultados. El acceso a la instantánea es de solo lectura. El identificador de instantánea actúa como un identificador de objeto y está sujeto a las mismas reglas con respecto a los procesos y subprocesos en los que es válido.

Para enumerar los estados del montón o módulo para todos los procesos, especifique TH32CS_SNAPALL y establezca th32ProcessID en cero. A continuación, para cada proceso adicional de la instantánea, llame a CreateToolhelp32Snapshot de nuevo, especificando su identificador de proceso y el valor de TH32CS_SNAPHEAPLIST o TH32_SNAPMODULE .

Al tomar instantáneas que incluyen montones y módulos para un proceso distinto del proceso actual, la función CreateToolhelp32Snapshot puede producir un error o devolver información incorrecta por diversos motivos. Por ejemplo, si la tabla de datos del cargador del proceso de destino está dañada o no se inicializa, o si la lista de módulos cambia durante la llamada de función como resultado de que se cargan o descargan archivos DLL, la función podría producir un error con ERROR_BAD_LENGTH u otro código de error. Asegúrese de que el proceso de destino no se inició en un estado suspendido e intente volver a llamar a la función. Si se produce un error en la función con ERROR_BAD_LENGTH cuando se llama a con TH32CS_SNAPMODULE o TH32CS_SNAPMODULE32, vuelva a llamar a la función hasta que se realice correctamente.

Las marcas TH32CS_SNAPMODULE y TH32CS_SNAPMODULE32 no recuperan identificadores para los módulos cargados con el LOAD_LIBRARY_AS_DATAFILE o marcas similares. Para obtener más información, consulte LoadLibraryEx.

Para destruir la instantánea, use la función CloseHandle .

Tenga en cuenta que puede usar la función QueryFullProcessImageName para recuperar el nombre completo de una imagen ejecutable para procesos de 32 y 64 bits de un proceso de 32 bits.

Ejemplos

Para obtener un ejemplo, vea Tomar una instantánea y ver procesos.

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	tlhelp32.h
Library	Kernel32.lib
Archivo DLL	Kernel32.dll