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 elfutils or libunwind support was enabled at compile
 199 time.
 200 .IP "\-x \fIfilter"
 201 A qualifying expression which modifies which symbol table entry points
 202 to trace.  The format of the filter expression is described in the
 203 section \fBFILTER EXPRESSIONS\fR.  If more than one \-x option appears
 204 on the command line, the symbols that match any of them are traced.
 205 No entry points are traced if no \-x is given.
 206 .IP "\-V, \-\-version"
 207 Show the version number of ltrace and exit.
 208
 209 .SH FILTER EXPRESSIONS
 210
 211 Filter expression is a chain of glob- or regexp-based rules that are
 212 used to pick symbols for tracing from libraries that the process uses.
 213 Most of it is intuitive, so as an example, the following would trace
 214 calls to malloc and free, except those done by libc:
 215
 216 -e malloc+free-@libc.so*
 217
 218 This reads: trace malloc and free, but don't trace anything that comes
 219 from libc.  Semi-formally, the syntax of the above example looks
 220 approximately like this:
 221
 222 {[+-][\fIsymbol_pattern\fR][@\fIlibrary_pattern\fR]}
 223
 224 \fISymbol_pattern\fR is used to match symbol names,
 225 \fIlibrary_pattern\fR to match library SONAMEs.  Both are implicitly
 226 globs, but can be regular expressions as well (see below).  The glob
 227 syntax supports meta-characters \fB*\fR and \fB?\fR and character
 228 classes, similarly to what basic bash globs support.  \fB^\fR and
 229 \fB$\fR are recognized to mean, respectively, start and end of given
 230 name.
 231
 232 Both \fIsymbol_pattern\fR and \fIlibrary_pattern\fR have to match the
 233 whole name.  If you want to match only part of the name, surround it
 234 with one or two *'s as appropriate.  The exception is if the pattern
 235 is not mentioned at all, in which case it's as if the corresponding
 236 pattern were \fB*\fR.  (So \fBmalloc\fR is really \fBmalloc@*\fR and
 237 \fB@libc.*\fR is really \fB*@libc.*\fR.)
 238
 239 In libraries that don't have an explicit SONAME, basename is taken for
 240 SONAME.  That holds for main binary as well: \fB/bin/echo\fR has an
 241 implicit SONAME of \fBecho\fR.  In addition to that, special library
 242 pattern \fBMAIN\fR always matches symbols in the main binary and never
 243 a library with actual SONAME \fBMAIN\fR (use e.g. \fB^MAIN\fR or
 244 \fB[M]AIN\fR for that).
 245
 246 If the symbol or library pattern is surrounded in slashes (/like
 247 this/), then it is considered a regular expression instead.  As a
 248 shorthand, instead of writing \fB/x/@/y/\fR, you can write
 249 \fB/x@y/\fR.
 250
 251 If the library pattern starts with a slash, it is not a SONAME
 252 expression, but a path expression, and is matched against the library
 253 path name.
 254
 255 The first rule may lack a sign, in which case \fB+\fR is assumed.  If,
 256 on the other hand, the first rule has a \fB-\fR sign, it is as if
 257 there was another rule \fB@\fR in front of it, which has the effect of
 258 tracing complement of given rule.
 259
 260 The above rules are used to construct the set of traced symbols.  Each
 261 candidate symbol is passed through the chain of above rules.
 262 Initially, the symbol is \fIunmarked\fR.  If it matches a \fB+\fR
 263 rule, it becomes \fImarked\fR, if it matches a \fB-\fR rule, it
 264 becomes \fIunmarked\fR again.  If, after applying all rules, the
 265 symbol is \fImarked\fR, it will be traced.
 266
 267 .SH PROTOTYPE LIBRARY DISCOVERY
 268
 269 When a library is mapped into the address space of a traced process,
 270 ltrace needs to know what the prototypes are of functions that this
 271 library implements.  For purposes of ltrace, prototype really is a bit
 272 more than just type signature: it's also formatting of individual
 273 parameters and of return value.  These prototypes are stored in files
 274 called prototype libraries.
 275
 276 After a library is mapped, ltrace finds out what its SONAME is.  It
 277 then looks for a file named SONAME.conf--e.g. protolib for libc.so.6
 278 would be in a file called libc.so.6.conf.  When such file is found
 279 (more about where ltrace looks for these files is below), ltrace reads
 280 all prototypes stored therein.  When a symbol table entry point (such
 281 as those traced by \-x) is hit, the prototype is looked up in a
 282 prototype library corresponding to the library where the hit occurred.
 283 When a library call (such as those traced by \-e and \-l) is hit, the
 284 prototype is looked up in all prototype libraries loaded for given
 285 process.  That is necessary, because a library call is traced in a PLT
 286 table of a caller library, but the prototype is described at callee
 287 library.
 288
 289 If a library has no SONAME, basename of library file is considered
 290 instead.  For the main program binary, basename is considered as well
 291 (e.g. protolib for /bin/echo would be called echo.conf).  If a name
 292 corresponding to soname (e.g. libc.so.6.conf) is not found, and the
 293 module under consideration is a shared library, ltrace also tries
 294 partial matches.  Ltrace snips one period after another, retrying the
 295 search, until either a protolib is found, or X.so is all that's left.
 296 Thus libc.so.conf would be considered, but libc.conf not.
 297
 298 When looking for a prototype library, ltrace potentially looks into
 299 several directories.  On Linux, those are $XDG_CONFIG_HOME/ltrace,
 300 $HOME/.ltrace, \fIX\fR/ltrace for each \fIX\fR in $XDG_CONFIG_DIRS and
 301 /usr/share/ltrace.  If the environment variable XDG_CONFIG_HOME is not
 302 defined, ltrace looks into $HOME/.config/ltrace instead.
 303
 304 There's also a mechanism for loading legacy config files.  If
 305 $HOME/.ltrace.conf exists it is imported to every loaded prototype
 306 library.  Similarly for /etc/ltrace.conf.  If both exist, both are
 307 imported, and $HOME/.ltrace.conf is consulted before /etc/ltrace.conf.
 308
 309 If \-F contains any directories, those are searched in precedence to
 310 the above system directories, in the same order in which they are
 311 mentioned in \-F.  Any files passed in \-F are imported similarly to
 312 above legacy config files, before them.
 313
 314 See ltrace.conf(5) for details on the syntax of ltrace prototype
 315 library files.
 316
 317 .SH BUGS
 318 It has most of the bugs stated in
 319 .BR strace(1) .
 320 .LP
 321 It only works on Linux and in some architectures.
 322 .LP
 323 .PP
 324 If you would like to report a bug, send a message to the mailing list
 325 (ltrace-devel@lists.alioth.debian.org), or use the
 326 .BR reportbug(1)
 327 program if you are under the Debian GNU/Linux distribution.
 328
 329 .SH FILES
 330 .TP
 331 .I /etc/ltrace.conf
 332 System configuration file
 333 .TP
 334 .I ~/.ltrace.conf
 335 Personal config file, overrides
 336 .I /etc/ltrace.conf
 337
 338 .SH AUTHOR
 339 Juan Cespedes <cespedes@debian.org>
 340 .br
 341 Petr Machata <pmachata@redhat.com>
 342
 343 .SH "SEE ALSO"
 344 .BR ltrace.conf(5),
 345 .BR strace(1) ,
 346 .BR ptrace(2)