mtrace-ng.1

.\" -*-nroff-*-
.\" Copyright (c) 2015 Stefani Seibold <stefani@seibold.net>
.\"
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of the
.\" License, or (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
.\" 02110-1301 USA
.\"
.TH MTRACE "12" "Oct 2015" "" "User Commands"
.SH NAME
mtrace-ng \- A dynamic memory allocation tracer
.SH SYNOPSIS
.\"
.\" ---------------------------------------------------------------------------
.\"
.PP
.BR mtrace-ng " \-t|\-\-trace
.\"
.\" Output formatting:
.\"
[\-d|\-\-depth \fIlevel\fR]
[\-F|\-\-config \fIfilename\fR]
[\-S|\-\-sort \fIoption\fR]
[\-o|\-\-output \fIfilename\fR]
.\"
.\" Various:
.\"
[\-a|\-\-autoscan]
[\-b|\-\-binpath \fIpath\fR]
[\-C|\-\-cwd \fIpath\fR]
[\-D|\-\-debug \fImask\fR]
[\-i|\-\-interactive]
[\-l|\-\-logfile \fIfilename\fR]
[\-L|\-\-long]
[\-n|\-\-nocpp]
[\-N|\-\-nohwbp]
[\-S|\-\-sanity]
[\-O|\-\-omit \fIfilename\fR]
[\-u|\-\-user \fIusername\fR]
[\-v|\-\-verbose]
.\"
.\" What processes to trace:
.\"
[\-e|\-\-follow\-exec]
[\-f|\-\-follow\-fork]
[\-p|\-\-pid \fIpid\fR]
[[\-\-] \fIcommand [arg ...]\fR]
.\"
.\" ---------------------------------------------------------------------------
.\"
.PP
.BR mtrace-ng " \-t|\-\-trace \-r|\-\-remote \fIaddr\fR"
[\-P|\-\-port \fInum\fR]
[\-w|\-\-wait]
.\"
.\" Output formatting:
.\"
[\-d|\-\-depth \fIlevel\fR]
.\"
.\" Various:
.\"
[\-C|\-\-cwd \fIpath\fR]
[\-D|\-\-debug \fImask\fR]
[\-l|\-\-logfile \fIfilename\fR]
[\-L|\-\-long]
[\-n|\-\-nocpp]
[\-N|\-\-nohwbp]
[\-S|\-\-sanity]
[\-O|\-\-omit \fIfilename\fR]
[\-u|\-\-user \fIusername\fR]
[\-v|\-\-verbose]
.\"
.\" What processes to trace:
.\"
[\-e|\-\-follow\-exec]
[\-f|\-\-follow\-fork]
[\-p|\-\-pid \fIpid\fR]
[[\-\-] \fIcommand [arg ...]\fR]
.\"
.\" ---------------------------------------------------------------------------
.\"
.PP
.BR mtrace-ng
[\-r|\-\-remote \fIaddr\fR]
[\-P|\-\-port \fInum\fR]
.\"
.\" Output formatting:
.\"
[\-F|\-\-config \fIfilename\fR]
[\-S|\-\-sort \fIoption\fR]
[\-o|\-\-output \fIfilename\fR]
.\"
.\" Various:
.\"
[\-a|\-\-autoscan]
[\-b|\-\-binpath \fIpath\fR]
[\-D|\-\-debug \fImask\fR]
[\-i|\-\-interactive]
[\-l|\-\-logfile \fIfilename\fR]
[\-v|\-\-verbose]
.\"
.\" ---------------------------------------------------------------------------
.\"
.PP
.BR mtrace-ng " \-V|\-\-version"
.PP
.BR mtrace-ng " \-h|\-\-help"
.SH DESCRIPTION
.B mtrace-ng
is a dynamic memory tracer, debugger and statistical analyses tool for C and
C++.  It traces, records and reports all dynamic memory functions which are
called by the specified
.I command
or
.I process
until it exits or
.B mtrace-ng
is terminated.

Unlike other memory tracers, the trace will be performed by setting
breakpoints on each know dynamic allocation function.  So no additional
library nor any kind of instrumentation or recompiling is needed to trace
and hunt for memory leaks.

.B mtrace-ng
is able to find no longer referenced memory allocation by scanning all
writable memory mappings of the program against the pointer of an allocation.
If the memory address will be not found during a scan there is a high change
for a missing reference and therefore for a memory leak.

