Debian Codegraph @

upstream/debian-unstable/man3/malloc_hook.3

raw
1 .\" Copyright 2002, Walter Harms <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .\"
6 .TH __malloc_hook 3 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 __malloc_hook, __malloc_initialize_hook,
9 __memalign_hook, __free_hook, __realloc_hook,
10 __after_morecore_hook \- malloc debugging variables (DEPRECATED)
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B "#include <malloc.h>"
17 .P
18 .BI "typeof(void *(size_t " size ", const void *" caller ))
19 .B " *volatile __malloc_hook;"
20 .P
21 .BI "typeof(void *(void *" p ", size_t " size ", const void *" caller ))
22 .B " *volatile __realloc_hook;"
23 .P
24 .BI "typeof(void *(size_t " align ", size_t " size ", const void *" caller ))
25 .B " *volatile __memalign_hook;"
26 .P
27 .BI "typeof(void *(void *" p ", const void *" caller ))
28 .B " *volatile __free_hook;"
29 .P
30 .B "typeof(void (void)) *__malloc_initialize_hook;"
31 .B "typeof(void (void)) *volatile __after_mrecore_hook;"
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 .P
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 .P
51 .in +4n
52 .EX
53 typeof(void (void)) *__malloc_initialize_hook = my_init_hook;
54 .EE
55 .in
56 .P
57 Now the function
58 .IR my_init_hook ()
59 can do the initialization of all hooks.
60 .P
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 .P
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 STANDARDS
83 GNU.
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 and from glibc 2.34 onwards, all
91 the hook variables have been removed from the API.
92 .\" https://bugzilla.redhat.com/show_bug.cgi?id=450187
93 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=9957
94 Programmers should instead preempt calls to the relevant functions
95 by defining and exporting
96 .BR malloc (),
97 .BR free (),
98 .BR realloc (),
99 and
100 .BR calloc ().
101 .SH EXAMPLES
102 Here is a short example of how to use these variables.
103 .P
104 .EX
105 #include <stdio.h>
106 #include <malloc.h>
107 \&
108 /* Prototypes for our hooks */
109 static void my_init_hook(void);
110 static void *my_malloc_hook(size_t, const void *);
111 \&
112 /* Variables to save original hooks */
113 static typeof(void *(size_t, const void *)) *old_malloc_hook;
114 \&
115 /* Override initializing hook from the C library */
116 typeof(void (void)) *__malloc_initialize_hook = my_init_hook;
117 \&
118 static void
119 my_init_hook(void)
120 {
121 old_malloc_hook = __malloc_hook;
122 __malloc_hook = my_malloc_hook;
123 }
124 \&
125 static void *
126 my_malloc_hook(size_t size, const void *caller)
127 {
128 void *result;
129 \&
130 /* Restore all old hooks */
131 __malloc_hook = old_malloc_hook;
132 \&
133 /* Call recursively */
134 result = malloc(size);
135 \&
136 /* Save underlying hooks */
137 old_malloc_hook = __malloc_hook;
138 \&
139 /* printf() might call malloc(), so protect it too */
140 printf("malloc(%zu) called from %p returns %p\[rs]n",
141 size, caller, result);
142 \&
143 /* Restore our own hooks */
144 __malloc_hook = my_malloc_hook;
145 \&
146 return result;
147 }
148 .EE
149 .SH SEE ALSO
150 .BR mallinfo (3),
151 .BR malloc (3),
152 .BR mcheck (3),
153 .BR mtrace (3)