search..
No manual entry for -- in section 3
mtrace(3)		    Library Functions Manual		      mtrace(3)

NAME
       mtrace, muntrace - malloc tracing

LIBRARY
       Standard C library (libc, -lc)

SYNOPSIS
       #include <mcheck.h>

       void mtrace(void);
       void muntrace(void);

DESCRIPTION
       The  mtrace() function installs hook functions for the memory-allocation
       functions (malloc(3),  realloc(3)  memalign(3),	free(3)).   These  hook
       functions record tracing information about memory allocation and deallo-
       cation.	 The  tracing  information can be used to discover memory leaks
       and attempts to free nonallocated memory in a program.

       The  muntrace()	function  disables  the	 hook  functions  installed  by
       mtrace(), so that tracing information is no longer recorded for the mem-
       ory-allocation  functions.   If	no hook functions were successfully in-
       stalled by mtrace(), muntrace() does nothing.

       When mtrace() is called, it checks the value of the environment variable
       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.

       If MALLOC_TRACE is not set, or the pathname it specifies is  invalid  or
       not  writable, then no hook functions are installed, and mtrace() has no
       effect.	In set-user-ID and set-group-ID programs, MALLOC_TRACE	is  ig-
       nored, and mtrace() has no effect.

ATTRIBUTES
       For an explanation of the terms used in this section, see attributes(7).
       +------------------------------------------+---------------+-----------+
       | Interface				  | Attribute	  | Value     |
       +------------------------------------------+---------------+-----------+
       | mtrace(), muntrace()			  | Thread safety | MT-Unsafe |
       +------------------------------------------+---------------+-----------+

STANDARDS
       GNU.

NOTES
       In  normal usage, mtrace() is called once at the start of execution of a
       program, and muntrace() is never called.

       The tracing output produced after a call to mtrace() is textual, but not
       designed to be human readable.	The  GNU  C  library  provides	a  Perl
       script,	mtrace(1),  that  interprets  the trace log and produces human-
       readable output.	 For best results, the traced program  should  be  com-
       piled  with  debugging  enabled,	 so  that  line-number	information  is
       recorded in the executable.

       The tracing performed by mtrace() incurs a performance penalty (if  MAL-
       LOC_TRACE points to a valid, writable pathname).

BUGS
       The line-number information produced by mtrace(1) is not always precise:
       the  line number references may refer to the previous or following (non-
       blank) line of the source code.

EXAMPLES
       The shell session below demonstrates the use of	the  mtrace()  function
       and the mtrace(1) command in a program that has memory leaks at two dif-
       ferent locations.  The demonstration uses the following program:

	   $ cat t_mtrace.c
	   #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);
	   }

       When  we run the program as follows, we see that mtrace() diagnosed mem-
       ory leaks at two different locations in the program:

	   $ cc -g t_mtrace.c -o t_mtrace
	   $ export MALLOC_TRACE=/tmp/t
	   $ ./t_mtrace
	   $ 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

       The first two messages about unfreed memory correspond to the  two  mal-
       loc(3)  calls inside the for loop.  The final message corresponds to the
       call to calloc(3) (which in turn calls malloc(3)).

SEE ALSO
       mtrace(1), malloc(3), malloc_hook(3), mcheck(3)

Linux man-pages 6.9.1		   2024-05-02			      mtrace(3)