update documentation

CREDITS

@@ -0,0 +1,4 @@
+the source is based on
+ ltrace http://ltrace.org/
+ libunwind http://www.nongnu.org/libunwind/
+ linux https://kernel.org/

HOWTO

@@ -0,0 +1,172 @@
+The easiest way for using mtrace is simply run a program under the control of mtrace:
+
+mtrace -d 10 a.out
+
+This will run a.out and records all memory allocations. When the program exits or mtrace is terminated, it dumps all open memory allocations for each different stack backtrace:
+
+.
+.
+.
+Stack (mmap):
+ bytes used: 8392704
+ number of open allocations: 1
+ total number of allocations: 1
+ tsc: 4
+  [0x7f9e207abfd7] /lib64/libpthread.so.0 pthread_create
+  [0x4010e0] /home/stefani/mt/test/x.c:128 test
+  [0x40126a] /home/stefani/mt/test/x.c:189 main
+  [0x7f9e20427b55] /lib64/libc.so.6 __libc_start_main
+  [0x400b89] /home/stefani/mt/test/a.out _start
+Stack (malloc):
+ bytes used: 4800
+ number of open allocations: 8
+ total number of allocations: 30
+ tsc: 75
+  [0x400dee] /home/stefani/mt/test/x.c:56 ThreadFuncA
+  [0x7f9e207ab3a4] /lib64/libpthread.so.0 __pthread_get_minstack
+  [0x7f9e204ee18d] /lib64/libc.so.6 clone
+
+In this case you see for the last stack backtrace which calls malloc() by function ThreadFuncA in file /home/stefani/mt/test/x.c at line 56, which has 8 open allocations using a total of 4800 bytes.
+
+The default sort order is "allocations", which sorts the output by the number of open allocations. The lowest value is printed out first and the highest value at last. So the most interesting values are always in view. If you wish a different sort order und can pass a -S option, for example.
+
+mtrace -d 10 -s usage a.out
+
+This will sort by the total sum of bytes used:
+
+Stack (malloc):
+ bytes used: 288
+ number of open allocations: 1
+ total number of allocations: 1
+ tsc: 1
+  [0x7ff0ca5562e2] /lib64/ld-linux-x86-64.so.2 _dl_mcount
+  [0x7ff0ca556a8e] /lib64/ld-linux-x86-64.so.2 _dl_allocate_tls
+  [0x7ff0c990c069] /lib64/libpthread.so.0 pthread_create
+  [0x401022] /home/stefani/mt/test/x.c:107 test
+  [0x40126a] /home/stefani/mt/test/x.c:189 main
+  [0x7ff0c9587b55] /lib64/libc.so.6 __libc_start_main
+  [0x400b89] /home/stefani/mt/test/a.out _start
+.
+.
+.
+Stack (mmap):
+ bytes used: 8392704
+ number of open allocations: 1
+ total number of allocations: 1
+ tsc: 2
+  [0x7ff0c990bfd7] /lib64/libpthread.so.0 pthread_create
+  [0x401081] /home/stefani/mt/test/x.c:117 test
+  [0x40126a] /home/stefani/mt/test/x.c:189 main
+  [0x7ff0c9587b55] /lib64/libc.so.6 __libc_start_main
+  [0x400b89] /home/stefani/mt/test/a.out _start
+Stack (mmap):
+ bytes used: 8392704
+ number of open allocations: 1
+ total number of allocations: 1
+ tsc: 4
+  [0x7ff0c990bfd7] /lib64/libpthread.so.0 pthread_create
+  [0x4010e0] /home/stefani/mt/test/x.c:128 test
+  [0x40126a] /home/stefani/mt/test/x.c:189 main
+  [0x7ff0c9587b55] /lib64/libc.so.6 __libc_start_main
+  [0x400b89] /home/stefani/mt/test/a.out _start
+
+So you can see that the last two stack backtraces both called mmap() from inside the pthread_create() function. But since there are two different backtrace stacks there will be not merged together (the first on is called by x.c:117 and the other by x.c:128). Lets assume for the above example the stack backtrace depth is set (to the not really useful) value of 1, then mtrace would output:
+
+Stack (mmap):
+ bytes used: 16785408
+ number of open allocations: 2
+ total number of allocations: 2
+ tsc: 4
+  [0x7ff0c990bfd7] /lib64/libpthread.so.0 pthread_create
+
+In this case it is not possible to identifiy which function has been called pthread_create() and some important informations get lost. So it always reasonable to use a stack depth which allows to distinguish the callers. For C programs a depth value of 10 is recommended and for C++ a minimum of 20 is useful.
+
+It is also possible to write the output to a file instead to stderr, for example: 
+
+mtrace -d 10 -o /tmp/mtrace.out a.out
+
+In this case the dump will written to /tmp/mtrace.out after the program exits or mtrace is terminated. Note that in the case the sort order is inverted, the highest value is written first to the file and the lowest value at last. So the most interesting values are always in view when opening the file with an editor. 
+
+It is also possible to attach to an already running program:
+
+mtrace -d 10 -o /tmp/mtrace.out $(pidof -s a.out)
+
+This is e.g. useful when you not want do trace the whole startup of the program or you want to test only a specific function of a program. Imaging a test scenario where a leak is assumed. So attached mtrace, run the tests (more then once is better) and then terminated mtrace by Ctrl-C. One of last dump stack backtraces should show the culprit.
+
+A more sophisticate way to find a memory leak is to scan for lost pointer values, e.g.
+
+mtrace -a -S leaks -d 10 -o /tmp/mtrace.out $(pidof -s a.out)
+
+After attach and run the tests and terminating mtrace by Ctrl-C, the memory will be scanned for lost pointer. The dump output will then sorted by the number of leaked allocations:
+
+process 12166 scanning 18 allocations
+process 12166
+ leaks reported: 15
+ new leaks found: 15
+ leaked bytes: 8064
+ leaked at 0x02030010 (288 bytes)
+ leaked at 0x02030140 (288 bytes)
+ leaked at 0x02030270 (288 bytes)
+ leaked at 0x7fb4740008c0 (0 bytes)
+ leaked at 0x7fb4740008e0 (400 bytes)
+ leaked at 0x7fb474000a80 (800 bytes)
+ leaked at 0x7fb474000db0 (1200 bytes)
+ leaked at 0x7fb474001270 (0 bytes)
+ leaked at 0x7fb474001290 (400 bytes)
+ leaked at 0x7fb474001430 (800 bytes)
+ leaked at 0x7fb474001760 (1200 bytes)
+ leaked at 0x7fb474001c20 (0 bytes)
+ leaked at 0x7fb474001c40 (400 bytes)
+ leaked at 0x7fb474001de0 (800 bytes)
+ leaked at 0x7fb474002110 (1200 bytes)
+leaks total: 15
+.
+.
+.
+Stack (malloc):
+ bytes used: 288
+ number of open allocations: 1
+ total number of allocations: 1
+ leaked allocations: 1 (288 bytes)
+ tsc: 6
+  [0x7fb47aae72e2] /lib64/ld-linux-x86-64.so.2 _dl_mcount
+  [0x7fb47aae7a8e] /lib64/ld-linux-x86-64.so.2 _dl_allocate_tls
+  [0x7fb479e9d069] /lib64/libpthread.so.0 pthread_create
+  [0x4010e0] /home/stefani/mt/test/x.c:128 test
+  [0x40126a] /home/stefani/mt/test/x.c:189 main
+  [0x7fb479b18b55] /lib64/libc.so.6 __libc_start_main
+  [0x400b89] /home/stefani/mt/test/a.out _start
+Stack (malloc):
+ bytes used: 7200
+ number of open allocations: 12
+ total number of allocations: 45
+ leaked allocations: 12 (7200 bytes)
+ tsc: 110
+  [0x400dee] /home/stefani/mt/test/x.c:56 ThreadFuncA
+  [0x7fb479e9c3a4] /lib64/libpthread.so.0 __pthread_get_minstack
+  [0x7fb479bdf18d] /lib64/libc.so.6 clone
+
+So you can see there are 15 leaked pointer in this case and the main culprit is a malloc() called from ThreadFuncA().
+
+There is also a server mode and a client with an command line interface. This is useful when you want get information during the runtime 
+of a program, for example:
+
+mtrace -w -s -d 10 a.out
+
+This start the client waiting for a client connection before running the program a.out.
+
+Then you can connect the client using an other terminal or on an other computer:
+
+mtrace -c 127.0.0.1
+memtrace info:
+ follow fork: no
+ follow exec: no
+ verbose: no
+ do trace: yes
+ stack depth: 10
+memtrace> 
+
+No you can ask for help with the command "help", or dump the current state of the bookkeeping by using the command "dump".
+
+For more information about the interactive mode see the manual page mtrace(1) section INTERACTIVE MODE.
+

