`_heapwalk`

Статья
04/03/2023

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

Внимание

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

Синтаксис

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, функция возвращает _HEAPEND и задает errno значение ENOSYS.

Эта функция проверяет свои параметры. Если entryinfo имеет значение NULL, вызывается обработчик недопустимых параметров, как описано в разделе "Проверка параметров". Если выполнение может быть продолжено, для 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("%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

См. также

Распределение памяти
_heapadd
_heapchk
_heapmin
_heapset

Поделиться через