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 \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 to trace.
 126 The format of the filter expression is described in the section
 127 \fBFILTER EXPRESSIONS\fR.  If more than one \-e option appears on the
 128 command line, the library calls that match any of them are traced.  If
 129 no \-e is given, \fB@MAIN\fR is assumed as a default.
 130 .IP \-f
 131 Trace child processes as they are created by
 132 currently traced processes as a result of the fork(2)
 133 or clone(2) system calls.
 134 The new process is attached immediately.
 135 .IP "\-F \fIpathlist"
 136 Contains a colon-separated list of paths.  If a path refers to a
 137 directory, that directory is considered when prototype libraries are
 138 searched (see the section \fBPROTOTYPE LIBRARY DISCOVERY\fR).  If it refers to
 139 a file, that file is imported implicitly to all loaded prototype
 140 libraries.
 141 .IP "\-h, \-\-help"
 142 Show a summary of the options to ltrace and exit.
 143 .IP \-i
 144 Print the instruction pointer at the time of the library call.
 145 .IP "\-l, \-\-library \fIlibrary_pattern"
 146 Display only calls to functions implemented by libraries that match
 147 .I library_pattern.
 148 Multiple library patters can be specified with several instances of
 149 this option.  Syntax of library_pattern is described in section
 150 \fBFILTER EXPRESSIONS\fR.
 151
 152 Note that while this option selects calls that might be directed to
 153 the selected libraries, there's no actual guarantee that the call
 154 won't be directed elsewhere due to e.g. LD_PRELOAD or simply
 155 dependency ordering.  If you want to make sure that symbols in given
 156 library are actually called, use \fB-x @\fIlibrary_pattern\fR instead.
 157 .IP \-L
 158 When no \-e option is given, don't assume the default action of
 159 \fB@MAIN\fR.  In practice this means that library calls will not be
 160 traced.
 161 .IP "\-n, \-\-indent \fInr"
 162 Indent trace output by \fInr\fR spaces for each level of call
 163 nesting. Using this option makes the program flow visualization easy
 164 to follow.  This indents uselessly also functions that never return,
 165 such as service functions for throwing exceptions in the C++ runtime.
 166 .IP "\-o, \-\-output \fIfilename"
 167 Write the trace output to the file \fIfilename\fR rather than to
 168 stderr.
 169 .IP "\-p \fIpid"
 170 Attach to the process with the process ID \fIpid\fR and begin tracing.
 171 This option can be used together with passing a command to execute.
 172 It is possible to attach to several processes by passing more than one
 173 option \-p.
 174 .IP \-r
 175 Print a relative timestamp with each line of the trace.  This records
 176 the time difference between the beginning of successive lines.
 177 .IP "\-s \fIstrsize"
 178 Specify the maximum string size to print (the default is 32).
 179 .IP \-S
 180 Display system calls as well as library calls
 181 .IP \-t
 182 Prefix each line of the trace with the time of day.
 183 .IP \-tt
 184 If given twice, the time printed will include the microseconds.
 185 .IP \-ttt
 186 If given thrice, the time printed will include the microseconds and
 187 the leading portion will be printed as the number of seconds since the
 188 epoch.
 189 .IP \-T
 190 Show  the  time  spent inside each call. This records the time difference
 191 between the beginning and the end of each call.
 192 .IP "\-u \fIusername"
 193 Run command with the userid, groupid and supplementary groups of
 194 .IR username .
 195 This option is only useful when running as root and enables the
 196 correct execution of setuid and/or setgid binaries.
 197 .IP "\-w, \-\-where \fInr"
 198 Show backtrace of \fInr\fR stack frames for each traced function. This
 199 option enabled only if elfutils or libunwind support was enabled at compile
 200 time.
 201 .IP "\-x \fIfilter"
 202 A qualifying expression which modifies which symbol table entry points
 203 to trace.  The format of the filter expression is described in the
 204 section \fBFILTER EXPRESSIONS\fR.  If more than one \-x option appears
 205 on the command line, the symbols that match any of them are traced.
 206 No entry points are traced if no \-x is given.
 207 .IP "\-V, \-\-version"
 208 Show the version number of ltrace and exit.
 209
 210 .SH FILTER EXPRESSIONS
 211
 212 Filter expression is a chain of glob- or regexp-based rules that are
 213 used to pick symbols for tracing from libraries that the process uses.
 214 Most of it is intuitive, so as an example, the following would trace
 215 calls to malloc and free, except those done by libc:
 216
 217 -e malloc+free-@libc.so*
 218
 219 This reads: trace malloc and free, but don't trace anything that comes
 220 from libc.  Semi-formally, the syntax of the above example looks
 221 approximately like this:
 222
 223 {[+-][\fIsymbol_pattern\fR][@\fIlibrary_pattern\fR]}
 224
 225 \fISymbol_pattern\fR is used to match symbol names,
 226 \fIlibrary_pattern\fR to match library SONAMEs.  Both are implicitly
 227 globs, but can be regular expressions as well (see below).  The glob
 228 syntax supports meta-characters \fB*\fR and \fB?\fR and character
 229 classes, similarly to what basic bash globs support.  \fB^\fR and
 230 \fB$\fR are recognized to mean, respectively, start and end of given
 231 name.
 232
 233 Both \fIsymbol_pattern\fR and \fIlibrary_pattern\fR have to match the
 234 whole name.  If you want to match only part of the name, surround it
 235 with one or two *'s as appropriate.  The exception is if the pattern
 236 is not mentioned at all, in which case it's as if the corresponding
 237 pattern were \fB*\fR.  (So \fBmalloc\fR is really \fBmalloc@*\fR and
 238 \fB@libc.*\fR is really \fB*@libc.*\fR.)
 239
 240 In libraries that don't have an explicit SONAME, basename is taken for
 241 SONAME.  That holds for main binary as well: \fB/bin/echo\fR has an
 242 implicit SONAME of \fBecho\fR.  In addition to that, special library
 243 pattern \fBMAIN\fR always matches symbols in the main binary and never
 244 a library with actual SONAME \fBMAIN\fR (use e.g. \fB^MAIN\fR or
 245 \fB[M]AIN\fR for that).
 246
 247 If the symbol or library pattern is surrounded in slashes (/like
 248 this/), then it is considered a regular expression instead.  As a
 249 shorthand, instead of writing \fB/x/@/y/\fR, you can write
 250 \fB/x@y/\fR.
 251
 252 If the library pattern starts with a slash, it is not a SONAME
 253 expression, but a path expression, and is matched against the library
 254 path name.
 255
 256 The first rule may lack a sign, in which case \fB+\fR is assumed.  If,
 257 on the other hand, the first rule has a \fB-\fR sign, it is as if
 258 there was another rule \fB@\fR in front of it, which has the effect of
 259 tracing complement of given rule.
 260
 261 The above rules are used to construct the set of traced symbols.  Each
 262 candidate symbol is passed through the chain of above rules.
 263 Initially, the symbol is \fIunmarked\fR.  If it matches a \fB+\fR
 264 rule, it becomes \fImarked\fR, if it matches a \fB-\fR rule, it
 265 becomes \fIunmarked\fR again.  If, after applying all rules, the
 266 symbol is \fImarked\fR, it will be traced.
 267
 268 .SH PROTOTYPE LIBRARY DISCOVERY
 269
 270 When a library is mapped into the address space of a traced process,
 271 ltrace needs to know what the prototypes are of functions that this
 272 library implements.  For purposes of ltrace, prototype really is a bit
 273 more than just type signature: it's also formatting of individual
 274 parameters and of return value.  These prototypes are stored in files
 275 called prototype libraries.
 276
 277 After a library is mapped, ltrace finds out what its SONAME is.  It
 278 then looks for a file named SONAME.conf--e.g. protolib for libc.so.6
 279 would be in a file called libc.so.6.conf.  When such file is found
 280 (more about where ltrace looks for these files is below), ltrace reads
 281 all prototypes stored therein.  When a symbol table entry point (such
 282 as those traced by \-x) is hit, the prototype is looked up in a
 283 prototype library corresponding to the library where the hit occurred.
 284 When a library call (such as those traced by \-e and \-l) is hit, the
 285 prototype is looked up in all prototype libraries loaded for given
 286 process.  That is necessary, because a library call is traced in a PLT
 287 table of a caller library, but the prototype is described at callee
 288 library.
 289
 290 If a library has no SONAME, basename of library file is considered
 291 instead.  For the main program binary, basename is considered as well
 292 (e.g. protolib for /bin/echo would be called echo.conf).  If a name
 293 corresponding to soname (e.g. libc.so.6.conf) is not found, and the
 294 module under consideration is a shared library, ltrace also tries
 295 partial matches.  Ltrace snips one period after another, retrying the
 296 search, until either a protolib is found, or X.so is all that's left.
 297 Thus libc.so.conf would be considered, but libc.conf not.
 298
 299 When looking for a prototype library, ltrace potentially looks into
 300 several directories.  On Linux, those are $XDG_CONFIG_HOME/ltrace,
 301 $HOME/.ltrace, \fIX\fR/ltrace for each \fIX\fR in $XDG_CONFIG_DIRS and
 302 /usr/share/ltrace.  If the environment variable XDG_CONFIG_HOME is not
 303 defined, ltrace looks into $HOME/.config/ltrace instead.
 304
 305 There's also a mechanism for loading legacy config files.  If
 306 $HOME/.ltrace.conf exists it is imported to every loaded prototype
 307 library.  Similarly for /etc/ltrace.conf.  If both exist, both are
 308 imported, and $HOME/.ltrace.conf is consulted before /etc/ltrace.conf.
 309
 310 If \-F contains any directories, those are searched in precedence to
 311 the above system directories, in the same order in which they are
 312 mentioned in \-F.  Any files passed in \-F are imported similarly to
 313 above legacy config files, before them.
 314
 315 See ltrace.conf(5) for details on the syntax of ltrace prototype
 316 library files.
 317
 318 .SH BUGS
 319 It has most of the bugs stated in
 320 .BR strace(1) .
 321 .LP
 322 It only works on Linux and in some architectures.
 323 .LP
 324 .PP
 325 If you would like to report a bug, send a message to the mailing list
 326 (ltrace-devel@lists.alioth.debian.org), or use the
 327 .BR reportbug(1)
 328 program if you are under the Debian GNU/Linux distribution.
 329
 330 .SH FILES
 331 .TP
 332 .I /etc/ltrace.conf
 333 System configuration file
 334 .TP
 335 .I ~/.ltrace.conf
 336 Personal config file, overrides
 337 .I /etc/ltrace.conf
 338
 339 .SH AUTHOR
 340 Juan Cespedes <cespedes@debian.org>
 341 .br
 342 Petr Machata <pmachata@redhat.com>
 343
 344 .SH "SEE ALSO"
 345 .BR ltrace.conf(5),
 346 .BR strace(1) ,
 347 .BR ptrace(2)