man3/mcheck.3

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