Next: , Previous: Testing, Up: Using mpatrol

7.7 Library functions

Along with the standard set of C and C++ dynamic memory allocation functions, the mpatrol library also comes with an additional set of functions which can be used to provide additional information to your program, and which can be called at various points in your code for debugging purposes. You must always include the mpatrol.h header file in order to use these functions, but you can check for a specific version of the mpatrol library by checking the MPATROL_VERSION preprocessor macro. You can check the version of the mpatrol library that a program was linked with by calling the __mp_libversion() function.

Certain mpatrol library options can be set after the library has been initialised with the __mp_setoption() function. This allows you to override the default options or those specified in the MPATROL_OPTIONS environment variable from within your code. Not all options can be overridden, however, since they would require a complete reinitialisation of the library — the __mp_setoption() function returns a failure indicator in these cases. You can read the setting of any mpatrol library option with the corresponding function, __mp_getoption().

On systems that support it, global functions (with C linkage) in an executable file or shared library whose names begin with `__mp_init_' will be noted when the mpatrol library first starts up and is reading the symbols. Such functions will then be called as soon as the mpatrol library is initialised, which can be useful if the initialisation occurs before main() is called. These functions must accept no arguments and must return no value. Similar behaviour exists for global functions whose names begin with `__mp_fini_', except that such functions will be executed when the mpatrol library terminates. Note that this feature will have no effect if the symbol table is stripped from the executable file or shared library before the program is run, and the order in which such functions will be called if there are more than one is unspecified. The __mp_atexit() function can also be used to register functions that should be called when the mpatrol library terminates.