The following functions will be intercepted:

.in +4
.nf
void *malloc(size_t size);
void free(void *ptr);
void *calloc(size_t nmemb, size_t size);
void *realloc(void *ptr, size_t size);
int posix_memalign(void **memptr, size_t alignment, size_t size);
void *aligned_alloc(size_t alignment, size_t size);
void *valloc(size_t size);
void *memalign(size_t alignment, size_t size);
void *pvalloc(size_t size);
void cfree(void *ptr);
void *mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset);
void *mmap64(void *addr, size_t length, int prot, int flags, int fd, off_t offset);
int munmap(void *addr, size_t length);
void *mremap(void *old_address, size_t old_size, size_t new_size, int flags, ... /* void *new_address */);

void *operator new(size_t size) throw (std::bad_alloc)
void *operator new(size_t size, const std::nothrow_t& nt) __THROW
void *operator new[](size_t size) throw (std::bad_alloc)
void *operator new[](size_t size, const std::nothrow_t& nt) __THROW
void operator delete(void* p) __THROW
void operator delete(void* p, const std::nothrow_t& nt) __THROW
void operator delete[](void* p) __THROW
void operator delete[](void* p, const std::nothrow_t& nt) __THROW
void operator delete(void*, unsigned long)
void operator delete[](void*, unsigned long)
.fi
.in
.PP
.B mtrace-ng
offers three different kind of working modes.  A non interactive mode, a
server mode and a interactive client mode.

The most common mode is the non interactive mode, which allows to run
and/or attach to a process, similar to strace.
.B mtrace-ng
will show all open allocations when the traced program exists or
.B mtrace-ng
will be terminated.

For system with memory restrictions or for using in a cross architecture
environment,
.B mtrace-ng
offers a server mode which moves the memory bookkeeping and address resolution
outside to a connected client.  In this case the server must be started on
target system where the program is executed.  Then the client has to be started
on the remote host system.

