_heapwalk

Artículo
06/09/2015

Recorre el montón y devuelve información sobre la entrada siguiente.

Importante

Esta API no se puede usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución, salvo en compilaciones Debug.Para obtener más información, vea Funciones de CRT no admitidas con /ZW.

int _heapwalk( 
   _HEAPINFO *entryinfo 
);

Parámetros

entryinfo
Búfer que contendrá la información del montón.

Valor devuelto

_heapwalk devuelve una de las siguientes constantes de manifiesto enteras, definidas en Malloc.h.

_HEAPBADBEGIN
La información de encabezado inicial no es válida o no se encuentra.
_HEAPBADNODE
Se ha encontrado un montón dañado o un nodo incorrecto.
_HEAPBADPTR
El campo _pentry de la estructura de _HEAPINFO no contiene un puntero válido para el montón o entryinfo es un puntero nulo.
_HEAPEND
Se ha llegado al final del montón correctamente.
_HEAPEMPTY
El montón no está inicializado.
_HEAPOK
Ningún error hasta el momento. entryinfo se actualiza con la información sobre la siguiente entrada del montón.

Además, si se produce un error, _heapwalk establece errno en ENOSYS.

Comentarios

La función _heapwalk ayuda a depurar problemas relacionados con el montón de los programas. La función recorre el montón, atravesando una entrada por llamada, y devuelve un puntero a una estructura del tipo _HEAPINFO que contiene información sobre la siguiente entrada del montón. El tipo _HEAPINFO, definido en Malloc.h, contiene los elementos siguientes.

int *_pentry
Puntero de entrada en el montón.
size_t _size
Tamaño de la entrada del montón.
int _useflag
Marca que indica si la entrada del montón está en uso.

Una llamada a _heapwalk que devuelve _HEAPOK almacena el tamaño de la entrada en el campo _size y establece el campo _useflag en _FREEENTRY o _USEDENTRY (ambas constantes se definen en Malloc.h). Para obtener esta información sobre la primera entrada del montón, pase un puntero de _heapwalk a una estructura de _HEAPINFO cuyo miembro _pentry sea NULL. Si el sistema operativo no admite _heapwalk(por ejemplo Windows 98), la función devuelve _HEAPEND y establece errno en ENOSYS.

Esta función valida su parámetro. Si entryinfo es un puntero nulo, se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, errno se establece en EINVAL y la función devuelve _HEAPBADPTR.

Requisitos

Rutina	Encabezado necesario	Encabezado opcional
_heapwalk	<malloc.h>	<errno.h>

Para obtener más información sobre compatibilidad, vea Compatibilidad.

Ejemplo

// crt_heapwalk.c

// This program "walks" the heap, starting
// at the beginning (_pentry = NULL). It prints out each
// heap entry's use, location, and size. It also prints
// out information about the overall state of the heap as
// soon as _heapwalk returns a value other than _HEAPOK
// or if the loop has iterated 100 times.

#include <stdio.h>
#include <malloc.h>

void heapdump(void);

int main(void)
{
    char *buffer;

    heapdump();
    if((buffer = (char *)malloc(59)) != NULL)
    {
        heapdump();
        free(buffer);
    }
    heapdump();
}

void heapdump(void)
{
    _HEAPINFO hinfo;
    int heapstatus;
    int numLoops;
    hinfo._pentry = NULL;
    numLoops = 0;
    while((heapstatus = _heapwalk(&hinfo)) == _HEAPOK &&
          numLoops < 100)
    {
        printf("%6s block at %Fp of size %4.4X\n",
               (hinfo._useflag == _USEDENTRY ? "USED" : "FREE"),
               hinfo._pentry, hinfo._size);
        numLoops++;
    }

    switch(heapstatus)
    {
    case _HEAPEMPTY:
        printf("OK - empty heap\n");
        break;
    case _HEAPEND:
        printf("OK - end of heap\n");
        break;
    case _HEAPBADPTR:
        printf("ERROR - bad pointer to heap\n");
        break;
    case _HEAPBADBEGIN:
        printf("ERROR - bad start of heap\n");
        break;
    case _HEAPBADNODE:
        printf("ERROR - bad node in heap\n");
        break;
    }
}