diff options
Diffstat (limited to 'man3/mtrace.3')
| -rw-r--r-- | man3/mtrace.3 | 180 |
1 files changed, 0 insertions, 180 deletions
diff --git a/man3/mtrace.3 b/man3/mtrace.3 deleted file mode 100644 index 61e8251..0000000 --- a/man3/mtrace.3 +++ /dev/null @@ -1,180 +0,0 @@ -'\" t -.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH mtrace 3 2024-02-26 "Linux man-pages 6.7" -.SH NAME -mtrace, muntrace \- malloc tracing -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B "#include <mcheck.h>" -.P -.B "void mtrace(void);" -.B "void muntrace(void);" -.fi -.SH DESCRIPTION -The -.BR mtrace () -function installs hook functions for the memory-allocation functions -.RB ( malloc (3), -.BR realloc (3) -.BR memalign (3), -.BR free (3)). -These hook functions record tracing information about memory allocation -and deallocation. -The tracing information can be used to discover memory leaks and -attempts to free nonallocated memory in a program. -.P -The -.BR muntrace () -function disables the hook functions installed by -.BR mtrace (), -so that tracing information is no longer recorded -for the memory-allocation functions. -If no hook functions were successfully installed by -.BR mtrace (), -.BR muntrace () -does nothing. -.P -When -.BR mtrace () -is called, it checks the value of the environment variable -.BR MALLOC_TRACE , -which should contain the pathname of a file in which -the tracing information is to be recorded. -If the pathname is successfully opened, it is truncated to zero length. -.P -If -.B MALLOC_TRACE -is not set, -or the pathname it specifies is invalid or not writable, -then no hook functions are installed, and -.BR mtrace () -has no effect. -In set-user-ID and set-group-ID programs, -.B MALLOC_TRACE -is ignored, and -.BR mtrace () -has no effect. -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.na -.nh -.BR mtrace (), -.BR muntrace () -T} Thread safety MT-Unsafe -.TE -.\" FIXME: The marking is different from that in the glibc manual, -.\" markings in glibc manual are more detailed: -.\" -.\" mtrace: MT-Unsafe env race:mtrace const:malloc_hooks init -.\" muntrace: MT-Unsafe race:mtrace const:malloc_hooks locale -.\" -.\" But there is something wrong in glibc manual, for example: -.\" glibc manual says muntrace should have marking locale because it calls -.\" fprintf(), but muntrace does not execute area which cause locale problem. -.SH STANDARDS -GNU. -.SH NOTES -In normal usage, -.BR mtrace () -is called once at the start of execution of a program, and -.BR muntrace () -is never called. -.P -The tracing output produced after a call to -.BR mtrace () -is textual, but not designed to be human readable. -The GNU C library provides a Perl script, -.BR mtrace (1), -that interprets the trace log and produces human-readable output. -For best results, -the traced program should be compiled with debugging enabled, -so that line-number information is recorded in the executable. -.P -The tracing performed by -.BR mtrace () -incurs a performance penalty (if -.B MALLOC_TRACE -points to a valid, writable pathname). -.SH BUGS -The line-number information produced by -.BR mtrace (1) -is not always precise: -the line number references may refer to the previous or following (nonblank) -line of the source code. -.SH EXAMPLES -The shell session below demonstrates the use of the -.BR mtrace () -function and the -.BR mtrace (1) -command in a program that has memory leaks at two different locations. -The demonstration uses the following program: -.P -.in +4n -.RB "$ " "cat t_mtrace.c" -.\" SRC BEGIN (t_mtrace.c) -.EX -#include <mcheck.h> -#include <stdio.h> -#include <stdlib.h> -\& -int -main(void) -{ - mtrace(); -\& - for (unsigned int j = 0; j < 2; j++) - malloc(100); /* Never freed\-\-a memory leak */ -\& - calloc(16, 16); /* Never freed\-\-a memory leak */ - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.in -.P -When we run the program as follows, we see that -.BR mtrace () -diagnosed memory leaks at two different locations in the program: -.P -.in +4n -.EX -.RB "$ " "cc \-g t_mtrace.c \-o t_mtrace" -.RB "$ " "export MALLOC_TRACE=/tmp/t" -.RB "$ " "./t_mtrace" -.RB "$ " "mtrace ./t_mtrace $MALLOC_TRACE" -Memory not freed: --\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - Address Size Caller -0x084c9378 0x64 at /home/cecilia/t_mtrace.c:12 -0x084c93e0 0x64 at /home/cecilia/t_mtrace.c:12 -0x084c9448 0x100 at /home/cecilia/t_mtrace.c:16 -.EE -.in -.P -The first two messages about unfreed memory correspond to the two -.BR malloc (3) -calls inside the -.I for -loop. -The final message corresponds to the call to -.BR calloc (3) -(which in turn calls -.BR malloc (3)). -.SH SEE ALSO -.BR mtrace (1), -.BR malloc (3), -.BR malloc_hook (3), -.BR mcheck (3) |