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