Debian Codegraph @

upstream/fedora-44/man3/malloc_hook.3

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