_heapwalk

Статья
06/09/2015

Обходит кучу и возвращает сведения о следующей записи.

Важно!

Этот API нельзя использовать в приложениях, выполняемых в среде выполнения Windows, за исключением отладочных версий.Дополнительные сведения см. в статье Функции CRT, которые не поддерживаются с ключом /ZW.

int _heapwalk( 
   _HEAPINFO *entryinfo 
);

Параметры

entryinfo
Буфер, который будет содержать данные кучи.

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

_heapwalk возвращает одну из следующих целочисленных констант манифеста, определенных в Malloc.h.

_HEAPBADBEGIN
Начальные сведения о заголовке не найдены или недопустимы.
_HEAPBADNODE
Куча повреждена или обнаружен плохой узел.
_HEAPBADPTR
Поле _pentry структуры _HEAPINFO не содержит допустимый указатель на кучу или entryinfo — нулевой указатель.
_HEAPEND
Успешно достигнут конец кучи.
_HEAPEMPTY
Куча еще не инициализирована.
_HEAPOK
Без ошибок до сих пор; entryinfo обновляется информацией о следующей записи кучи.

Кроме того, при возникновении ошибки _heapwalk устанавливает errno в ENOSYS.

Заметки

Функция _heapwalk помогает при отладке проблем в программе, связанных с кучей. Функция проходит через кучу, обходя одну запись при каждом вызове, и возвращает указатель на структуру типа _HEAPINFO, содержащую сведения о следующей записи кучи. Тип _HEAPINFO, определенный в Malloc.h, содержит следующие элементы.

int *_pentry
Указатель записи кучи.
size_t _size
Размер записи кучи.
int _useflag
Флаг, указывающий, используется ли запись кучи.

Вызов _heapwalk, возвращающий _HEAPOK, сохраняет размер записи в поле _size и устанавливает поле _useflag либо в _FREEENTRY, либо в _USEDENTRY (обе константы определенны в Malloc.h). Для доступа к этой информации о первой записи в куче следует передать в _heapwalk указатель на структуру _HEAPINFO, в которой член _pentry установлен в NULL. Если операционная система не поддерживает _heapwalk(например, Windows 98), функция возвращает _HEAPEND и устанавливает errno в ENOSYS.

Эта функция проверяет свой параметр. Если entryinfo является пустым указателем, то вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если продолжение выполнения разрешено, то errno устанавливается в EINVAL, и функция возвращает _HEAPBADPTR.

Требования

Подпрограмма	Обязательный заголовок	Необязательный заголовок
_heapwalk	<malloc.h>	<errno.h>

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

// 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;
    }
}