summaryrefslogtreecommitdiffstats
path: root/man3/mtrace.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/mtrace.3')
-rw-r--r--man3/mtrace.3180
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)