ltrace.1

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