It is possible to obtain a great deal of information about an existing memory allocation or free block using the __mp_info() function. This takes an address as an argument and fills in any details about its corresponding memory allocation in a supplied structure. The following example illustrates this (it can be found in tests/pass/test4.c).

      23  /*
      24   * Demonstrates and tests the facility for obtaining information
      25   * about the allocation a specific address belongs to.
      26   */
      29  #include "mpatrol.h"
      30  #include <stdio.h>
      33  void display(void *p)
      34  {
      35      __mp_allocstack *s;
      36      __mp_allocinfo d;
      37      __mp_symbolinfo i;
      39      if (!__mp_info(p, &d) || !d.allocated)
      40      {
      41          fprintf(stderr, "nothing known about address 0x%0*lX\n",
      42                  sizeof(void *) * 2, p);
      43          return;
      44      }
      45      fprintf(stderr, "block:    0x%0*lX\n", sizeof(void *) * 2, d.block);
      46      fprintf(stderr, "size:     %lu\n", d.size);
      47      fprintf(stderr, "type:     %s\n", __mp_function(d.type));
      48      fprintf(stderr, "alloc:    %lu\n", d.alloc);
      49      fprintf(stderr, "realloc:  %lu\n", d.realloc);
      50      fprintf(stderr, "thread:   %lu\n", d.thread);
      51      fprintf(stderr, "event:    %lu\n", d.event);
      52      fprintf(stderr, "func:     %s\n", d.func ? d.func : "<unknown>");
      53      fprintf(stderr, "file:     %s\n", d.file ? d.file : "<unknown>");
      54      fprintf(stderr, "line:     %lu\n", d.line);
      55      for (s = d.stack; s != NULL; s = s->next)
      56      {
      57          fprintf(stderr, "\t0x%0*lX", sizeof(void *) * 2, s->addr);
      58          if (__mp_syminfo(s->addr, &i))
      59          {
      60              if ( != NULL)
      61                  fprintf(stderr, " %s",;
      62              if ((i.addr != NULL) && (i.addr != s->addr))
      63                  fprintf(stderr, "%+ld",
      64                          (char *) s->addr - (char *) i.addr);
      65              if (i.object != NULL)
      66                  fprintf(stderr, " [%s]", i.object);
      67          }
      68          else if (s->name != NULL)
      69              fprintf(stderr, " %s", s->name);
      70          fputc('\n', stderr);
      71      }
      72      fprintf(stderr, "typestr:  %s\n",
      73              d.typestr ? d.typestr : "<unknown>");
      74      fprintf(stderr, "typesize: %lu\n", d.typesize);
      75      fprintf(stderr, "userdata: 0x%0*lX\n", sizeof(void *) * 2, d.userdata);
      76      fputs("flags:   ", stderr);
      77      if (!d.freed && !d.marked && !d.profiled && !d.traced && !d.internal)
      78          fputs(" none\n", stderr);
      79      else
      80      {
      81          if (d.freed)
      82              fputs(" freed", stderr);
      83          if (d.marked)
      84              fputs(" marked", stderr);
      85          if (d.profiled)
      86              fputs(" profiled", stderr);
      87          if (d.traced)
      88              fputs(" traced", stderr);
      89          if (d.internal)
      90              fputs(" internal", stderr);
      91          fputc('\n', stderr);
      92      }
      93  }
      96  void func2(void)
      97  {
      98      void *p;
     100      if (p = malloc(16))
     101      {
     102          display(p);
     103          free(p);
     104      }
     105      display(p);
     106  }
     109  void func1(void)
     110  {
     111      func2();
     112  }
     115  int main(void)
     116  {
     117      func1();
     118      return EXIT_SUCCESS;
     119  }

When this is compiled and run, it should give the following output, although the pointers are likely to be different.

     block:    0x0806A0E8
     size:     16
     type:     malloc
     alloc:    52
     realloc:  0
     thread:   0
     event:    97
     func:     func2
     file:     test4.c
     line:     100
               0x0804A743 func2+35 [./a.out]
               0x0804A790 func1+8 [./a.out]
               0x0804A79C main+8 [./a.out]
               0x4007C9CB __libc_start_main+255 [/lib/]
               0x0804A3E1 _start+33 [./a.out]
     typestr:  <unknown>
     typesize: 0
     userdata: 0x00000000
     flags:    none
     nothing known about address 0x0806A0E8

As you can see, anything that the mpatrol library knows about any memory allocation can be obtained for use in your own code, which can be very useful if you need to write handlers to keep track of memory allocations, etc. for debugging purposes. It can also be useful to have this information when running your program within a debugger, so you can use the __mp_printinfo() function to display information about a heap address if your debugger supports calling functions from the command prompt. Note that the textual representation of the type field returned by the __mp_info() function can be obtained by calling __mp_function().

The mpatrol library records the error code from the most recently encountered warning or error in the __mp_errno global variable. This variable can be read and compared with the known error codes listed in mpatrol.h. It can also be reset to MP_ET_NONE before calling any mpatrol library function in order to check to see if a warning or error was encountered during the call. A string representation of the error message corresponding to any mpatrol error code can be obtained by calling the __mp_strerror() function with the specific code.

The userdata field shown in the previous example can be set for any memory allocation with the __mp_setuser() function. This can have any value and is not interpreted by the mpatrol library. It was added for user code to associate its own data with memory allocations.

The marked field that is also shown in the previous example indicates if a memory allocation has been marked to indicate that it should never be freed. This can only be performed from the source code by calling __mp_setmark() with the address of the memory allocation. Such a memory allocation can be reallocated but never freed, and will not contribute to the list of memory leaks. It will also be profiled and traced as freed by the end of program execution if memory allocation profiling or tracing is enabled.

You may also have noticed the use of __mp_syminfo() in the above example. This function is very similar to the __mp_info() function except that instead of looking for the details of a memory allocation at a specific address, it looks for the details of a function symbol at that address. This provides user access to the data obtained by the mpatrol symbol handler, including line number information if the USEDEBUG option is supported and used.

It is also possible for you to be able to intercept calls to allocate, reallocate and deallocate memory for your own purposes. You can install prologue and epilogue functions that the mpatrol library will call before and after every time one of its functions is called. These can be used for additional tracing or simply to add extra checks to your code. The following code is an example of this and can be found in tests/pass/test2.c.

     23  /*
     24   * Demonstrates and tests the facility for specifying user-defined
     25   * prologue and epilogue functions.
     26   */
     29  #include "mpatrol.h"
     30  #include <stdio.h>
     33  __mp_prologuehandler old_prologue;
     34  __mp_epiloguehandler old_epilogue;
     37  void prologue(MP_CONST void *p, size_t l, size_t m, MP_CONST char *s,
     38                MP_CONST char *t, unsigned long u, MP_CONST void *a)
     39  {
     40      if (old_prologue != NULL)
     41          old_prologue(p, l, m, s, t, u, a);
     42      if (p == (void *) -1)
     43          fprintf(stderr, "allocating %lu bytes\n", l);
     44      else if (l == (size_t) -1)
     45          fprintf(stderr, "freeing allocation 0x%0*lX\n", sizeof(void *) * 2, p);
     46      else if (l == (size_t) -2)
     47          fprintf(stderr, "duplicating string `%s'\n", p);
     48      else
     49          fprintf(stderr, "reallocating allocation 0x%0*lX to %lu bytes\n",
     50                  sizeof(void *) * 2, p, l);
     51  }
     54  void epilogue(MP_CONST void *p, MP_CONST char *s, MP_CONST char *t,
     55                unsigned long u, MP_CONST void *a)
     56  {
     57      if (p != (void *) -1)
     58          fprintf(stderr, "allocation returns 0x%0*lX\n", sizeof(void *) * 2, p);
     59      if (old_epilogue != NULL)
     60          old_epilogue(p, s, t, u, a);
     61  }
     64  int main(void)
     65  {
     66      void *p, *q;
     68      old_prologue = __mp_prologue(prologue);
     69      old_epilogue = __mp_epilogue(epilogue);
     70      if (p = malloc(16))
     71          if (q = realloc(p, 32))
     72              free(q);
     73          else
     74              free(p);
     75      if (p = (char *) strdup("test"))
     76          free(p);
     77      __mp_prologue(old_prologue);
     78      __mp_epilogue(old_epilogue);
     79      return EXIT_SUCCESS;
     80  }

Once again, if you compile and run the above code, you should see the following output.

     allocating 16 bytes
     allocation returns 0x0806A0E8
     reallocating allocation 0x0806A0E8 to 32 bytes
     allocation returns 0x0806A0E8
     freeing allocation 0x0806A0E8
     duplicating string `test'
     allocation returns 0x0806A0E5
     freeing allocation 0x0806A0E5

Note that in the above code, the previous prologue and epilogue functions were recorded and called. If this is not done then your prologue and epilogue functions will completely override all others, which is not usually the expected behaviour. In case you're wondering what the last four arguments of the prologue and epilogue handlers are, they are the function name, file name, line number and call address of the function that called malloc() or a related function. These can be used in the handlers to see where they were called from.

Along with being able to install prologue and epilogue functions, you can also install a low-memory handler with the __mp_nomemory() function, which will be called by the mpatrol library if it ever runs out of memory during the call to a memory allocation function. This gives you the opportunity to use that handler to either free up any unneeded memory or simply to abort, thus removing the need to check for failed allocations. Note that the low-memory handler also accepts the same four common arguments that the prologue and epilogue handlers do.

It is also possible to iterate over all of the allocated and freed memory allocations that are currently in the heap at any point in a program. This is done by invoking the __mp_iterate() function with a callback function which is called once per allocation with the start address of the memory block being passed as the argument to the callback function. Any further information about the memory allocation can then be obtained via the __mp_info() function. Note that the __mp_iterateall() function does the same as the __mp_iterate() function except that it also includes all free memory blocks and memory allocations that are internal to the mpatrol library.

Differences in the heap allocations (their details, not their contents) between a previous point in a program's execution and the current point of execution can be determined by calling the __mp_snapshot() function and then invoking __mp_iterate() with that snapshot value as its second argument at a later point in execution. The callback function passed to __mp_iterate() will then only be invoked with the start address of any memory allocation that has been allocated or reallocated (or freed if the NOFREE option is being used) since the snapshot point. This makes it possible to detect localised memory leaks very easily, as the following example (found in tests/pass/test10.c) shows.

      23  /*
      24   * Demonstrates and tests the facility for obtaining information on
      25   * local memory leaks.  Will also edit or list the location of each
      26   * leak if the EDIT or LIST option is in effect.
      27   */
      30  #include "mpatrol.h"
      31  #include <stdio.h>
      34  int callback(MP_CONST void *p, void *t)
      35  {
      36      __mp_allocstack *s;
      37      __mp_allocinfo d;
      39      if (!__mp_info(p, &d) || !d.allocated)
      40      {
      41          fprintf(stderr, "nothing known about address 0x%0*lX\n",
      42                  sizeof(void *) * 2, p);
      43          return -1;
      44      }
      45      if (!d.freed)
      46      {
      47          fprintf(stderr, "0x%0*lX", sizeof(void *) * 2, d.block);
      48          fprintf(stderr, " %s", d.func ? d.func : "<unknown>");
      49          fprintf(stderr, " %s", d.file ? d.file : "<unknown>");
      50          fprintf(stderr, " %lu", d.line);
      51          for (s = d.stack; s != NULL; s = s->next)
      52          {
      53              if (s == d.stack)
      54                  fputs(" (", stderr);
      55              else
      56                  fputs("->", stderr);
      57              if (s->name != NULL)
      58                  fprintf(stderr, "%s", s->name);
      59              else
      60                  fprintf(stderr, "0x%0*lX", sizeof(void *) * 2, s->addr);
      61              if (s->next == NULL)
      62                  fputc(')', stderr);
      63          }
      64          fputc('\n', stderr);
      65          if ((d.file != NULL) && (d.line != 0))
      66              __mp_view(d.file, d.line);
      67          *((unsigned long *) t) = *((unsigned long *) t) + d.size;
      68          return 1;
      69      }
      70      return 0;
      71  }
      74  void func2(unsigned long n)
      75  {
      76      void *p;
      78      p = malloc((n * 10) + 1);
      79      if (n % 13)
      80          free(p);
      81  }
      84  void func1(void)
      85  {
      86      void *p;
      87      size_t i, n;
      88      unsigned long s, t;
      90      p = malloc(16);
      91      s = __mp_snapshot();
      92      for (i = 0; i < 128; i++)
      93          func2(i);
      94      free(p);
      95      t = 0;
      96      if (n = __mp_iterate(callback, &t, s))
      97          fprintf(stderr, "Detected %lu memory leaks (%lu bytes)\n", n, t);
      98      if ((n != 10) || (t != 5860))
      99          fputs("Expected 10 memory leaks (5860 bytes)\n", stderr);
     100  }
     103  int main(void)
     104  {
     105      void *p;
     107      p = malloc(16);
     108      func1();
     109      free(p);
     110      return EXIT_SUCCESS;
     111  }

Compiling this example with mpatrol and then running it will produce the following list of memory leaks that were located between the points of calling __mp_snapshot() and __mp_iterate().

     0x0806A108 func2 test10.c 78 (func2->func1->main->_start)
     0x0806A674 func2 test10.c 78 (func2->func1->main->_start)
     0x0806A6F8 func2 test10.c 78 (func2->func1->main->_start)
     0x0806A800 func2 test10.c 78 (func2->func1->main->_start)
     0x0806A988 func2 test10.c 78 (func2->func1->main->_start)
     0x0806AB94 func2 test10.c 78 (func2->func1->main->_start)
     0x0806AE20 func2 test10.c 78 (func2->func1->main->_start)
     0x0806B130 func2 test10.c 78 (func2->func1->main->_start)
     0x0806B4C0 func2 test10.c 78 (func2->func1->main->_start)
     0x0806B8D4 func2 test10.c 78 (func2->func1->main->_start)
     Detected 10 memory leaks (5860 bytes)

The tools directory in the mpatrol distribution contains two files called heapdiff.c and heapdiff.h which demonstrate the use of __mp_snapshot() and __mp_iterate() to find localised memory leaks. Have a look at these files to see a further example of using these functions, or perhaps even add these files to your application for debugging purposes. Note that it is perfectly safe to allocate memory in the callback function used by __mp_iterate(), and such allocations can be freed as well. The only restriction is that the callback function should never free a memory allocation that it has not allocated itself.

An alternative way to detect differences in the heap between two points in a program's execution is to make use of the leak table. This is a hash table that stores the number and size of memory allocations and deallocations referenced by the source file and line number where they occur1. The leak table can be cleared with a call to __mp_clearleaktable() and can be displayed with a call to __mp_leaktable(), which will display a sorted summary of the allocated, freed or unfreed memory entries stored in the leak table. Memory allocation events can be automatically logged in the leak table by calling __mp_startleaktable() but this behaviour can be disabled by calling __mp_stopleaktable(). Additional entries can be manually added to the leak table with __mp_addallocentry() and __mp_addfreeentry().

If you wish to write your own diagnostics to the mpatrol log file from within your source code then you can do so with the __mp_printf() and __mp_vprintf() functions, which are the functional equivalents of printf() and vprintf(). They prefix every line written to the log file with `>', partly for making it clear where user diagnostics occur and partly to avoid problems with external utilities that parse the mpatrol log file. The __mp_locprintf() and __mp_vlocprintf() functions are equivalent functions that also display the source file and line number from where they were called along with a stack trace, if available.

It is also possible to write out a memory dump in hexadecimal format, a stack trace at the current point in execution and details of a memory allocation to the log file in standard format using the __mp_logmemory(), __mp_logstack() and __mp_logaddr() functions respectively.

You can also take advantage of the mpedit command from within the mpatrol library with the __mp_edit(), __mp_list() and __mp_view() functions. The first invokes a text editor on a specified file and line number, while the second displays a context listing of a file at a given line number. The third function performs either or neither depending on the setting of the EDIT or LIST options.

Finally, there are four functions which affect the mpatrol library globally. The first, __mp_check(), allows you to force an internal check of the mpatrol library's data structures at any point during program execution and also to free up any out of scope memory allocations made by the alloca() family of functions. The __mp_memorymap() function allows you to force the generation of a memory map at any point in your program, in much the same way as it would normally be displayed at the end of program execution if the SHOWMAP option was used. The __mp_summary() function writes library statistics to the mpatrol log file, while the __mp_stats() function fills in a data structure with selected statistics for examination in user code.


[1] If that information is not available then the function name or return address will be used instead.