fanotify_init.2, fanotify.7: Document FAN_REPORT_TID

[thirdparty/man-pages.git] / man3 / mtrace.3

diff --git a/man3/mtrace.3 b/man3/mtrace.3
index 6b9514c0680ce79860cb32cf05fc64454d7d72aa..ff9f0fc5df846002f26f2d21b928d44ae68c5d8d 100644 (file)
--- a/man3/mtrace.3
+++ b/man3/mtrace.3
@@ -22,14 +22,14 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
-.TH MTRACE 3 2012-04-18 "GNU" "Linux Programmer's Manual"
+.TH MTRACE 3 2017-09-15 "GNU" "Linux Programmer's Manual"
 .SH NAME
 mtrace, muntrace \- malloc tracing
 .SH SYNOPSIS
 .B "#include <mcheck.h>"
-.sp
+.PP
 .B "void mtrace(void);"
-.sp
+.PP
 .B "void muntrace(void);"
 .SH DESCRIPTION
 The
@@ -43,7 +43,7 @@ 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.
-
+.PP
 The
 .BR muntrace ()
 function disables the hook functions installed by
@@ -54,7 +54,7 @@ If no hook functions were successfully installed by
 .BR mtrace (),
 .BR muntrace ()
 does nothing.
-
+.PP
 When
 .BR mtrace ()
 is called, it checks the value of the environment variable
@@ -62,7 +62,7 @@ is called, it checks the value of the environment variable
 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.
-
+.PP
 If
 .BR MALLOC_TRACE
 is not set,
@@ -75,6 +75,28 @@ In set-user-ID and set-group-ID programs,
 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;
+lbw20 lb lb
+l l l.
+Interface      Attribute       Value
+T{
+.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 CONFORMING TO
 These functions are GNU extensions.
 .SH NOTES
@@ -83,7 +105,7 @@ In normal usage,
 is called once at the start of execution of a program, and
 .BR muntrace ()
 is never called.
-
+.PP
 The tracing output produced after a call to
 .BR mtrace ()
 is textual, but not designed to be human readable.
@@ -93,7 +115,7 @@ 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.
-
+.PP
 The tracing performed by
 .BR mtrace ()
 incurs a performance penalty (if
@@ -103,7 +125,7 @@ points to a valid, writable pathname).
 The line-number information produced by
 .BR mtrace (1)
 is not always precise:
-the line number references may refer to the previous or following (non-blank)
+the line number references may refer to the previous or following (nonblank)
 line of the source code.
 .SH EXAMPLE
 The shell session below demonstrates the use of the
@@ -112,9 +134,9 @@ function and the
 .BR mtrace (1)
 command in a program that has memory leaks at two different locations.
 The demonstration uses the following program:
+.PP
 .in +4
-.nf
-
+.EX
 .RB "$ " "cat t_mtrace.c"
 #include <mcheck.h>
 #include <stdlib.h>
@@ -133,15 +155,15 @@ main(int argc, char *argv[])
     calloc(16, 16);             /* Never freed\-\-a memory leak */
     exit(EXIT_SUCCESS);
 }
-
-.fi
+.EE
 .in
+.PP
 When we run the program as follows, we see that
 .BR mtrace ()
 diagnosed memory leaks at two different locations in the program:
+.PP
 .in +4n
-.nf
-
+.EX
 .RB "$ " "cc \-g t_mtrace.c \-o t_mtrace"
 .RB "$ " "export MALLOC_TRACE=/tmp/t"
 .RB "$ " "./t_mtrace"
@@ -152,9 +174,9 @@ Memory not freed:
 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
-.fi
+.EE
 .in
-
+.PP
 The first two messages about unfreed memory correspond to the two
 .BR malloc (3)
 calls inside the