Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 181 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man3/mtrace.3 b/upstream/opensuse-tumbleweed/man3/mtrace.3
new file mode 100644
index 00000000..442da6fb
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man3/mtrace.3
@@ -0,0 +1,181 @@
+'\" t
+.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH mtrace 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+mtrace, muntrace \- malloc tracing
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B "#include <mcheck.h>"
+.PP
+.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.
+.PP
+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.
+.PP
+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.
+.PP
+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
+.sp 1
+.\" 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.
+.PP
+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.
+.PP
+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:
+.PP
+.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
+.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
+.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
+.PP
+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)