.\" -*-nroff-*- .\" Copyright (c) 2015 Stefani Seibold .\" .\" 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 .SH "SEE ALSO" .BR mtrace-ng.conf(5), .BR ptrace(2), .BR perf(1)