_heapwalk

Artigo
06/09/2015

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

Importante

Essa API não pode ser usada em aplicativos executados no Tempo de Execução do Windows, exceto em compilações de Depuração.Para obter mais informações, consulte Funções CRT sem suporte pelo /ZW.

int _heapwalk( 
   _HEAPINFO *entryinfo 
);

Parâmetros

entryinfo
Buffer para conter informações acumuladas.

Valor de retorno

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

_HEAPBADBEGIN
Informações de cabeçalho inicial inválidas ou não encontradas.
_HEAPBADNODE
Heap danificada ou nó incorreto encontrado.
_HEAPBADPTR
O campo _pentry da estrutura de _HEAPINFO não contém um ponteiro válido no heap ou entryinfo é um ponteiro nulo.
_HEAPEND
O fim da heap foi alcançado com êxito.
_HEAPEMPTY
Heap não inicializada.
_HEAPOK
Nenhum erros até o momento; entryinfo é atualizado com informações sobre a próxima entrada da heap.

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

Comentários

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

int *_pentry
Ponteiro de entrada de heap.
size_t _size
Tamanho da entrada do heap.
int _useflag
Sinalizador que indica se a entrada da heap está em uso.

Uma chamada para _heapwalk que retorna _HEAPOK armazena o tamanho da entrada no campo _size e define o campo _useflag como _FREEENTRY ou _USEDENTRY (as duas constantes definidas em Malloc.h). Para obter essas informações sobre a primeira entrada no heap, passe _heapwalk a um ponteiro para uma estrutura _HEAPINFO cujo membro _pentry é NULL. Se o sistema operacional não oferecer suporte a _heapwalk(por exemplo, Windows 98), a função retorna _HEAPEND e define errno como ENOSYS.

Essa função valida seu parâmetro. Se entryinfo for um ponteiro nulo, o manipulador de parâmetro inválido será chamado, como descrito em Validação do parâmetro. Se a execução puder 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 mais 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("%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;
    }
}