Makefile.am

@@ -81,7 +81,7 @@ noinst_HEADERS = \
 dist_man1_MANS = mtrace.1
 dist_man5_MANS = mtrace.conf.5
 
-dist_doc_DATA = COPYING CREDITS INSTALL README TODO
+dist_doc_DATA = COPYING CREDITS INSTALL README TODO HOWTO
 
 EXTRA_DIST = 
 

README.md

@@ -1,38 +1,65 @@
-mtrace is an interactive dynamic memory tracer/debugger for C and C++, which intercepts and reports all kinds of dynamic memory allocations.
+Mtrace
+------
 
-It supports the developer to get statistics about the memory usage and finding memory leaks in an arbitrate application. There is no need of modification of the source code nor any recompilation.
+mtrace is an interactive dynamic memory tracer, debugger and statistical analyses tool for C and C++, which intercepts, records and reports all kinds of dynamic memory allocations.
 
-Unlike other dynamic memory tracer, mtrace is able to find no longer referenced memory allocation by scanning all writable memory mappings of the program against the addresses of the 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.
+It supports the developer to get statistics about the memory usage and finding memory leaks in an arbitrate program.  Since mtrace is using breakpoints for tracing the program, there is no need of modification of the source code nor any recompilation.
 
-The mtrace utility was designed to run in a very constrained environment, like small embedded systems. This is one of the reasons for a client/server architecture. The server runs on the target side and the interactive client runs on the host side, the communication is done via TCP. If server and client are on the same machine then the communication can be done via UNIX Domain Socket. Both sides can run on different architectures, address sizes and endianness, but for tracing 64 bit programs the client must be compiled as a 64 bit program. On the host side all binaries (including debug information) must be accessible, there is no need for debug information on the target side.
+The mtrace utility intercepts the following library calls:
-
-The mtrace utility intercepts the following GLIBC calls:
 
 	void *malloc(size_t size);
