1LTRACE(1)                        User Commands                       LTRACE(1)
2
3
4

NAME

6       ltrace - A library call tracer
7
8

SYNOPSIS

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
16       ltrace  -c  [-e  filter|-L]  [-l|--library=library_pattern] [-x filter]
17       [-S] [-o|--output filename] [-f] [-p pid] [[--] command [arg ...]]
18
19       ltrace -V|--version
20
21       ltrace -h|--help
22
23

DESCRIPTION

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
31       Its use is very similar to strace(1).
32
33       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
40

OPTIONS

42       -a, --align column
43              Align  return values in a specific column (default column is 5/8
44              of screen width).
45
46       -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
51       -b, --no-signals
52              Disable printing of signals recieved by the traced process.
53
54       -c     Count time and calls for each library call and report a  summary
55              on program exit.
56
57       -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
62       -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
68       -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
75       -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
79       -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
86       -h, --help
87              Show a summary of the options to ltrace and exit.
88
89       -i     Print the instruction pointer at the time of the library call.
90
91       -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
97              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
104       -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
108       -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
115       -o, --output filename
116              Write the trace output to  the  file  filename  rather  than  to
117              stderr.
118
119       -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
124       -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
128       -s strsize
129              Specify the maximum string size to print (the default is 32).
130
131       -S     Display system calls as well as library calls
132
133       -t     Prefix each line of the trace with the time of day.
134
135       -tt    If given twice, the time printed will include the microseconds.
136
137       -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
141       -T     Show  the  time  spent inside each call. This records  the  time
142              difference between the beginning and the end of each call.
143
144       -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
149       -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
154       -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
162       -V, --version
163              Show the version number of ltrace and exit.
164
165

FILTER EXPRESSIONS

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
172       -e malloc+free-@libc.so*
173
174       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
178       {[+-][symbol_pattern][@library_pattern]}
179
180       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
187       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
193       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
199       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
203       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
207       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
212       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
218

PROTOTYPE LIBRARY DISCOVERY

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
227       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
239       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
248       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
254       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
259       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
264       See  ltrace.conf(5)  for  details  on  the  syntax  of ltrace prototype
265       library files.
266
267

BUGS

269       It has most of the bugs stated in strace(1).
270
271       It only works on Linux and in a small subset of architectures.
272
273       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
277

FILES

279       /etc/ltrace.conf
280              System configuration file
281
282       ~/.ltrace.conf
283              Personal config file, overrides /etc/ltrace.conf
284
285

AUTHOR

287       Juan Cespedes <cespedes@debian.org>
288       Petr Machata <pmachata@redhat.com>
289
290

SEE ALSO

292       ltrace.conf(5), strace(1), ptrace(2)
293
294
295
296                                 January 2013                        LTRACE(1)
Impressum