Debian Codegraph @

upstream/debian-unstable/man3/mcheck.3

raw
1 '\" t
2 .\" Copyright 2012, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH mcheck 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mcheck, mcheck_check_all, mcheck_pedantic, mprobe \- heap consistency checking
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <mcheck.h>
16 .P
17 .BI "int mcheck(typeof(void (enum mcheck_status " mstatus ")) *" f );
18 .B "int mcheck_pedantic("
19 .BI " typeof(void (enum mcheck_status " mstatus ")) *" f );
20 .B void mcheck_check_all(void);
21 .P
22 .BI "enum mcheck_status mprobe(void *" ptr );
23 .fi
24 .SH DESCRIPTION
25 The
26 .BR mcheck ()
27 function installs a set of debugging hooks for the
28 .BR malloc (3)
29 family of memory-allocation functions.
30 These hooks cause certain consistency checks to be performed
31 on the state of the heap.
32 The checks can detect application errors such as freeing a block of memory
33 more than once or corrupting the bookkeeping data structures
34 that immediately precede a block of allocated memory.
35 .P
36 To be effective, the
37 .BR mcheck ()
38 function must be called before the first call to
39 .BR malloc (3)
40 or a related function.
41 In cases where this is difficult to ensure, linking the program with
42 .I \-lmcheck
43 inserts an implicit call to
44 .BR mcheck ()
45 (with a NULL argument)
46 before the first call to a memory-allocation function.
47 .P
48 The
49 .BR mcheck_pedantic ()
50 function is similar to
51 .BR mcheck (),
52 but performs checks on all allocated blocks whenever
53 one of the memory-allocation functions is called.
54 This can be very slow!
55 .P
56 The
57 .BR mcheck_check_all ()
58 function causes an immediate check on all allocated blocks.
59 This call is effective only if
60 .BR mcheck ()
61 is called beforehand.
62 .P
63 If the system detects an inconsistency in the heap,
64 the caller-supplied function pointed to by
65 .I f
66 is invoked with a single argument,
67 .IR mstatus ,
68 that indicates what type of inconsistency was detected.
69 If
70 .I f
71 is NULL, a default function prints an error message on
72 .I stderr
73 and calls
74 .BR abort (3).
75 .P
76 The
77 .BR mprobe ()
78 function performs a consistency check on
79 the block of allocated memory pointed to by
80 .IR ptr .
81 The
82 .BR mcheck ()
83 function should be called beforehand (otherwise
84 .BR mprobe ()
85 returns
86 .BR MCHECK_DISABLED ).
87 .P
88 The following list describes the values returned by
89 .BR mprobe ()
90 or passed as the
91 .I mstatus
92 argument when
93 .I f
94 is invoked:
95 .TP
96 .BR MCHECK_DISABLED " (" mprobe "() only)"
97 .BR mcheck ()
98 was not called before the first memory allocation function was called.
99 Consistency checking is not possible.
100 .TP
101 .BR MCHECK_OK " (" mprobe "() only)"
102 No inconsistency detected.
103 .TP
104 .B MCHECK_HEAD
105 Memory preceding an allocated block was clobbered.
106 .TP
107 .B MCHECK_TAIL
108 Memory following an allocated block was clobbered.
109 .TP
110 .B
111 MCHECK_FREE
112 A block of memory was freed twice.
113 .SH RETURN VALUE
114 .BR mcheck ()
115 and
116 .BR mcheck_pedantic ()
117 return 0 on success, or \-1 on error.
118 .SH ATTRIBUTES
119 For an explanation of the terms used in this section, see
120 .BR attributes (7).
121 .TS
122 allbox;
123 lbx lb lb
124 l l l.
125 Interface Attribute Value
126 T{
127 .na
128 .nh
129 .BR mcheck (),
130 .BR mcheck_pedantic (),
131 .BR mcheck_check_all (),
132 .BR mprobe ()
133 T} Thread safety T{
134 .na
135 .nh
136 MT-Unsafe race:mcheck
137 const:malloc_hooks
138 T}
139 .TE
140 .SH STANDARDS
141 GNU.
142 .SH HISTORY
143 .TP
144 .BR mcheck_pedantic ()
145 .TQ
146 .BR mcheck_check_all ()
147 glibc 2.2.
148 .TP
149 .BR mcheck ()
150 .TQ
151 .BR mprobe ()
152 glibc 2.0.
153 .SH NOTES
154 Linking a program with
155 .I \-lmcheck
156 and using the
157 .B MALLOC_CHECK_
158 environment variable (described in
159 .BR mallopt (3))
160 cause the same kinds of errors to be detected.
161 But, using
162 .B MALLOC_CHECK_
163 does not require the application to be relinked.
164 .\" But is MALLOC_CHECK_ slower?
165 .SH EXAMPLES
166 The program below calls
167 .BR mcheck ()
168 with a NULL argument and then frees the same block of memory twice.
169 The following shell session demonstrates what happens
170 when running the program:
171 .P
172 .in +4n
173 .EX
174 .RB "$" " ./a.out"
175 About to free
176 \&
177 About to free a second time
178 block freed twice
179 Aborted (core dumped)
180 .EE
181 .in
182 .SS Program source
183 \&
184 .\" SRC BEGIN (mcheck.c)
185 .EX
186 #include <mcheck.h>
187 #include <stdio.h>
188 #include <stdlib.h>
189 \&
190 int
191 main(void)
192 {
193 char *p;
194 \&
195 if (mcheck(NULL) != 0) {
196 fprintf(stderr, "mcheck() failed\[rs]n");
197 \&
198 exit(EXIT_FAILURE);
199 }
200 \&
201 p = malloc(1000);
202 \&
203 fprintf(stderr, "About to free\[rs]n");
204 free(p);
205 fprintf(stderr, "\[rs]nAbout to free a second time\[rs]n");
206 free(p);
207 \&
208 exit(EXIT_SUCCESS);
209 }
210 .EE
211 .\" SRC END
212 .SH SEE ALSO
213 .BR malloc (3),
214 .BR mallopt (3),
215 .BR mtrace (3)