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 2021-03-22 "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 *(*volatile __malloc_hook)(size_t " size ", const void *" caller );
  20 .PP
  21 .BI "void *(*volatile __realloc_hook)(void *" ptr ", size_t " size \
  22 ", const void *" caller );
  23 .PP
  24 .BI "void *(*volatile __memalign_hook)(size_t " alignment ", size_t " size ,
  25 .BI "                         const void *" caller );
  26 .PP
  27 .BI "void (*volatile __free_hook)(void *" ptr ", const void *" caller );
  28 .PP
  29 .B "void (*__malloc_initialize_hook)(void);"
  30 .PP
  31 .B "void (*volatile __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 .PP
  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 .PP
  51 .in +4n
  52 .EX
  53 void (*__malloc_initialize_hook)(void) = my_init_hook;
  54 .EE
  55 .in
  56 .PP
  57 Now the function
  58 .IR my_init_hook ()
  59 can do the initialization of all hooks.
  60 .PP
  61 The four functions pointed to by
  62 .BR __malloc_hook ,
  63 .BR __realloc_hook ,
  64 .BR __memalign_hook ,
  65 .B __free_hook
  66 have a prototype like the functions
  67 .BR malloc (3),
  68 .BR realloc (3),
  69 .BR memalign (3),
  70 .BR free (3),
  71 respectively, except that they have a final argument
  72 .I caller
  73 that gives the address of the caller of
  74 .BR malloc (3),
  75 etc.
  76 .PP
  77 The variable
  78 .B __after_morecore_hook
  79 points at a function that is called each time after
  80 .BR sbrk (2)
  81 was asked for more memory.
  82 .SH CONFORMING TO
  83 These functions are GNU extensions.
  84 .SH NOTES
  85 The use of these hook functions is not safe in multithreaded programs,
  86 and they are now deprecated.
  87 From glibc 2.24 onwards, the
  88 .B __malloc_initialize_hook
  89 variable has been removed from the API.
  90 .\" https://bugzilla.redhat.com/show_bug.cgi?id=450187
  91 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=9957
  92 Programmers should instead preempt calls to the relevant functions
  93 by defining and exporting functions such as "malloc" and "free".
  94 .SH EXAMPLES
  95 Here is a short example of how to use these variables.
  96 .PP
  97 .EX
  98 #include <stdio.h>
  99 #include <malloc.h>
 100
 101 /* Prototypes for our hooks */
 102 static void my_init_hook(void);
 103 static void *my_malloc_hook(size_t, const void *);
 104
 105 /* Variables to save original hooks */
 106 static void *(*old_malloc_hook)(size_t, const void *);
 107
 108 /* Override initializing hook from the C library */
 109 void (*__malloc_initialize_hook)(void) = my_init_hook;
 110
 111 static void
 112 my_init_hook(void)
 113 {
 114     old_malloc_hook = __malloc_hook;
 115     __malloc_hook = my_malloc_hook;
 116 }
 117
 118 static void *
 119 my_malloc_hook(size_t size, const void *caller)
 120 {
 121     void *result;
 122
 123     /* Restore all old hooks */
 124     __malloc_hook = old_malloc_hook;
 125
 126     /* Call recursively */
 127     result = malloc(size);
 128
 129     /* Save underlying hooks */
 130     old_malloc_hook = __malloc_hook;
 131
 132     /* printf() might call malloc(), so protect it too */
 133     printf("malloc(%zu) called from %p returns %p\en",
 134             size, caller, result);
 135
 136     /* Restore our own hooks */
 137     __malloc_hook = my_malloc_hook;
 138
 139     return result;
 140 }
 141 .EE
 142 .SH SEE ALSO
 143 .BR mallinfo (3),
 144 .BR malloc (3),
 145 .BR mcheck (3),
 146 .BR mtrace (3)