DragonFly On-Line Manual Pages

LMDBG-RUN(1)                                                      LMDBG-RUN(1)

NAME
       lmdbg-run - runs a program and traces the malloc/realloc/free calls

SYNOPSIS
       lmdbg-run [OPTIONS] <progname> [args...]

DESCRIPTION
       lmdbg-run lmdbg-run runs an external command progname args and creates
       a log file where all invocations of malloc, calloc, realloc, memalign,
       posix_memalign and free are registered accompanied by the following
       information: full stacktrace (addresses), input argument(s) (requested
       size and/or address), result value (returned address, if any) and
       ordinal number of function invocation.  Also, some special information
       is output about the program being run.  Before being saved to the log
       file, stacktrace info can be filtered through a custom command.

OPTIONS
       -h     Display the help message.

       -V     Display the lmdbg version.

       -v     Enable verbose mode.

       -o filename
              Specify the log file name.

       -f|-p command
              Filter stacktraces through a filtering command/pipe.  The result
              is sent to the log file specified in -o option or to stdout
              otherwise.

       -n     Do not enable logging on startup. To enable it, send SIGUSR1
              signal to the process.

       -N filename
              Save pid of progname to filename.

       -T number
              Specify the number of addresses to skip from the top of the
              stacktrace (farther from function main).

       -B number
              Specify the number of addresses to skip from the bottom of the
              stacktrace (nearer to function main).

       -M number
              Limit the number of addresses shown in a stacktrace. An
              incomplete stacktrace may be generated, that includes the top of
              the stack.

EXAMPLE
       The output of lmdbg-run may look like the following

        realloc ( 0xbb901800 , 777 ) --> 0xbb901c00
         0xbbbe58e8
         0xbbbe5a37
         0x8048764
         0x8048584
         0x80484e7

       This output means that realloc function was given the pointer
       0xbb901800 and 777 bytes were requested. As a result realloc returned
       the address 0xbb901c00.  Addresses 0xbbbe58e8, 0xbbbe5a37 etc. are a
       part of the stacktrace.

EXAMPLE

       $ cat test2.c
       #include <stdlib.h>

       int main ()
       {
          void *p1 = NULL;
          void *p2 = NULL;

          p1 = malloc (555);
          p2 = realloc (p2, 666);
          p2 = realloc (p2, 777);
          p2 = realloc (p2, 888);

          return 0;
       }
       $ cc -O0 -g -o test2 test2.c
       $ lmdbg-run -o log ./test2
       $ cat log
       info section 0x0xbbace000 0x0xbbbc6000 /lib/libc.so.12.179
       info section 0x0xbbbdd000 0x0xbbbe1000 /usr/pkg/lib/liblmdbg.so.0.0
       info section 0x0xbbbee000 0x0xbbbfe000 /libexec/ld.elf_so
       info progname ./test2
       malloc ( 555 ) --> 0xbb90a400 num: 1
        0xbbbddb7a
        0xbbbde53b
        0x8048769
        0x804863d
        0x8048678
       realloc ( NULL , 666 ) --> 0xbb90a800 num: 2
        0xbbbddb7a
        0xbbbde68c
        0x8048781
        0x804863d
        0x8048678
       realloc ( 0xbb90a800 , 777 ) --> 0xbb90ac00 num: 3
        0xbbbddb7a
        0xbbbde68c
        0x8048799
        0x804863d
        0x8048678
       realloc ( 0xbb90ac00 , 888 ) --> 0xbb90a800 num: 4
        0xbbbddb7a
        0xbbbde68c
        0x80487b1
        0x804863d
        0x8048678
       $

EXAMPLE
       lmdbg-run -o log ./my_app &&
         lmdbg-leaks log > log_leaks &&
         lmdbg-sym ./my_app log_leaks > log_leaks2 &&
         lmdbg-sysleaks -s log_leaks2 > log_final
       lmdbg-run -B2 -M6 -f 'lmdbg-leaks | lmdbg-sym > log' ./my_app <args>

ENVIRONMENT
       LMDBG_LIB
              Path to LD_PRELOAD'ed liblmdbg dynamic library. It defaults to
              /usr/local/lib/liblmdbg.so

NOTES
       Full stacktrace allows analysing an application on per-module basis. It
       helps determine what libraries and/or components require more memory
       than others and why. See lmdbg-stat and lmdbg-sort.

BUGS
       The current implementation of lmdbg-run relies on several GCC's
       extensions, namely, __builtin_return_address, __builtin_frame_address,
       __attribute__((constructor)) and __attribute__((destructor)). In my
       knowledge, Besides GCC these extensions are also supported by Intel C
       compiler and Clang. If you know a solution that works for other
       compilers let me now ;-)

SEE ALSO
       lmdbg(1), lmdbg-sym(1), lmdbg-stat(1), lmdbg-sort(1), lmdbg-grep(1),
       lmdbg-head(1), lmdbg-leaks(1), lmdbg-sysleaks(1), lmdbg-strip(1),
       lmdbg-modules(1)

AUTHOR
       Aleksey Cheusov <vle@gmx.net>

                                August 4, 2013                    LMDBG-RUN(1)