1LTRACE(1) User Commands LTRACE(1)
2
6 ltrace - A library call tracer
7
10 ltrace [-e filter|-L] [-l|--library=library_pattern] [-x filter] [-S]
11 [-b|--no-signals] [-i] [-w|--where=nr] [-r|-t|-tt|-ttt] [-T] [-F path‐
12 list] [-A maxelts] [-s strsize] [-C|--demangle] [-a|--align column]
13 [-n|--indent nr] [-o|--output filename] [-D|--debug mask] [-u username]
14 [-f] [-p pid] [[--] command [arg ...]]
15 ltrace -c [-e filter|-L] [-l|--library=library_pattern] [-x filter]
17 [-S] [-o|--output filename] [-f] [-p pid] [[--] command [arg ...]]
18 ltrace -V|--version
20 ltrace -h|--help
22
25 ltrace is a program that simply runs the specified command until it
26 exits. It intercepts and records the dynamic library calls which are
27 called by the executed process and the signals which are received by
28 that process. It can also intercept and print the system calls exe‐
29 cuted by the program.
30 Its use is very similar to strace(1).
32 ltrace shows parameters of invoked functions and system calls. To
34 determine what arguments each function has, it needs external declara‐
35 tion of function prototypes. Those are stored in files called proto‐
36 type libraries--see ltrace.conf(5) for details on the syntax of these
37 files. See the section PROTOTYPE LIBRARY DISCOVERY to learn how ltrace
38 finds prototype libraries.
39
42 -a, --align column
43 Align return values in a specific column (default column is 5/8
44 of screen width).
45 -A maxelts
47 Maximum number of array elements to print before suppressing the
48 rest with an ellipsis ("..."). This also limits number of
49 recursive structure expansions.
50 -b, --no-signals
52 Disable printing of signals recieved by the traced process.
53 -c Count time and calls for each library call and report a summary
55 on program exit.
56 -C, --demangle
58 Decode (demangle) low-level symbol names into user-level names.
59 Besides removing any initial underscore prefix used by the sys‐
60 tem, this makes C++ function names readable.
61 -D, --debug mask
63 Show debugging output of ltrace itself. mask is a number
64 describing which debug messages should be displayed. Use the
65 option -Dh to see what can be used, but note that currently the
66 only reliable debugmask is 77, which shows all debug messages.
67 -e filter
69 A qualifying expression which modifies which library calls to
70 trace. The format of the filter expression is described in the
71 section FILTER EXPRESSIONS. If more than one -e option appears
72 on the command line, the library calls that match any of them
73 are traced. If no -e is given, @MAIN is assumed as a default.
74 -f Trace child processes as they are created by currently traced
76 processes as a result of the fork(2) or clone(2) system calls.
77 The new process is attached immediately.
78 -F pathlist
80 Contains a colon-separated list of paths. If a path refers to a
81 directory, that directory is considered when prototype libraries
82 are searched (see the section PROTOTYPE LIBRARY DISCOVERY). If
83 it refers to a file, that file is imported implicitly to all
84 loaded prototype libraries.
85 -h, --help
87 Show a summary of the options to ltrace and exit.
88 -i Print the instruction pointer at the time of the library call.
90 -l, --library library_pattern
92 Display only calls to functions implemented by libraries that
93 match library_pattern. Multiple library patters can be speci‐
94 fied with several instances of this option. Syntax of
95 library_pattern is described in section FILTER EXPRESSIONS.
96 Note that while this option selects calls that might be directed
98 to the selected libraries, there's no actual guarantee that the
99 call won't be directed elsewhere due to e.g. LD_PRELOAD or sim‐
100 ply dependency ordering. If you want to make sure that symbols
101 in given library are actually called, use -x @library_pattern
102 instead.
103 -L When no -e option is given, don't assume the default action of
105 @MAIN. In practice this means that library calls will not be
106 traced.
107 -n, --indent nr
109 Indent trace output by nr spaces for each level of call nesting.
110 Using this option makes the program flow visualization easy to
111 follow. This indents uselessly also functions that never
112 return, such as service functions for throwing exceptions in the
113 C++ runtime.
114 -o, --output filename
116 Write the trace output to the file filename rather than to
117 stderr.
118 -p pid Attach to the process with the process ID pid and begin tracing.
120 This option can be used together with passing a command to exe‐
121 cute. It is possible to attach to several processes by passing
122 more than one option -p.
123 -r Print a relative timestamp with each line of the trace. This
125 records the time difference between the beginning of successive
126 lines.
127 -s strsize
129 Specify the maximum string size to print (the default is 32).
130 -S Display system calls as well as library calls
132 -t Prefix each line of the trace with the time of day.
134 -tt If given twice, the time printed will include the microseconds.
136 -ttt If given thrice, the time printed will include the microseconds
138 and the leading portion will be printed as the number of seconds
139 since the epoch.
140 -T Show the time spent inside each call. This records the time
142 difference between the beginning and the end of each call.
143 -u username
145 Run command with the userid, groupid and supplementary groups of
146 username. This option is only useful when running as root and
147 enables the correct execution of setuid and/or setgid binaries.
148 -w, --where nr
150 Show backtrace of nr stack frames for each traced function. This
151 option enabled only if elfutils or libunwind support was enabled
152 at compile time.
153 -x filter
155 A qualifying expression which modifies which symbol table entry
156 points to trace. The format of the filter expression is
157 described in the section FILTER EXPRESSIONS. If more than one
158 -x option appears on the command line, the symbols that match
159 any of them are traced. No entry points are traced if no -x is
160 given.
161 -V, --version
163 Show the version number of ltrace and exit.
164
167 Filter expression is a chain of glob- or regexp-based rules that are
168 used to pick symbols for tracing from libraries that the process uses.
169 Most of it is intuitive, so as an example, the following would trace
170 calls to malloc and free, except those done by libc:
171 -e malloc+free-@libc.so*
173 This reads: trace malloc and free, but don't trace anything that comes
175 from libc. Semi-formally, the syntax of the above example looks
176 approximately like this:
177 {[+-][symbol_pattern][@library_pattern]}
179 Symbol_pattern is used to match symbol names, library_pattern to match
181 library SONAMEs. Both are implicitly globs, but can be regular expres‐
182 sions as well (see below). The glob syntax supports meta-characters *
183 and ? and character classes, similarly to what basic bash globs sup‐
184 port. ^ and $ are recognized to mean, respectively, start and end of
185 given name.
186 Both symbol_pattern and library_pattern have to match the whole name.
188 If you want to match only part of the name, surround it with one or two
189 *'s as appropriate. The exception is if the pattern is not mentioned
190 at all, in which case it's as if the corresponding pattern were *. (So
191 malloc is really malloc@* and @libc.* is really *@libc.*.)
192 In libraries that don't have an explicit SONAME, basename is taken for
194 SONAME. That holds for main binary as well: /bin/echo has an implicit
195 SONAME of echo. In addition to that, special library pattern MAIN
196 always matches symbols in the main binary and never a library with
197 actual SONAME MAIN (use e.g. ^MAIN or [M]AIN for that).
198 If the symbol or library pattern is surrounded in slashes (/like
200 this/), then it is considered a regular expression instead. As a
201 shorthand, instead of writing /x/@/y/, you can write /x@y/.
202 If the library pattern starts with a slash, it is not a SONAME expres‐
204 sion, but a path expression, and is matched against the library path
205 name.
206 The first rule may lack a sign, in which case + is assumed. If, on the
208 other hand, the first rule has a - sign, it is as if there was another
209 rule @ in front of it, which has the effect of tracing complement of
210 given rule.
211 The above rules are used to construct the set of traced symbols. Each
213 candidate symbol is passed through the chain of above rules. Ini‐
214 tially, the symbol is unmarked. If it matches a + rule, it becomes
215 marked, if it matches a - rule, it becomes unmarked again. If, after
216 applying all rules, the symbol is marked, it will be traced.
217
220 When a library is mapped into the address space of a traced process,
221 ltrace needs to know what the prototypes are of functions that this
222 library implements. For purposes of ltrace, prototype really is a bit
223 more than just type signature: it's also formatting of individual
224 parameters and of return value. These prototypes are stored in files
225 called prototype libraries.
226 After a library is mapped, ltrace finds out what its SONAME is. It
228 then looks for a file named SONAME.conf--e.g. protolib for libc.so.6
229 would be in a file called libc.so.6.conf. When such file is found
230 (more about where ltrace looks for these files is below), ltrace reads
231 all prototypes stored therein. When a symbol table entry point (such
232 as those traced by -x) is hit, the prototype is looked up in a proto‐
233 type library corresponding to the library where the hit occured. When
234 a library call (such as those traced by -e and -l) is hit, the proto‐
235 type is looked up in all prototype libraries loaded for given process.
236 That is necessary, because a library call is traced in a PLT table of a
237 caller library, but the prototype is described at callee library.
238 If a library has no SONAME, basename of library file is considered
240 instead. For the main program binary, basename is considered as well
241 (e.g. protolib for /bin/echo would be called echo.conf). If a name
242 corresponding to soname (e.g. libc.so.6.conf) is not found, and the
243 module under consideration is a shared library, ltrace also tries par‐
244 tial matches. Ltrace snips one period after another, retrying the
245 search, until either a protolib is found, or X.so is all that's left.
246 Thus libc.so.conf would be considered, but libc.conf not.
247 When looking for a prototype library, ltrace potentially looks into
249 several directories. On Linux, those are $XDG_CONFIG_HOME/ltrace,
250 $HOME/.ltrace, X/ltrace for each X in $XDG_CONFIG_DIRS and
251 /usr/share/ltrace. If the environment variable XDG_CONFIG_HOME is not
252 defined, ltrace looks into $HOME/.config/ltrace instead.
253 There's also a mechanism for loading legacy config files. If
255 $HOME/.ltrace.conf exists it is imported to every loaded prototype
256 library. Similarly for /etc/ltrace.conf. If both exist, both are
257 imported, and $HOME/.ltrace.conf is consulted before /etc/ltrace.conf.
258 If -F contains any directories, those are searched in precedence to the
260 above system directories, in the same order in which they are mentioned
261 in -F. Any files passed in -F are imported similarly to above legacy
262 config files, before them.
263 See ltrace.conf(5) for details on the syntax of ltrace prototype
265 library files.
266
269 It has most of the bugs stated in strace(1).
270 It only works on Linux and in a small subset of architectures.
272 If you would like to report a bug, send a message to the mailing list
274 (ltrace-devel@lists.alioth.debian.org), or use the reportbug(1) program
275 if you are under the Debian GNU/Linux distribution.
276
279 /etc/ltrace.conf
280 System configuration file
281 ~/.ltrace.conf
283 Personal config file, overrides /etc/ltrace.conf
284
287 Juan Cespedes <cespedes@debian.org>
288 Petr Machata <pmachata@redhat.com>
289
292 ltrace.conf(5), strace(1), ptrace(2)
293 January 2013 LTRACE(1)