ltrace.1

   1 .\" -*-nroff-*-
   2 .\" Copyright (c) 2012, 2013, 2014 Petr Machata, Red Hat Inc.
   3 .\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
   4 .\"
   5 .\" This program is free software; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of the
   8 .\" License, or (at your option) any later version.
   9 .\"
  10 .\" This program is distributed in the hope that it will be useful, but
  11 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 .\" General Public License for more details.
  14 .\"
  15 .\" You should have received a copy of the GNU General Public License
  16 .\" along with this program; if not, write to the Free Software
  17 .\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  18 .\" 02110-1301 USA
  19 .\"
  20 .TH LTRACE "1" "January 2013" "" "User Commands"
  21 .SH NAME
  22 ltrace \- A library call tracer
  23
  24 .SH SYNOPSIS
  25 .\"
  26 .\" ---------------------------------------------------------------------------
  27 .\"
  28 .PP
  29 .B ltrace
  30 .\"
  31 .\" What events to trace:
  32 .\"
  33 [\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR]
  34 [\-x \fIfilter\fR] [\-S] [\-b|\-\-no-signals]
  35 .\"
  36 .\" What to display with each event:
  37 .\"
  38 [\-i] [\-w|\-\-where=\fInr\fR] [\-r|\-t|\-tt|\-ttt] [\-T]
  39 .\"
  40 .\" Output formatting:
  41 .\"
  42 [[\-F|\-\-config] \fIpathlist\fR]
  43 [\-A \fImaxelts\fR] [\-s \fIstrsize\fR] [\-C|\-\-demangle]
  44 [\-a|\-\-align \fIcolumn\fR] [\-n|\-\-indent \fInr\fR]
  45 [\-o|\-\-output \fIfilename\fR]
  46 .\"
  47 .\" Various:
  48 .\"
  49 [\-D|\-\-debug \fImask\fR] [\-u \fIusername\fR]
  50 .\"
  51 .\" What processes to trace:
  52 .\"
  53 [\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR]
  54 .\"
  55 .\" ---------------------------------------------------------------------------
  56 .\"
  57 .PP
  58 .BR ltrace " \-c"
  59 .\"
  60 .\" What events to trace:
  61 .\"
  62 [\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR]
  63 [\-x \fIfilter\fR] [\-S]
  64 .\"
  65 .\" Output formatting:
  66 .\"
  67 [\-o|\-\-output \fIfilename\fR]
  68 .\"
  69 .\" What processes to trace:
  70 .\"
  71 [\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR]
  72 .\"
  73 .\" ---------------------------------------------------------------------------
  74 .\"
  75 .PP
  76 .BR ltrace " \-V|\-\-version"
  77 .PP
  78 .BR ltrace " \-h|\-\-help"
  79
  80 .SH DESCRIPTION
  81 .B ltrace
  82 is a program that simply runs the specified
  83 .I command
  84 until it exits.  It intercepts and records the dynamic library calls
  85 which are called by the executed process and the signals which are
  86 received by that process.
  87 It can also intercept and print the system calls executed by the program.
  88 .PP
  89 Its use is very similar to
  90 .BR strace(1) .
  91
  92 .B ltrace
  93 shows parameters of invoked functions and system calls.  To determine
  94 what arguments each function has, it needs external declaration of
  95 function prototypes.  Those are stored in files called \fIprototype
  96 libraries\fR--see ltrace.conf(5) for details on the syntax of these
  97 files.  See the section \fBPROTOTYPE LIBRARY DISCOVERY\fR to learn how
  98 \fBltrace\fR finds prototype libraries.
  99
 100 .SH OPTIONS
 101 .PP
 102 .IP "\-a, \-\-align \fIcolumn"
 103 Align return values in a specific
 104 .IR column
 105 (default column is 5/8 of screen width).
 106 .IP "\-A \fImaxelts"
 107 Maximum number of array elements to print before suppressing the rest
 108 with an ellipsis ("...").  This also limits number of recursive
 109 structure expansions.
 110 .IP "\-b, \-\-no-signals"
 111 Disable printing of signals received by the traced process.
 112 .IP \-c
 113 Count time and calls for each library call and report a summary on
 114 program exit.
 115 .IP "\-C, \-\-demangle"
 116 Decode (demangle) low-level symbol names into user-level names.
 117 Besides removing any initial underscore prefix used by the system,
 118 this makes C++ function names readable.
 119 .IP "\-D, \-\-debug \fRmask\fI"
 120 Show debugging output of \fBltrace\fR itself.  \fImask\fR is a number
 121 describing which debug messages should be displayed.  Use the option
 122 \-Dh to see what can be used, but note that currently the only
 123 reliable debugmask is 77, which shows all debug messages.
 124 .IP "\-e \fIfilter"
 125 A qualifying expression which modifies which library calls (i.e. calls
 126 done through PLT slots, which are typically calls from the main binary
 127 to a library, or inter-library calls) to trace.  The format of the
 128 filter expression is described in the section \fBFILTER
 129 EXPRESSIONS\fR.  If more than one \-e option appears on the command
 130 line, the library calls that match any of them are traced.  If no \-e
 131 is given, \fB@MAIN\fR is assumed as a default.
 132 .IP \-f
 133 Trace child processes as they are created by
 134 currently traced processes as a result of the fork(2)
 135 or clone(2) system calls.
 136 The new process is attached immediately.
 137 .IP "\-F, \-\-config \fIpathlist"
 138 Contains a colon-separated list of paths.  If a path refers to a
 139 directory, that directory is considered when prototype libraries are
 140 searched (see the section \fBPROTOTYPE LIBRARY DISCOVERY\fR).  If it refers to
 141 a file, that file is imported implicitly to all loaded prototype
 142 libraries.
 143 .IP "\-h, \-\-help"
 144 Show a summary of the options to ltrace and exit.
 145 .IP \-i
 146 Print the instruction pointer at the time of the library call.
 147 .IP "\-l, \-\-library \fIlibrary_pattern"
 148 Display only calls to functions implemented by libraries that match
 149 .I library_pattern.
 150 This is as if you specified one \-e for every symbol implemented in a
 151 library specified by
 152 .I library_pattern.
 153 Multiple library patters can be specified with several instances of
 154 this option.  Syntax of library_pattern is described in section
 155 \fBFILTER EXPRESSIONS\fR.
 156
 157 Note that while this option selects calls that might be directed to
 158 the selected libraries, there's no actual guarantee that the call
 159 won't be directed elsewhere due to e.g. LD_PRELOAD or simply
 160 dependency ordering.  If you want to make sure that symbols in given
 161 library are actually called, use \fB-x @\fIlibrary_pattern\fR instead.
 162 .IP \-L
 163 When no \-e option is given, don't assume the default action of
 164 \fB@MAIN\fR.  In practice this means that library calls will not be
 165 traced.
 166 .IP "\-n, \-\-indent \fInr"
 167 Indent trace output by \fInr\fR spaces for each level of call
 168 nesting. Using this option makes the program flow visualization easy
 169 to follow.  This indents uselessly also functions that never return,
 170 such as service functions for throwing exceptions in the C++ runtime.
 171 .IP "\-o, \-\-output \fIfilename"
 172 Write the trace output to the file \fIfilename\fR rather than to
 173 stderr.
 174 .IP "\-p \fIpid"
 175 Attach to the process with the process ID \fIpid\fR and begin tracing.
 176 This option can be used together with passing a command to execute.
 177 It is possible to attach to several processes by passing more than one
 178 option \-p.
 179 .IP \-r
 180 Print a relative timestamp with each line of the trace.  This records
 181 the time difference between the beginning of successive lines.
 182 .IP "\-s \fIstrsize"
 183 Specify the maximum string size to print (the default is 32).
 184 .IP \-S
 185 Display system calls as well as library calls
 186 .IP \-t
 187 Prefix each line of the trace with the time of day.
 188 .IP \-tt
 189 If given twice, the time printed will include the microseconds.
 190 .IP \-ttt
 191 If given thrice, the time printed will include the microseconds and
 192 the leading portion will be printed as the number of seconds since the
 193 epoch.
 194 .IP \-T
 195 Show  the  time  spent inside each call. This records the time difference
 196 between the beginning and the end of each call.
 197 .IP "\-u \fIusername"
 198 Run command with the userid, groupid and supplementary groups of
 199 .IR username .
 200 This option is only useful when running as root and enables the
 201 correct execution of setuid and/or setgid binaries.
 202 .IP "\-w, \-\-where \fInr"
 203 Show backtrace of \fInr\fR stack frames for each traced function. This
 204 option enabled only if elfutils or libunwind support was enabled at compile
 205 time.
 206 .IP "\-x \fIfilter"
 207 A qualifying expression which modifies which symbol table entry points
 208 to trace (those are typically calls inside a library or main binary,
 209 though PLT calls, traced by \-e, land on entry points as well).  The
 210 format of the filter expression is described in the section \fBFILTER
 211 EXPRESSIONS\fR.  If more than one \-x option appears on the command
 212 line, the symbols that match any of them are traced.  No entry points
 213 are traced if no \-x is given.
 214 .IP "\-V, \-\-version"
 215 Show the version number of ltrace and exit.
 216
 217 .SH FILTER EXPRESSIONS
 218
 219 Filter expression is a chain of glob- or regexp-based rules that are
 220 used to pick symbols for tracing from libraries that the process uses.
 221 Most of it is intuitive, so as an example, the following would trace
 222 calls to malloc and free, except those done by libc:
 223
 224 -e malloc+free-@libc.so*
 225
 226 This reads: trace malloc and free, but don't trace anything that comes
 227 from libc.  Semi-formally, the syntax of the above example looks
 228 approximately like this:
 229
 230 {[+-][\fIsymbol_pattern\fR][@\fIlibrary_pattern\fR]}
 231
 232 \fISymbol_pattern\fR is used to match symbol names,
 233 \fIlibrary_pattern\fR to match library SONAMEs.  Both are implicitly
 234 globs, but can be regular expressions as well (see below).  The glob
 235 syntax supports meta-characters \fB*\fR and \fB?\fR and character
 236 classes, similarly to what basic bash globs support.  \fB^\fR and
 237 \fB$\fR are recognized to mean, respectively, start and end of given
 238 name.
 239
 240 Both \fIsymbol_pattern\fR and \fIlibrary_pattern\fR have to match the
 241 whole name.  If you want to match only part of the name, surround it
 242 with one or two *'s as appropriate.  The exception is if the pattern
 243 is not mentioned at all, in which case it's as if the corresponding
 244 pattern were \fB*\fR.  (So \fBmalloc\fR is really \fBmalloc@*\fR and
 245 \fB@libc.*\fR is really \fB*@libc.*\fR.)
 246
 247 In libraries that don't have an explicit SONAME, basename is taken for
 248 SONAME.  That holds for main binary as well: \fB/bin/echo\fR has an
 249 implicit SONAME of \fBecho\fR.  In addition to that, special library
 250 pattern \fBMAIN\fR always matches symbols in the main binary and never
 251 a library with actual SONAME \fBMAIN\fR (use e.g. \fB^MAIN\fR or
 252 \fB[M]AIN\fR for that).
 253
 254 If the symbol or library pattern is surrounded in slashes (/like
 255 this/), then it is considered a regular expression instead.  As a
 256 shorthand, instead of writing \fB/x/@/y/\fR, you can write
 257 \fB/x@y/\fR.
 258
 259 If the library pattern starts with a slash, it is not a SONAME
 260 expression, but a path expression, and is matched against the library
 261 path name.
 262
 263 The first rule may lack a sign, in which case \fB+\fR is assumed.  If,
 264 on the other hand, the first rule has a \fB-\fR sign, it is as if
 265 there was another rule \fB@\fR in front of it, which has the effect of
 266 tracing complement of given rule.
 267
 268 The above rules are used to construct the set of traced symbols.  Each
 269 candidate symbol is passed through the chain of above rules.
 270 Initially, the symbol is \fIunmarked\fR.  If it matches a \fB+\fR
 271 rule, it becomes \fImarked\fR, if it matches a \fB-\fR rule, it
 272 becomes \fIunmarked\fR again.  If, after applying all rules, the
 273 symbol is \fImarked\fR, it will be traced.
 274
 275 .SH PROTOTYPE LIBRARY DISCOVERY
 276
 277 When a library is mapped into the address space of a traced process,
 278 ltrace needs to know what the prototypes are of functions that this
 279 library implements.  For purposes of ltrace, prototype really is a bit
 280 more than just type signature: it's also formatting of individual
 281 parameters and of return value.  These prototypes are stored in files
 282 called prototype libraries.
 283
 284 After a library is mapped, ltrace finds out what its SONAME is.  It
 285 then looks for a file named SONAME.conf--e.g. protolib for libc.so.6
 286 would be in a file called libc.so.6.conf.  When such file is found
 287 (more about where ltrace looks for these files is below), ltrace reads
 288 all prototypes stored therein.  When a symbol table entry point (such
 289 as those traced by \-x) is hit, the prototype is looked up in a
 290 prototype library corresponding to the library where the hit occurred.
 291 When a library call (such as those traced by \-e and \-l) is hit, the
 292 prototype is looked up in all prototype libraries loaded for given
 293 process.  That is necessary, because a library call is traced in a PLT
 294 table of a caller library, but the prototype is described at callee
 295 library.
 296
 297 If a library has no SONAME, basename of library file is considered
 298 instead.  For the main program binary, basename is considered as well
 299 (e.g. protolib for /bin/echo would be called echo.conf).  If a name
 300 corresponding to soname (e.g. libc.so.6.conf) is not found, and the
 301 module under consideration is a shared library, ltrace also tries
 302 partial matches.  Ltrace snips one period after another, retrying the
 303 search, until either a protolib is found, or X.so is all that's left.
 304 Thus libc.so.conf would be considered, but libc.conf not.
 305
 306 When looking for a prototype library, ltrace potentially looks into
 307 several directories.  On Linux, those are $XDG_CONFIG_HOME/ltrace,
 308 $HOME/.ltrace, \fIX\fR/ltrace for each \fIX\fR in $XDG_CONFIG_DIRS and
 309 /usr/share/ltrace.  If the environment variable XDG_CONFIG_HOME is not
 310 defined, ltrace looks into $HOME/.config/ltrace instead.
 311
 312 There's also a mechanism for loading legacy config files.  If
 313 $HOME/.ltrace.conf exists it is imported to every loaded prototype
 314 library.  Similarly for /etc/ltrace.conf.  If both exist, both are
 315 imported, and $HOME/.ltrace.conf is consulted before /etc/ltrace.conf.
 316
 317 If \-F contains any directories, those are searched in precedence to
 318 the above system directories, in the same order in which they are
 319 mentioned in \-F.  Any files passed in \-F are imported similarly to
 320 above legacy config files, before them.
 321
 322 See ltrace.conf(5) for details on the syntax of ltrace prototype
 323 library files.
 324
 325 .SH BUGS
 326 It has most of the bugs stated in
 327 .BR strace(1) .
 328 .LP
 329 It only works on Linux and in some architectures.
 330 .LP
 331 .PP
 332 If you would like to report a bug, send a message to the mailing list
 333 (ltrace-devel@lists.alioth.debian.org), or use the
 334 .BR reportbug(1)
 335 program if you are under the Debian GNU/Linux distribution.
 336
 337 .SH FILES
 338 .TP
 339 .I /etc/ltrace.conf
 340 System configuration file
 341 .TP
 342 .I ~/.ltrace.conf
 343 Personal config file, overrides
 344 .I /etc/ltrace.conf
 345
 346 .SH AUTHOR
 347 Juan Cespedes <cespedes@debian.org>
 348 .br
 349 Petr Machata <pmachata@redhat.com>
 350
 351 .SH "SEE ALSO"
 352 .BR ltrace.conf(5),
 353 .BR strace(1) ,
 354 .BR ptrace(2)