-        void free(void *ptr);
+	void free(void *ptr);
-        void *calloc(size_t nmemb, size_t size);
+	void *calloc(size_t nmemb, size_t size);
-        void *realloc(void *ptr, size_t size);
+	void *realloc(void *ptr, size_t size);
-        int posix_memalign(void **memptr, size_t alignment, size_t size);
+	int posix_memalign(void **memptr, size_t alignment, size_t size);
-        void *aligned_alloc(size_t alignment, size_t size);
+	void *aligned_alloc(size_t alignment, size_t size);
-        void *valloc(size_t size);
+	void *valloc(size_t size);
-        void *memalign(size_t alignment, size_t size);
+	void *memalign(size_t alignment, size_t size);
-        void *pvalloc(size_t size);
+	void *pvalloc(size_t size);
-        void cfree(void *ptr);
+	void cfree(void *ptr);
-        void *mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset);
+	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);
+	void *mmap64(void *addr, size_t length, int prot, int flags, int fd, off_t offset);
-        int munmap(void *addr, size_t length);
+	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 *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) throw (std::bad_alloc)
-        void *operator new(size_t size, const std::nothrow_t& nt) __THROW
+	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) throw (std::bad_alloc)
-        void *operator new[](size_t size, const std::nothrow_t& nt) __THROW
+	void *operator new[](size_t size, const std::nothrow_t& nt) __THROW
-        void operator delete(void* p) __THROW
+	void operator delete(void* p) __THROW
-        void operator delete(void* p, const std::nothrow_t& nt) __THROW
+	void operator delete(void* p, const std::nothrow_t& nt) __THROW
-        void operator delete[](void* p) __THROW
+	void operator delete[](void* p) __THROW
-        void operator delete[](void* p, const std::nothrow_t& nt) __THROW
+	void operator delete[](void* p, const std::nothrow_t& nt) __THROW
 
-There is currently support for X86 (32 and 64 Bit), PowerPC (32 Bit) and ARM (32 Bit). Only Linux is now supported, but there are plans to support different operating systems and CPU's.
 
-Stay tuned...
+For each allocation a backtrace will be recorded.  This backtrace allows to trace and identify the callers of an allocation function.  The depth of this backtrace could be set by the -d option. Identical backtraces will be handled as one caller, since there is no way to distinguish the callers.
+
+Unlike other dynamic memory tracer, mtrace is able to find no longer referenced memory allocation by scanning all writable memory mappings of the program against the pointer values of the allocations.  If a pointer value of an open allocated memory block will 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.
+
+The mtrace utility was designed to run in a very constrained environment, like small embedded systems.  This is one of the reasons for a client/server architecture.  The server runs on the target side and the interactive client runs on the host side, the communication is done via TCP.  If server and client running on the same machine then the communication can be done via UNIX Domain Socket.  Both sides can run on different architectures, address sizes and endianness, but for tracing 64 bit programs the client must be compiled as a 64 bit program.  On the host side all binaries (including debug information) must be accessible, there is no need for debug information on the target side.
+
+
+mtrace offers different kind of working modes.  A non interactive mode, a server mode and a interactive client mode.
+
+Non interactive mode
+--------------------
+The most common mode is the non interactive mode, which allows to run and/or attach to a process, similar to strace.  mtrace will show all open allocations when the traced program exists or mtrace will be terminated.
+
+Server mode
+-----------
+For system with memory restrictions or for using in a cross architecture environment, mtrace 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.
+
+Interactive client mode
+-----------------------
+To get a more detailed information about the dynamic memory consumption mtrace can be started in an interactive mode.  This mode is available for client mode or when attaching to a process.  See the section INTERACTIVE MODE of the manual page mtrace(1) to learn more about the interactive commands in mtrace.
+
+
+Restrictions
+------------
+There is currently support for X86 (32 and 64 Bit), PowerPC (32 Bit) and ARM (32 Bit, no Thumb support).  Only Linux is now supported, but there are plans to support different operating systems and CPU's.
+
+
+Munich, Germany
+6. Mai 2015
+Stefani Seibold
 