To get a more detailed information about the dynamic memory consumption
.B mtrace-ng
can be started in an interactive mode.  This mode is available for client
mode or when attaching to a process.  See the section \fBINTERACTIVE MODE\fR
to learn more about the interactive commands in
\fBmtrace-ng\fR.
.SH OPTIONS
.PP
.IP "\-a, \-\-autoscan"
Scan all writeable memory mappings of the process for leaked pointers on exit
of the traced program or termination of \fBmtrace-ng\fR.  If the pointer value of an
open allocated memory block will be not found on any aligned memory addresses,
it will be marked and reported as leaked.  The scan can take some time,
depending on the size of the writeable memory mappings and the number of open
allocations.
.IP "\-b, \-\-binpath \fIpath\fR"
Set the binary search path.  This option is mostly needed for remote cross
architecture trace and tells the client where to find the binaries or
libraries.  The client tries to locate the binaries by adding the remote path
of the binary to the search path.  If the binary is not found it will strip
down the leading directory of the remote path and try again until no more
leading directory is found.  It is possible to add several binary search paths
by passing more than one \-b option.
.IP "\-c, \-\-cwd \fIpath\fR"
This option is valid in any mode except the client mode.  Its used for locating
libraries for an attached process which are linked with relative paths.  In this
case
.B mtrace-ng
does not know the origin state of the current working directory and need
to manually add this information.
.IP "\-D, \-\-debug \fImask\fR"
Show debugging output of
.B mtrace-ng
itself.  \fImask\fR is a number
describing which debug messages should be displayed.  Use the \-Dh option
to see what can be used.  This option is only available when
.B mtrace-ng
was build with --enable-debug.
.IP "\-d, \-\-depth \fIlevel\fR"
Do backtrace of \fIlevel\fR stack frames for each memory allocation function.
.IP "\-e, \-\-follow-exec"
Trace processes as they are created by one of the currently traced processes as
a result of execve(2) system call.
.IP "\-f, \-\-follow-fork"
Trace child processes as they are created by one of the currently traced
processes as a result of the fork(2) system call.
.IP "\-F, \-\-config \fIpath"
Set the config file.  For a detailed description of this file see
mtrace-ng.conf(5).  It is possible to pass several config files by passing more
than one \-F option.  If no -F is given,
.B mtrace-ng
will look up for one of the default files in the following order:
$HOME/.mtrace-ng,
$XDG_CONFIG_HOME/mtrace-ng,
SYSCONFDIR/mtrace-ng.conf,
/etc/mtrace-ng.conf
.IP "\-h, \-\-help"
Show a summary of the options to \fBmtrace-ng\fR and exit.
.IP "\-i, \-\-interactive"
Enables the interactive mode for client or when attaching to a process.  See
the section \fBINTERACTIVE MODE\fR to learn more about the interactive commands
in this mode.
.IP "\-k, \-\-kill"
Kill \fBmtrace-ng\fR in case of a bookkeeping error.  This options is intended for
.B mtrace-ng
development only!
.IP "\-O, \-\-omit \fIfilename"
Do not place any dynamic memory interception breakpoints in the given file.
This is usefull when a library offers memory allocation functions which does
only forward the calls.  Use of this option can improve the trace performace in
this case.  It is possible to omit several files by passing more than one
\-O option.
.IP "\-o, \-\-output \fIfilename"
Write the trace output to the file \fIfilename\fR rather than to stderr.  When
passing this option the output will be written in reserve order in opposite the
stderr output.  So the highest value of the sort order is at the beginning of
the file and the lowest at the end of the file.
.IP "\-l, \-\-logfile \fIfilename"
Use a given logfile instead of a socket connection.  In trace mode all data will
be written into the logfile.  In the non trace mode the data will be retrieved
from the logfile.  This option can improve the performance of the trace
since the trace will be split into to different actions.
.IP "\-L, \-\-long"
Do a long dump which includes map file as well.
.IP "\-n, \-\-nocpp"
Disable the trace of C++ allocation operators.  This is safe and faster for libstdc++,
since this library does call malloc() and free() inside the allocation operators.
.IP "\-N, \-\-nohwbp"
Disable the usage of hardware breakpoints. This options is intended for some
virtual machines, where hardware breakpoints do not work well.
.IP "\-p, \-\-pid \fIpid"
Attach to the process with the process ID \fIpid\fR and begin tracing.
This option can be used together with passing a command to execute.
It is possible to attach to several processes by passing more than one
\-p option.
.IP "\-P, \-\-port \fInum"
Set the port number for client or server mode.  The default port number is 4576.
.IP "\-r, \-\-remote \fIaddr"
Run \fBmtrace-ng\fR in remote mode.  Use \fIaddr\fR as socket path or address.  If
\fIaddr\fR begins with / or . it will assumed a named socket, otherwise it
will be passed to getaddrinfo(3), which handles any kind of hostname, IPv4 or
IPv6 addresses.  If this option is passed in conjunction with -t, mtrace-ng will be
execute in server mode, otherwise in client mode.
.IP "\-s, \-\-sortby keyword"
Sort the output of the stack backtraces by keyword.  Valid keywords are:

.RS
\fIallocations\fR
.RS
Sort by the number of open allocations.
.RE
.RE
.RS
\fIaverage\fR
.RS
Sort by the number of average allocations (number of bytes in used / number of open allocations).
.RE
.RE
.RS
\fIbadfree\fR
.RS
Sort by number of bad free releases (only useful with \-S option).
.RE
.RE
.RS
\fIbytes-leaked\fR
.RS
Sort by number of bytes leaked (only useful with \-a option).
.RE
.RE
.RS
\fImismatched\fR
.RS
Sort by number of mismatched releases (only useful with \-S option).
.RE
.RE
.RS
\fIleaks\fR
.RS
Sort by number of leaked allocations (only useful with \-a option).
.RE
.RE
.RS
\fIstacks\fR
.RS
Like \fIallocations\fR but show also all stack backtraces with zero open allocations.
.RE
.RE
.RS
\fItotal\fR
.RS
Sort by the total number of allocations.
.RE
.RE
.RS
\fItsc\fR
.RS
Sort by the pseudo time stamp counter.  Each stack backtrace will get an incremented counter value.
.RE
.RE
.RS
\fIusage\fR
.RS
Sort by number of bytes in use of all open allocations.
.RE
.RE
.IP "\-S, \-\-sanity"
Check mismatching operations against new/delete or free releases. This options
also sets the sort-by options to mismatched if no other sort option was set.
.IP "\-t, \-\-trace"
Run \fBmtrace-ng\fR in trace mode.  In this mode all attached processes will run under
the control of \fBmtrace-ng\fR and all dynamic memory function calls will be traced.
If this options is not given, \fBmtrace-ng\fR will run in client mode.
.IP "\-u, \-\-user \fIusername\fR"
Run command with the userid, groupid and supplementary groups of
.IR username .
This option is only useful when running as root and enables the
correct execution of setuid and/or setgid binaries.
.IP "\-v, \-\-verbose"
Be verbose and display more details about what going on.  This option can be
repeated for a more detailed view.
.IP "\-V, \-\-version"
Show the version number of \fBmtrace-ng\fR and exit.
.IP "\-w, \-\-wait"
This option stops the execution of the traced processes until a client is
connected to the server.  So this option is only valid in server mode.
.SH INTERACTIVE MODE

