_uheap_walk - Return Information about Memory Heap

Syntax

#include <umalloc.h>
int _uheap_walk(Heap_t heap, int (*callback_fn)(const void *object,
                     size_t size, int flag, int status,
                     const char* file, int line) );

Description

• uheap_walk traverses the heap you specify, and, for each allocated or freed object, it calls the callback_fn function that you provide. _uheap_walk works just like _heap_walk, except that you specify the heap to be traversed; _heap_walk always traverses the default heap.

  For each object, _uheap_walk passes your function:

  object

  A pointer to the object.
  size
  The size of the object.
  flag
  The value _USEDENTRY, if the object is currently allocated, or _FREEENTRY, if the object has been freed. (Both values are defined in <malloc.h>.)
  status
  One of the following values, defined in both <umalloc.h> and <malloc.h>, depending on the status of the object:
  • HEAPBADBEGIN
    The heap specified is not valid. It may have been closed or destroyed.
    _HEAPBADNODE
    A memory node is corrupted, or the heap is damaged.
    _HEAPEMPTY
    The heap has not been initialized.
    _HEAPOK
    The heap appears to be consistent.
    file
    The name of the file where the object was allocated or freed.
    line
    The line where the object was allocated or freed.

  • uheap_walk provides information about all objects, regardless of which memory management functions were used to allocate them. However, the file and line information are only available if the object was allocated and freed using the debug versions of the memory management functions. Otherwise, file is NULL and line is 0.

    _uheap_walk calls callback_fn for each object until one of the following occurs:

    • All objects have been traversed. 
      callback_fn returns a nonzero value to _heap_walk.
      
      It cannot continue because of a problem with the heap.

      You may want to code your callback_fn to return a nonzero value if the status of the object is not _HEAPOK. Even if callback_fn returns 0 for an object that is corrupted, _heap_walk cannot continue because of the state of the heap and returns to its caller.

      You can use callback_fn to process information from _uheap_walk in various ways. For example, you may want to print the information to a file, or use it to generate your own error messages. You can use the information to look for memory leaks and objects incorrectly allocated or freed from the heap. It can be especially useful to call _uheap_walk when _uheapchk returns an error.

      Note:

      • Using the _uheapchk, _uheapset, and _uheap_walk functions (and their equivalents for the default heap) may add overhead to each object allocated from the heap

      • uheap_walk locks the heap while it traverses it, to ensure that no other operations use the heap until _uheap_walk finishes. As a result, in your callback_fn, you cannot call any critical functions in the run-time library, either explicitly or by calling another function that calls a critical function. See the VisualAge C++ Programming Guide for a list of critical functions.

    Returns

    • uheap_walk returns the last value of status to the caller.
    Example Code

    This example creates a heap and performs memory operations on it. _uheap_walk then traverses the heap and calls callback_function for each memory object. The callback_function prints a message about each memory block.

    #include <stdlib.h>#include <stdio.h>
    #include <umalloc.h>
    
    int callback_function(const void *pentry, size_t sz, int useflag, int status,
                          const char *filename, size_t line)
    {
       if (_HEAPOK != status) {
          puts("status is not _HEAPOK.");
          exit(status);
       }
       if (_USEDENTRY == useflag)
          printf("allocated  %p     %u\n", pentry, sz);
       else
          printf("freed      %p     %u\n", pentry, sz);
       return 0;
    }
    

    int main(void)
    {
       Heap_t  myheap;
       char    *p1, *p2, *p3;
    
       /* User default heap as user heap */
       myheap = _udefault(NULL);
    
       if (NULL == (p1 = _umalloc(myheap, 100)) ||
           NULL == (p2 = _umalloc(myheap, 200)) ||
           NULL == (p3 = _umalloc(myheap, 300))) {
          puts("Cannot allocate memory from user heap.");
          exit(EXIT_FAILURE);
       }
       free(p2);
       puts("usage      address   size\n-----      -------   ----");
    
       _uheap_walk(myheap, callback_function);
    
       free(p1);
       free(p3);
       return 0;
    
       /****************************************************************************
          The output should be similar to :
    
          usage      address   size
          -----      -------   ----
          allocated  73A20     300
          allocated  738C0     100
           :
           :
          freed      73930     224
       ****************************************************************************/
    }
    

    Related Information

    • heapmin
      
    • heap_walk
      
    • uheapchk
      
    • uheapset
      
    • Managing Memory" in the VisualAge C++ Programming Guide
      
    • Debugging Your Heaps" in the VisualAge C++ Programming Guide

    ---

    [Back: _uheapset - Validate and Set Memory Heap]
    [Next: _ultoa - Convert Unsigned Long Integer to String]