original/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 2010-10-13 "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 .sp
  19 .BI "void *(*__malloc_hook)(size_t " size ", const void *" caller );
  20 .sp
  21 .BI "void *(*__realloc_hook)(void *" ptr ", size_t " size \
  22 ", const void *" caller );
  23 .sp
  24 .BI "void *(*__memalign_hook)(size_t " alignment ", size_t " size ,
  25 .BI "                         const void *" caller );
  26 .sp
  27 .BI "void (*__free_hook)(void *" ptr ", const void *" caller );
  28 .sp
  29 .B "void (*__malloc_initialize_hook)(void);"
  30 .sp
  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 .\" https://bugzilla.redhat.com/show_bug.cgi?id=450187
  86 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=9957
  87 Programmers should instead preempt calls to the relevant functions
  88 by defining and exporting functions such as "malloc" and "free".
  89 .SH EXAMPLE
  90 Here is a short example of how to use these variables.
  91 .sp
  92 .nf
  93 #include <stdio.h>
  94 #include <malloc.h>
  95
  96 /* Prototypes for our hooks.  */
  97 static void my_init_hook(void);
  98 static void *my_malloc_hook(size_t, const void *);
  99
 100 /* Variables to save original hooks. */
 101 static void *(*old_malloc_hook)(size_t, const void *);
 102
 103 /* Override initializing hook from the C library. */
 104 void (*__malloc_initialize_hook) (void) = my_init_hook;
 105
 106 static void
 107 my_init_hook(void)
 108 {
 109     old_malloc_hook = __malloc_hook;
 110     __malloc_hook = my_malloc_hook;
 111 }
 112
 113 static void *
 114 my_malloc_hook(size_t size, const void *caller)
 115 {
 116     void *result;
 117
 118     /* Restore all old hooks */
 119     __malloc_hook = old_malloc_hook;
 120
 121     /* Call recursively */
 122     result = malloc(size);
 123
 124     /* Save underlying hooks */
 125     old_malloc_hook = __malloc_hook;
 126
 127     /* printf() might call malloc(), so protect it too. */
 128     printf("malloc(%u) called from %p returns %p\\n",
 129             (unsigned int) size, caller, result);
 130
 131     /* Restore our own hooks */
 132     __malloc_hook = my_malloc_hook;
 133
 134     return result;
 135 }
 136 .fi
 137 .SH SEE ALSO
 138 .BR mallinfo (3),
 139 .BR malloc (3),
 140 .BR mcheck (3),
 141 .BR mtrace (3)
 142 .SH COLOPHON
 143 This page is part of release 3.68 of the Linux
 144 .I man-pages
 145 project.
 146 A description of the project,
 147 information about reporting bugs,
 148 and the latest version of this page,
 149 can be found at
 150 \%http://www.kernel.org/doc/man\-pages/.