man3/malloc_hook.3

   1 .\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\"
   3 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   4 .\" Distributed under GPL
   5 .\" %%%LICENSE_END
   6 .\"
   7 .\" Heavily based on glibc documentation
   8 .\" Polished, added docs, removed glibc doc bug, 2002-07-20, aeb
   9 .\"
  10 .TH MALLOC_HOOK 3 2016-07-17 "GNU" "Linux Programmer's Manual"
  11 .SH NAME
  12 __malloc_hook, __malloc_initialize_hook,
  13 __memalign_hook, __free_hook, __realloc_hook,
  14 __after_morecore_hook \- malloc debugging variables
  15 .SH SYNOPSIS
  16 .nf
  17 .B "#include <malloc.h>"
  18 .PP
  19 .BI "void *(*__malloc_hook)(size_t " size ", const void *" caller );
  20 .PP
  21 .BI "void *(*__realloc_hook)(void *" ptr ", size_t " size \
  22 ", const void *" caller );
  23 .PP
  24 .BI "void *(*__memalign_hook)(size_t " alignment ", size_t " size ,
  25 .BI "                         const void *" caller );
  26 .PP
  27 .BI "void (*__free_hook)(void *" ptr ", const void *" caller );
  28 .PP
  29 .B "void (*__malloc_initialize_hook)(void);"
  30 .PP
  31 .B "void (*__after_morecore_hook)(void);"
  32 .fi
  33 .SH DESCRIPTION
  34 The GNU C library lets you modify the behavior of
  35 .BR malloc (3),
  36 .BR realloc (3),
  37 and
  38 .BR free (3)
  39 by specifying appropriate hook functions.
  40 You can use these hooks
  41 to help you debug programs that use dynamic memory allocation,
  42 for example.
  43 .LP
  44 The variable
  45 .B __malloc_initialize_hook
  46 points at a function that is called once when the malloc implementation
  47 is initialized.
  48 This is a weak variable, so it can be overridden in
  49 the application with a definition like the following:
  50 .nf
  51
  52     void (*__malloc_initialize_hook)(void) = my_init_hook;
  53
  54 .fi
  55 Now the function
  56 .IR my_init_hook ()
  57 can do the initialization of all hooks.
  58 .LP
  59 The four functions pointed to by
  60 .BR __malloc_hook ,
  61 .BR __realloc_hook ,
  62 .BR __memalign_hook ,
  63 .B __free_hook
  64 have a prototype like the functions
  65 .BR malloc (3),
  66 .BR realloc (3),
  67 .BR memalign (3),
  68 .BR free (3),
  69 respectively, except that they have a final argument
  70 .I caller
  71 that gives the address of the caller of
  72 .BR malloc (3),
  73 etc.
  74 .LP
  75 The variable
  76 .B __after_morecore_hook
  77 points at a function that is called each time after
  78 .BR sbrk (2)
  79 was asked for more memory.
  80 .SH CONFORMING TO
  81 These functions are GNU extensions.
  82 .SH NOTES
  83 The use of these hook functions is not safe in multithreaded programs,
  84 and they are now deprecated.
  85 From glibc 2.24 onwards, the
  86 .B __malloc_initialize_hook
  87 variable has been removed from the API.
  88 .\" https://bugzilla.redhat.com/show_bug.cgi?id=450187
  89 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=9957
  90 Programmers should instead preempt calls to the relevant functions
  91 by defining and exporting functions such as "malloc" and "free".
  92 .SH EXAMPLE
  93 Here is a short example of how to use these variables.
  94 .sp
  95 .nf
  96 #include <stdio.h>
  97 #include <malloc.h>
  98
  99 /* Prototypes for our hooks.  */
 100 static void my_init_hook(void);
 101 static void *my_malloc_hook(size_t, const void *);
 102
 103 /* Variables to save original hooks. */
 104 static void *(*old_malloc_hook)(size_t, const void *);
 105
 106 /* Override initializing hook from the C library. */
 107 void (*__malloc_initialize_hook) (void) = my_init_hook;
 108
 109 static void
 110 my_init_hook(void)
 111 {
 112     old_malloc_hook = __malloc_hook;
 113     __malloc_hook = my_malloc_hook;
 114 }
 115
 116 static void *
 117 my_malloc_hook(size_t size, const void *caller)
 118 {
 119     void *result;
 120
 121     /* Restore all old hooks */
 122     __malloc_hook = old_malloc_hook;
 123
 124     /* Call recursively */
 125     result = malloc(size);
 126
 127     /* Save underlying hooks */
 128     old_malloc_hook = __malloc_hook;
 129
 130     /* printf() might call malloc(), so protect it too. */
 131     printf("malloc(%u) called from %p returns %p\\n",
 132             (unsigned int) size, caller, result);
 133
 134     /* Restore our own hooks */
 135     __malloc_hook = my_malloc_hook;
 136
 137     return result;
 138 }
 139 .fi
 140 .SH SEE ALSO
 141 .BR mallinfo (3),
 142 .BR malloc (3),
 143 .BR mcheck (3),
 144 .BR mtrace (3)