_heapwalk

Percorre o heap e retorna informações sobre a próxima entrada.

Importante

Esta API não pode ser usada em aplicativos executados no Windows Runtime, exceto em builds de depuração. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

int _heapwalk( _HEAPINFO *entryinfo );

Parâmetros

entryinfo
Buffer que conterá informações do heap.

Valor retornado

_heapwalk retorna uma das seguintes constantes de manifesto de inteiro definidas em Malloc.h.

Valor retornado	Significado
_HEAPBADBEGIN	As informações do cabeçalho inicial são inválidas ou não foram encontradas.
_HEAPBADNODE	Heap danificado ou nó inválido encontrado.
_HEAPBADPTR	O _pentry campo da _HEAPINFO estrutura não contém um ponteiro válido para o heap ou entryinfo é um ponteiro nulo.
_HEAPEND	Fim do heap alcançado com êxito.
_HEAPEMPTY	Heap não inicializado.
_HEAPOK	Nenhum erro até o momento; entryinfo é atualizado com informações sobre a próxima entrada do heap.

Além disso, se ocorrer um erro, _heapwalk definirá errno como ENOSYS.

Comentários

A função _heapwalk ajuda a depurar problemas relacionados ao heap em programas. A função percorre o heap, passando por uma entrada por chamada e retorna um ponteiro para uma estrutura do tipo _HEAPINFO que contém informações sobre a entrada de heap seguinte. O tipo _HEAPINFO, definido em Malloc.h, contém os seguintes elementos.

Campo	Significado
int *_pentry	Ponto de entrada do heap.
size_t _size	Tamanho da entrada do heap.
int _useflag	Sinalizador que indica se a entrada do heap está sendo utilizada.

Uma chamada para _heapwalk que retorna _HEAPOK armazena o tamanho da entrada no campo _size e define o campo _useflag como _FREEENTRY ou _USEDENTRY (ambos são constantes definidas em Malloc.h). Para obter essas informações sobre a primeira entrada no heap, passe _heapwalk um ponteiro para uma estrutura _HEAPINFO cujo membro _pentry é NULL. Se o sistema operacional não for compatível com _heapwalk, a função retornará _HEAPEND e será definida errno como ENOSYS.

Esta função valida seu parâmetro. Se entryinfo for um ponteiro nulo, o manipulador de parâmetro inválido será chamado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, errno será definido como EINVAL e a função retornará _HEAPBADPTR.

Requisitos

Rotina	Cabeçalho necessário	Cabeçalho opcional
_heapwalk	<malloc.h>	<errno.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// 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("%8s 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;
    }
}

    USED block at 00310650 of size 0100
    USED block at 00310758 of size 0800
    USED block at 00310F60 of size 0080
    FREE block at 00310FF0 of size 0398
    USED block at 00311390 of size 000D
    USED block at 003113A8 of size 00B4
    USED block at 00311468 of size 0034
    USED block at 003114A8 of size 0039
...
    USED block at 00312228 of size 0010
    USED block at 00312240 of size 1000
    FREE block at 00313250 of size 1DB0
OK - end of heap

Confira também

Alocação de memória
_heapadd
_heapchk
_heapmin
_heapset