diff options
Diffstat (limited to 'man3/mcheck.3')
| -rw-r--r-- | man3/mcheck.3 | 214 |
1 files changed, 0 insertions, 214 deletions
diff --git a/man3/mcheck.3 b/man3/mcheck.3 deleted file mode 100644 index 9d24aaf0a..000000000 --- a/man3/mcheck.3 +++ /dev/null @@ -1,214 +0,0 @@ -'\" t -.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH mcheck 3 (date) "Linux man-pages (unreleased)" -.SH NAME -mcheck, mcheck_check_all, mcheck_pedantic, mprobe \- heap consistency checking -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <mcheck.h> -.PP -.BI "int mcheck(void (*" abortfunc ")(enum mcheck_status " mstatus )); -.BI "int mcheck_pedantic(void (*" abortfunc ")(enum mcheck_status " mstatus )); -.B void mcheck_check_all(void); -.PP -.BI "enum mcheck_status mprobe(void *" ptr ); -.fi -.SH DESCRIPTION -The -.BR mcheck () -function installs a set of debugging hooks for the -.BR malloc (3) -family of memory-allocation functions. -These hooks cause certain consistency checks to be performed -on the state of the heap. -The checks can detect application errors such as freeing a block of memory -more than once or corrupting the bookkeeping data structures -that immediately precede a block of allocated memory. -.PP -To be effective, the -.BR mcheck () -function must be called before the first call to -.BR malloc (3) -or a related function. -In cases where this is difficult to ensure, linking the program with -.I \-lmcheck -inserts an implicit call to -.BR mcheck () -(with a NULL argument) -before the first call to a memory-allocation function. -.PP -The -.BR mcheck_pedantic () -function is similar to -.BR mcheck (), -but performs checks on all allocated blocks whenever -one of the memory-allocation functions is called. -This can be very slow! -.PP -The -.BR mcheck_check_all () -function causes an immediate check on all allocated blocks. -This call is effective only if -.BR mcheck () -is called beforehand. -.PP -If the system detects an inconsistency in the heap, -the caller-supplied function pointed to by -.I abortfunc -is invoked with a single argument, -.IR mstatus , -that indicates what type of inconsistency was detected. -If -.I abortfunc -is NULL, a default function prints an error message on -.I stderr -and calls -.BR abort (3). -.PP -The -.BR mprobe () -function performs a consistency check on -the block of allocated memory pointed to by -.IR ptr . -The -.BR mcheck () -function should be called beforehand (otherwise -.BR mprobe () -returns -.BR MCHECK_DISABLED ). -.PP -The following list describes the values returned by -.BR mprobe () -or passed as the -.I mstatus -argument when -.I abortfunc -is invoked: -.TP -.BR MCHECK_DISABLED " (" mprobe "() only)" -.BR mcheck () -was not called before the first memory allocation function was called. -Consistency checking is not possible. -.TP -.BR MCHECK_OK " (" mprobe "() only)" -No inconsistency detected. -.TP -.B MCHECK_HEAD -Memory preceding an allocated block was clobbered. -.TP -.B MCHECK_TAIL -Memory following an allocated block was clobbered. -.TP -.B -MCHECK_FREE -A block of memory was freed twice. -.SH RETURN VALUE -.BR mcheck () -and -.BR mcheck_pedantic () -return 0 on success, or \-1 on error. -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.ad l -.nh -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.BR mcheck (), -.BR mcheck_pedantic (), -.BR mcheck_check_all (), -.BR mprobe () -T} Thread safety T{ -MT-Unsafe race:mcheck -const:malloc_hooks -T} -.TE -.hy -.ad -.sp 1 -.SH STANDARDS -GNU. -.SH HISTORY -.TP -.BR mcheck_pedantic () -.TQ -.BR mcheck_check_all () -glibc 2.2. -.TP -.BR mcheck () -.TQ -.BR mprobe () -glibc 2.0. -.SH NOTES -Linking a program with -.I \-lmcheck -and using the -.B MALLOC_CHECK_ -environment variable (described in -.BR mallopt (3)) -cause the same kinds of errors to be detected. -But, using -.B MALLOC_CHECK_ -does not require the application to be relinked. -.\" But is MALLOC_CHECK_ slower? -.SH EXAMPLES -The program below calls -.BR mcheck () -with a NULL argument and then frees the same block of memory twice. -The following shell session demonstrates what happens -when running the program: -.PP -.in +4n -.EX -.RB "$" " ./a.out" -About to free -\& -About to free a second time -block freed twice -Aborted (core dumped) -.EE -.in -.SS Program source -\& -.\" SRC BEGIN (mcheck.c) -.EX -#include <mcheck.h> -#include <stdio.h> -#include <stdlib.h> -\& -int -main(void) -{ - char *p; -\& - if (mcheck(NULL) != 0) { - fprintf(stderr, "mcheck() failed\en"); -\& - exit(EXIT_FAILURE); - } -\& - p = malloc(1000); -\& - fprintf(stderr, "About to free\en"); - free(p); - fprintf(stderr, "\enAbout to free a second time\en"); - free(p); -\& - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.BR malloc (3), -.BR mallopt (3), -.BR mtrace (3) |