2 .\" Copyright (c) 2012, 2013 Petr Machata, Red Hat Inc.
3 .\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
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.
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.
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
20 .TH LTRACE "1" "January 2013" "" "User Commands"
22 ltrace \- A library call tracer
26 .\" ---------------------------------------------------------------------------
31 .\" What events to trace:
33 [\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR]
34 [\-x \fIfilter\fR] [\-S] [\-b|\-\-no-signals]
36 .\" What to display with each event:
38 [\-i] [\-w|\-\-where=\fInr\fR] [\-r|\-t|\-tt|\-ttt] [\-T]
40 .\" Output formatting:
43 [\-A \fImaxelts\fR] [\-s \fIstrsize\fR] [\-C|\-\-demangle]
44 [\-a|\-\-align \fIcolumn\fR] [\-n|\-\-indent \fInr\fR]
45 [\-o|\-\-output \fIfilename\fR]
49 [\-D|\-\-debug \fImask\fR] [\-u \fIusername\fR]
51 .\" What processes to trace:
53 [\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR]
55 .\" ---------------------------------------------------------------------------
60 .\" What events to trace:
62 [\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR]
63 [\-x \fIfilter\fR] [\-S]
65 .\" Output formatting:
67 [\-o|\-\-output \fIfilename\fR]
69 .\" What processes to trace:
71 [\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR]
73 .\" ---------------------------------------------------------------------------
76 .BR ltrace " \-V|\-\-version"
78 .BR ltrace " \-h|\-\-help"
82 is a program that simply runs the specified
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.
89 Its use is very similar to
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.
102 .IP "\-a, \-\-align \fIcolumn"
103 Align return values in a specific
105 (default column is 5/8 of screen width).
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 recieved by the traced process.
113 Count time and calls for each library call and report a summary on
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
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.
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
142 Show a summary of the options to ltrace and exit.
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
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.
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.
158 When no -e option is given, don't assume the default action of
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
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
174 Print a relative timestamp with each line of the trace. This records
175 the time difference between the beginning of successive lines.
177 Specify the maximum string size to print (the default is 32).
179 Display system calls as well as library calls
181 Prefix each line of the trace with the time of day.
183 If given twice, the time printed will include the microseconds.
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
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
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.
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.
208 .SH FILTER EXPRESSIONS
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:
215 -e malloc+free-@libc.so*
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:
221 {[+-][\fIsymbol_pattern\fR][@\fIlibrary_pattern\fR]}
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
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.)
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).
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
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
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.
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.
266 .SH PROTOTYPE LIBRARY DISCOVERY
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.
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 occured.
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
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.
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.
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.
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.
313 See ltrace.conf(5) for details on the syntax of ltrace prototype
317 It has most of the bugs stated in
320 It only works on Linux and in a small subset of architectures.
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
326 program if you are under the Debian GNU/Linux distribution.
331 System configuration file
334 Personal config file, overrides
338 Juan Cespedes <cespedes@debian.org>
340 Petr Machata <pmachata@redhat.com>