The interactive mode offers a command line interface, which allows to gather
different kind of debug statistics during the runtime and after termination of
the traced program.  Due the use of readline it offers auto completion by
using the TAB key.  The following commands are available:

.in +4
.nf
dump
help
proclist
quit
reset
scan
set
show
start
status
stop
.fi
.in
.PP

.IP "dump \fIsortby\fR \fIpid\fR \fI>filename\fR"
The dump command allows to output the current state of the memory bookkeeping
at any time.  It accepts a maximum of three parameters:

.RS
\fIsortby\fR
.RS
Sort the output of dump by the keyword.  The keyword is the same as for the
\-S option (\fIallocations, \fIaverage\fR, \fIbadfree\fR \fIbytes-leaked\fR, \fIleaks\fR,
\fImismatched\fR, \fIstacks\fR, \fItotal\fR, \fItsc\fR and \fIusage\fR).  See
\-S option for more details about the sortby keywords.  The default sort order
is \fIallocations\fR when no sortby parameter is used.
.RE
.RE
.RS
\fIpid\fR
.RS
Process Id.  When no process Id is specified the lowest pid of all currently
traced processes will be used as default.
.RE
.RE
.RS
\fI>filename\fR
.RS
Write the output to a file.  When the parameter is omitted it will paging the
dump output.
.RE
.RE

.IP "help \fIcommand\fR"
Shows the help text for a given command.  If no command parameter is passed, it
will show all available commands.

.IP "proclist"
Shows the list of currently traced processes.

.IP "quit"
Close the client connection and exit the
.B mtrace-ng
debugger.

.IP "reset \fIpid\fR"
Reset the bookkeeping of a given process Id.

.IP "scan \fIpid\fR \fImode\fR"
Scan for memory leaks for a given process Id.  The scan operation can be only
performed when tracing is running.  \fImode\fR is one of the following keywords:

.RS
\fIall\fR
.RS
Scan all open allocations for leaking.
.RE
.RE
.RS
\fIleak\fR
.RS
Scan all leaked marked allocations again.
.RE
.RE
.RS
\fInew\fR
.RS
Scan only allocations since last scan.
.RE
.RE

.IP "set searchpath \fIpathes\fR"
Set the searchpath for binaries and libraries.  This is similar to to options
-b.  To pass more the one path search path, use a colon as seperator.  For a
detailed description about the search path see \-b option.

.IP "show \fI...\fR"
Show information about

.RS
\fIinfo\fR
.RS
Shows client settings.
.RE
.RE
.RS
\fIsearchpath\fR
.RS
Show searchpath for binaries and libraries.
.RE
.RE

.IP "start \fIpid\fR"
Start allocation tracing.

.IP "status \fIpid\fR"
Show allocation status.

.IP "stop \fIpid\fR"
Stop allocation tracing.  Note that in this state a \fIscan\fR command can
not performed.

.SH BUGS
It only works on Linux for X86, X86_64, ARM 32 and PowerPC 32.  No Hardware
Breakpoint support on ARM and PowerPC.  No ARM Thumb support.  See TODO file
for more open issues.
.LP
.PP
If you would like to report a bug, send a mail to stefani@seibold.net
.SH FILES
.TP
.I /etc/mtrace-ng.conf\fR or \fISYSCONFDIR/mtrace-ng.conf
System configuration file
.TP
.I $HOME/.mtrace-ng\fR or \fI$XDG_CONFIG_HOME/mtrace-ng
Personal config file, overrides system configuration file
.PP

See mtrace-ng.conf(5) for details on the syntax of this file.
.SH AUTHOR
Stefani Seibold <stefani@seibold.net>
.SH "SEE ALSO"
.BR mtrace-ng.conf(5),
.BR ptrace(2),
.BR perf(1)