man3/mcheck.3

   1 '\" t
   2 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH mcheck 3 (date) "Linux man-pages (unreleased)"
   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(void (*" abortfunc ")(enum mcheck_status " mstatus ));
  17 .BI "int mcheck_pedantic(void (*" abortfunc ")(enum mcheck_status " mstatus ));
  18 .B void mcheck_check_all(void);
  19 .P
  20 .BI "enum mcheck_status mprobe(void *" ptr );
  21 .fi
  22 .SH DESCRIPTION
  23 The
  24 .BR mcheck ()
  25 function installs a set of debugging hooks for the
  26 .BR malloc (3)
  27 family of memory-allocation functions.
  28 These hooks cause certain consistency checks to be performed
  29 on the state of the heap.
  30 The checks can detect application errors such as freeing a block of memory
  31 more than once or corrupting the bookkeeping data structures
  32 that immediately precede a block of allocated memory.
  33 .P
  34 To be effective, the
  35 .BR mcheck ()
  36 function must be called before the first call to
  37 .BR malloc (3)
  38 or a related function.
  39 In cases where this is difficult to ensure, linking the program with
  40 .I \-lmcheck
  41 inserts an implicit call to
  42 .BR mcheck ()
  43 (with a NULL argument)
  44 before the first call to a memory-allocation function.
  45 .P
  46 The
  47 .BR mcheck_pedantic ()
  48 function is similar to
  49 .BR mcheck (),
  50 but performs checks on all allocated blocks whenever
  51 one of the memory-allocation functions is called.
  52 This can be very slow!
  53 .P
  54 The
  55 .BR mcheck_check_all ()
  56 function causes an immediate check on all allocated blocks.
  57 This call is effective only if
  58 .BR mcheck ()
  59 is called beforehand.
  60 .P
  61 If the system detects an inconsistency in the heap,
  62 the caller-supplied function pointed to by
  63 .I abortfunc
  64 is invoked with a single argument,
  65 .IR mstatus ,
  66 that indicates what type of inconsistency was detected.
  67 If
  68 .I abortfunc
  69 is NULL, a default function prints an error message on
  70 .I stderr
  71 and calls
  72 .BR abort (3).
  73 .P
  74 The
  75 .BR mprobe ()
  76 function performs a consistency check on
  77 the block of allocated memory pointed to by
  78 .IR ptr .
  79 The
  80 .BR mcheck ()
  81 function should be called beforehand (otherwise
  82 .BR mprobe ()
  83 returns
  84 .BR MCHECK_DISABLED ).
  85 .P
  86 The following list describes the values returned by
  87 .BR mprobe ()
  88 or passed as the
  89 .I mstatus
  90 argument when
  91 .I abortfunc
  92 is invoked:
  93 .TP
  94 .BR MCHECK_DISABLED " (" mprobe "() only)"
  95 .BR mcheck ()
  96 was not called before the first memory allocation function was called.
  97 Consistency checking is not possible.
  98 .TP
  99 .BR MCHECK_OK " (" mprobe "() only)"
 100 No inconsistency detected.
 101 .TP
 102 .B MCHECK_HEAD
 103 Memory preceding an allocated block was clobbered.
 104 .TP
 105 .B MCHECK_TAIL
 106 Memory following an allocated block was clobbered.
 107 .TP
 108 .B
 109 MCHECK_FREE
 110 A block of memory was freed twice.
 111 .SH RETURN VALUE
 112 .BR mcheck ()
 113 and
 114 .BR mcheck_pedantic ()
 115 return 0 on success, or \-1 on error.
 116 .SH ATTRIBUTES
 117 For an explanation of the terms used in this section, see
 118 .BR attributes (7).
 119 .TS
 120 allbox;
 121 lbx lb lb
 122 l l l.
 123 Interface       Attribute       Value
 124 T{
 125 .na
 126 .nh
 127 .BR mcheck (),
 128 .BR mcheck_pedantic (),
 129 .BR mcheck_check_all (),
 130 .BR mprobe ()
 131 T}      Thread safety   T{
 132 .na
 133 .nh
 134 MT-Unsafe race:mcheck
 135 const:malloc_hooks
 136 T}
 137 .TE
 138 .SH STANDARDS
 139 GNU.
 140 .SH HISTORY
 141 .TP
 142 .BR mcheck_pedantic ()
 143 .TQ
 144 .BR mcheck_check_all ()
 145 glibc 2.2.
 146 .TP
 147 .BR mcheck ()
 148 .TQ
 149 .BR mprobe ()
 150 glibc 2.0.
 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 .P
 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 .\" [[memory leak]] SRC BEGIN (mcheck.c)
 183 .EX
 184 #include <mcheck.h>
 185 #include <stdio.h>
 186 #include <stdlib.h>
 187 \&
 188 int
 189 main(void)
 190 {
 191     char *p;
 192 \&
 193     if (mcheck(NULL) != 0) {
 194         fprintf(stderr, "mcheck() failed\en");
 195 \&
 196         exit(EXIT_FAILURE);
 197     }
 198 \&
 199     p = malloc(1000);
 200 \&
 201     fprintf(stderr, "About to free\en");
 202     free(p);
 203     fprintf(stderr, "\enAbout to free a second time\en");
 204     free(p);
 205 \&
 206     exit(EXIT_SUCCESS);
 207 }
 208 .EE
 209 .\" SRC END
 210 .SH SEE ALSO
 211 .BR malloc (3),
 212 .BR mallopt (3),
 213 .BR mtrace (3)