Debian Codegraph @

upstream/fedora-44/man3/mcheck.3

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