man3/malloc_hook.3

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