diff options
Diffstat (limited to 'man/man3/mtrace.3')
| -rw-r--r-- | man/man3/mtrace.3 | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/man/man3/mtrace.3 b/man/man3/mtrace.3 new file mode 100644 index 0000000..d332cc1 --- /dev/null +++ b/man/man3/mtrace.3 @@ -0,0 +1,180 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mtrace 3 2024-05-02 "Linux man-pages (unreleased)" +.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) |