mtrace.1

@@ -150,7 +150,7 @@ and hunt for memory leaks.
 
 .B mtrace
 is able to find no longer referenced memory allocation by scanning all
-writable memory mappings of the program against the pointer of the allocation.
+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.
 
@@ -185,8 +185,8 @@ void operator delete[](void* p, const std::nothrow_t& nt) __THROW
 .in
 .PP
 .B mtrace
-offers four different kind of modes.  A non interactive mode, a server
+offers three different kind of working modes.  A non interactive mode, a
-mode and a interactive and non interactive client mode.
+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.
@@ -195,12 +195,13 @@ will show all open allocations when the traced program exists or
 .B mtrace
 will be terminated.
 
-For system with memory restrictions or cross architecture
+For system with memory restrictions or for using in a cross architecture
+environment,
 .B mtrace
 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 host system.
+on the remote host system.
 
 To get a more detailed information about the dynamic memory consumption
 .B mtrace
@@ -214,7 +215,7 @@ to learn more about the interactive commands in
 Scan all writeable memory mappings of the process for leaked pointers on exit
 of the traced program or termination of \fBmtrace\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 a very long time,
+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"
@@ -224,7 +225,7 @@ 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 option -b.
+by passing more than one \-b option.
 .IP "\-c, \-\-client \fIaddr\fR"
 Run
 .B mtrace
@@ -242,8 +243,8 @@ to manually add this information.
 Show debugging output of
 .B mtrace
 itself.  \fImask\fR is a number
-describing which debug messages should be displayed.  Use the option
+describing which debug messages should be displayed.  Use the \-Dh option
-\-Dh to see what can be used.  This option is only available when
+to see what can be used.  This option is only available when
 .B mtrace
 was build with --enable-debug.
 .IP "\-d, \-\-depth \fIlevel\fR"
@@ -257,7 +258,7 @@ a result of execve(2) system call.
 .IP "\-F, \-\-config \fIpath"
 Set the config file.  For a detailed description of this file see
 mtrace.conf(5).  It is possible to pass several config files by passing more
-than one option \-F.  If no -F is given,
+than one \-F option.  If no -F is given,
 .B mtrace
 will look up for one of the default files in the following order:
 $HOME/.mtrace,
@@ -290,12 +291,12 @@ since this library does call malloc() and free() inside the allocation operators
 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
-option \-p.
+\-p option.
 .IP "\-P, \-\-port \fInum"
 Set the port number for client or server mode.  The default port number is 4576.
 .IP "\-s, \-\-server"
 Run mtrace in server mode.  This is mostly needed for remote cross architecture
-trace or when running an interactive client.  If no option -l and -P is passed
+trace or when running an interactive client.  If no \-l and \-P option is passed
 to the sever mode, the server will listen on any address using port 4576.
 .IP "\-S, \-\-sortby keyword"
 Sort the output of the stack backtraces by keyword.  Valid keywords are:
@@ -315,13 +316,13 @@ Sort by the number of average allocations (number of bytes in used / number of o
 .RS
 \fIbytes-leaked\fR
 .RS
-Sort by number of bytes leaked (only useful with option -a).
+Sort by number of bytes leaked (only useful with \-a option).
 .RE
 .RE
 .RS
 \fIleaks\fR
 .RS
-Sort by number of leaked allocations (only useful with option -a).
+Sort by number of leaked allocations (only useful with \-a option).
 .RE
 .RE
 .RS
@@ -393,8 +394,8 @@ at any time.  It accepts a maximum of three parameters:
 \fIsortby\fR
 .RS
 Sort the output of dump by the keyword.  The keyword is the same as for the
-option -S (\fIallocations, \fIaverage\fR, \fIbytes-leaked\fR, \fIleaks\fR,
+\-S option (\fIallocations, \fIaverage\fR, \fIbytes-leaked\fR, \fIleaks\fR,
-\fIstacks\fR, \fItotal\fR, \fItsc\fR and \fIusage\fR).  See option -S for
+\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
@@ -455,7 +456,7 @@ Scan only allocations since last scan.
 .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 option -B.
+detailed description about the search path see \-b option.
 
 .IP "show \fI...\fR"
 Show information about