ltrace.1

   1 .\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
   2 .\" This file is covered by the GNU GPL
   3 .TH ltrace 1
   4 .SH NAME
   5 ltrace \- A library call tracer
   6
   7 .SH SYNOPSIS
   8 .B ltrace
   9 .I "[-CfhiLrStttV] [-a column] [-A maxelts] [-D level] [-e expr] [-l filename] [-n nr] [-o filename] [-p pid] ... [-s strsize] [-u username] [-X extern] [-x extern] ... [--align=column] [--debug=level] [--demangle] [--help] [--indent=nr] [--library=filename] [--output=filename] [--version] [command [arg ...]]"
  10
  11 .SH DESCRIPTION
  12 .B ltrace
  13 is a program that simply runs the specified
  14 .I command
  15 until it exits.  It intercepts and records the dynamic library calls
  16 which are called by the executed process and the signals which are
  17 received by that process.
  18 It can also intercept and print the system calls executed by the program.
  19 .PP
  20 Its use is very similar to
  21 .BR strace(1) .
  22
  23 .SH OPTIONS
  24 .TP
  25 .I \-a, \-\-align column
  26 Align return values in a specific column (default column is 5/8 of screen width).
  27 .TP
  28 .I \-A maxelts
  29 Maximum number of array elements to print before suppressing the rest with an ellipsis ("...")
  30 .TP
  31 .I \-c
  32 Count time and calls for each library call and report a summary on program exit.
  33 .TP
  34 .I \-C, \-\-demangle
  35 Decode (demangle) low-level symbol names into user-level names.
  36 Besides removing any initial underscore prefix used by the system,
  37 this makes C++ function names readable.
  38 .TP
  39 .I \-D, \-\-debug level
  40 Show debugging output of
  41 .B ltrace
  42 itself.
  43 .I level
  44 must be a sum of some of the following numbers:
  45 .RS
  46 .TP
  47 .B 01
  48 DEBUG_GENERAL.  Shows helpful progress information
  49 .TP
  50 .B 010
  51 DEBUG_EVENT.  Shows every event received by a traced program
  52 .TP
  53 .B 020
  54 DEBUG_PROCESS.  Shows every action
  55 .B ltrace
  56 carries upon a traced process
  57 .TP
  58 .B 040
  59 DEBUG_FUNCTION.  Shows every entry to internal functions
  60 .RE
  61 .TP
  62 .I \-e expr
  63 A qualifying expression which modifies which events to trace.
  64 The format of the expression is:
  65 .br
  66 [!]value1[,value2]...
  67 .br
  68 where the values are the functions to trace.  Using an exclamation
  69 mark negates the set of values.  For example
  70 .I \-e printf
  71 means to trace only the printf library call.  By contrast,
  72 .I \-e !printf
  73 means to trace every library call except printf.
  74 .IP
  75 Note that some shells use the exclamation point for history
  76 expansion; even inside quoted arguments.  If so, you must escape
  77 the exclamation point with a backslash.
  78 .TP
  79 .I \-f
  80 Trace child processes as they are created by
  81 currently traced processes as a result of the fork(2)
  82 or clone(2) system calls.
  83 The new process is attached immediately.
  84 .TP
  85 .I \-F
  86 Load an alternate config file. Normally, /etc/ltrace.conf and
  87 ~/.ltrace.conf will be read (the latter only if it exists).
  88 Use this option to load the given file or files instead of
  89 those two default files.
  90 .TP
  91 .I \-h, \-\-help
  92 Show a summary of the options to ltrace and exit.
  93 .TP
  94 .I \-i
  95 Print the instruction pointer at the time of the library call.
  96 .TP
  97 .I \-l, \-\-library filename
  98 Display only the symbols included in the library
  99 .I filename.
 100 Up to 30 library names can be specified with several instances
 101 of this option.
 102 .TP
 103 .I \-L
 104 DON'T display library calls (use it with the
 105 .I \-S
 106 option).
 107 .TP
 108 .I \-n, \-\-indent nr
 109 Indent trace output by
 110 .I nr
 111 number of spaces for each new nested call. Using this option makes
 112 the program flow visualization easy to follow.
 113 .TP
 114 .I \-o, \-\-output filename
 115 Write the trace output to the file
 116 .I filename
 117 rather than to stderr.
 118 .TP
 119 .I \-p pid
 120 Attach to the process with the process ID
 121 .I pid
 122 and begin tracing.
 123 .TP
 124 .I \-r
 125 Print a relative timestamp with each line of the trace.
 126 This records the time difference between the beginning of
 127 successive lines.
 128 .TP
 129 .I \-s strsize
 130 Specify the maximum string size to print (the default is 32).
 131 .TP
 132 .I \-S
 133 Display system calls as well as library calls
 134 .TP
 135 .I \-t
 136 Prefix each line of the trace with the time of day.
 137 .TP
 138 .I \-tt
 139 If given twice, the time printed will include the microseconds.
 140 .TP
 141 .I \-ttt
 142 If given thrice, the time printed will include the microseconds and
 143 the leading portion will be printed as the number of seconds since the
 144 epoch.
 145 .TP
 146 .I \-T
 147 Show  the  time  spent inside each call. This records the time difference
 148 between the beginning and the end of each call.
 149 .TP
 150 .I \-u username
 151 Run command with the userid, groupid and supplementary groups of
 152 .IR username .
 153 This option is only useful when running as root and enables the
 154 correct execution of setuid and/or setgid binaries.
 155 .TP
 156 .I \-X extern
 157 Some architectures need to know where to set a breakpoint that will be hit
 158 after the dynamic linker has run.  If this flag is used, then the breakpoint
 159 is set at
 160 .IR extern ,
 161 which must be an external function.  By default, '_start' is used.
 162 NOTE: this flag is only available on the architectures that need it.
 163 .TP
 164 .I \-x extern
 165 Trace the external function
 166 .IR extern .
 167 This option may be repeated.
 168 .TP
 169 .I \-V, \-\-version
 170 Show the version number of ltrace and exit.
 171
 172 .SH BUGS
 173 It has most of the bugs stated in
 174 .BR strace(1) .
 175 .LP
 176 Manual page and documentation are not very up-to-date.
 177 .LP
 178 Option -f sometimes fails to trace some children.
 179 .LP
 180 It only works on Linux and in a small subset of architectures.
 181 .LP
 182 Only ELF32 binaries are supported.
 183 .LP
 184 Calls to dlopen()ed libraries will not be traced.
 185 .PP
 186 If you would like to report a bug, send a message to the mailing list
 187 (ltrace-devel@lists.alioth.debian.org), or use the
 188 .BR reportbug(1)
 189 program if you are under the Debian GNU/Linux distribution.
 190
 191 .SH FILES
 192 .TP
 193 .I /etc/ltrace.conf
 194 System configuration file
 195 .TP
 196 .I ~/.ltrace.conf
 197 Personal config file, overrides
 198 .I /etc/ltrace.conf
 199
 200 .SH AUTHOR
 201 Juan Cespedes <cespedes@debian.org>
 202
 203 .SH "SEE ALSO"
 204 .BR strace(1) ,
 205 .BR ptrace(2)
 206