1LATRACE(1)                                                          LATRACE(1)
2
3
4

NAME

6       latrace - LD_AUDIT 2.4+ libc frontend
7

SYNOPSIS

9       latrace [-snltfvhiBdISbcCyYLpoaNADVTFERq] command [arg ... ]
10

DESCRIPTION

12       The latrace tracer is able to run a command and display its dynamic
13       library calls using a LD_AUDIT libc feature, available from libc
14       version 2.4 onward. It is also capable to measure and display various
15       statistics of dynamic calls. See the section called “DISCUSSION” for
16       more details.
17
18       If the header file with functions' declarations is provided, latrace
19       will display functions’s arguments. The header file file syntax is
20       similar to the C language, with several exceptions See the section
21       called “HEADERS” for more details.
22
23       The latrace by default fully operates inside of the traced program.
24       However another "pipe mode" is available to move the main work to the
25       tracer - the latrace binary. See the section called “PIPE mode” for
26       more details.
27
28       The latrace use is similar to strace(1) and ltrace(1).
29

OPTIONS

31       -l, --libs lib1[,lib2,...]
32           audit from and to lib1, lib2 ...
33
34       -t, --libs-to lib1[,lib2,...]
35           audit to lib1, lib2 ...
36
37       -f, --libs-from lib1[,lib2,...]
38           audit from lib1, lib2 ...
39
40       -s, --sym sym1[,sym2,...]
41           audit symbols sym1, sym2 ...
42
43       -n, --sym-omit sym1[,sym2,...]
44           omit symbols sym1, sym2 ...
45
46       -L, --lib-subst s1[,s2,...]
47           objsearch LD_AUDIT interface (See the section called “OBJSEARCH”)
48
49       -c, --counts
50           display statistics counts of symbols - implies pipe mode (see the
51           section called “PIPE mode”) an no symbol output is displayed
52
53       -C, --sort-counts stat
54           implies -c, plus sort the statistics by stat with following values:
55           time,per,call,ucall,lib,sym (default is call)
56
57       -p, --pipe
58           use pipe to latrace process to send audit data (see the section
59           called “PIPE mode”)
60
61       -N, --conf
62           config file (see the section called “CONFIG”)
63
64       -A, --enable-args
65           enable arguments output (definitions from /etc/latrace.conf)
66
67       -D, --detail-args
68           display struct arguments in more detail
69
70       -a, --args file
71           specify arguments definition file, implies -A (without the default
72           definition file of course)
73
74       -y, --framesize number
75           framesize for storing the stack before pltexit (default 100)
76
77       -Y, --no-framesize-check
78           disable framesize check
79
80       -F, --no-follow-fork
81           dont follow fork calls (childs). This is just supressing the
82           latrace output from new childs. The nature of the LD_AUDIT feature
83           prevents to disable it completely.
84
85       -E, --no-follow-exec
86           dont follow exec calls
87
88       -S, --timestamp
89           display timestamp for each symbol
90
91       -b, --flow-below sym1[,sym2,...]
92           display flow for sym1, sym2 ...
93
94       -I, --no-indent-sym
95           do no indent symbols based on the their stack depth
96
97       -i, --indent-sym indent_size
98           indent size specification in indent_size
99
100       -B, --braces
101           allways display {} for the around the symbol body
102
103       -d, --demangle
104           C++ demangle symbols on the output
105
106       -T, --hide-tid
107           dont display thread id
108
109       -o, --output file
110           store output to file
111
112       -R, --ctl-config
113           controled config feature
114
115       -q, --disable
116           run with disabled auditing
117
118       -v, --verbose
119           verbose output
120
121       -V, --version
122           display version
123
124       -h, --help
125           display help
126

EXAMPLES

128       ·   The simplest way to run latrace is like this:
129
130               latrace cat
131
132       ·   To see the argument values specified by default config file run:
133
134               latrace -A cat
135
136       ·   Same as above but using the pipe mode to get all the end symbols
137           printed:
138
139               latrace -Ap cat
140
141       ·   To see the argument values specified by specified config file run:
142
143               latrace -a latrace.conf cat
144
145       ·   To get output only for specified symbol (eg. read and write) run:
146
147               latrace -A -s read,write cat
148
149       ·   To get flow under the specified symbol (eg. sysconf) run:
150
151               latrace -b sysconf kill
152
153       ·   To get output only for specified library (eg. libproc) run:
154
155               latrace -Al libproc w
156
157       ·   To get symbol statistics run:
158
159               latrace -c ls
160
161       ·   To get symbol statistics sorted by time run:
162
163               latrace -C time ls
164
165       ·   To get output stored to the text file run:
166
167               latrace -o output.latrace ls
168
169       ·   To change the libkrava1.so dependency to the libkrava2.so run one
170           of these:
171
172               latrace -L krava1%krava2 ex
173
174               latrace -L krava1~libkrava2.so ex
175
176               latrace -L libkrava1.so=libkrava2.so ex
177

DISCUSSION

179   NAMES CHECK
180       For options "-l -t -f -s -n -b" the * symbol can be used to switch to
181       the substring search. If it is not specified, the exact search for the
182       name is done.
183
184       Examples:
185
186           -s "*krava" checks for symbols with "krava" substring.
187
188           -s "krava"  checks only for "krava" symbol
189
190   LD_AUDIT
191       This is just a brief and vague description of the LD_AUDIT feature. For
192       more information look to rtld-audit(7) man done by Petr Baudis or study
193       the glibc/latrace source code. Very brief explanation follows.
194
195       The libc dynamic linker audit feature allows to trace/audit program’s
196       symbols/libraries. The feature is enabled by the LD_AUDIT environment
197       variable. This variable must contain path to the audit shared library.
198       This audit library needs to follow specific interface. The interface
199       functions will be then called by the dynamic linker appropriatelly.
200
201       The audit library needs to export following symbols (the "la_PLTENTER"
202       and "la_PLTEXIT" names are architecture dependent).
203
204           "la_activity"
205           "la_objsearch"
206           "la_objopen"
207           "la_preinit"
208           "la_symbind32"
209           "la_symbind64"
210           "la_PLTENTER"
211           "la_PLTEXIT"
212           "la_objclose"
213
214       As for the latrace package the audit shared library is called
215       libltaudit.so.
216
217   OBJSEARCH
218       The objsearch LD_AUDIT interface provide means for changing traced
219       program shared object names/locations. The -L option argument should
220       have following form:
221
222       -L s1[,s2,...] where sN is src [=%~] dst
223
224       The src is the source pattern/name and dst is the destination
225       name/pattern.
226
227
228       =   Comparing src with the
229           library name. If matched,
230           replace the library name
231           with dst.
232                      library name         - /lib/krava1.so
233                      src                  - /lib/krava1.so
234                      dst                  - /lib/krava2.so
235
236                      final library name   - /lib/krava2.so
237
238
239       %   Looking for the src in the library name. If
240           found, replace the src with dst part.
241                      library name         - /lib/krava1.so
242                      src                  - krava1
243                      dst                  - krava2
244
245                      final library name   - /lib/krava2.so
246
247
248       ~   Looking for the src in the library name. If
249           found, replace the library name with dst.
250                      library name         - /lib/krava1.so
251                      src                  - krava1
252                      dst                  - /lib/krava2.so
253
254                      final library name   - /lib/krava2.so
255
256
257
258   PIPE mode
259       The latrace can work in two modes. The first one native does does the
260       output directly in the traced program process. The other one, pipe mode
261       use the IPC fifo mechanism to send the data from the traced process to
262       the latrace process. The latrace process is then responsible for the
263       output. Using the pipe mode you loose the traced program standard
264       output context with printed symbols.
265
266       By using the pipe mode, the latrace is not dependent on the trace
267       program usage/manipulation of the standard output descriptor. Also the
268       symbol statistics counts -c, -C options use the pipe mode to transfer
269       symbol information to the latrace binary, and the latrace binary does
270       the counts at the end.
271
272   CONFIG
273       The latrace provide possibility to enable/disable some of the options
274       by means of configuration file. Some of the options are linked to the
275       command line arguments some of them are not. When latrace starts the
276       global configuration file is read. This file is usually being placed in
277       here:
278
279           /etc/latrace.d/latrace.conf
280
281       Having default values read from this file, user can overload any of
282       them by command line options or by supling another config file via -N,
283       --conf option.
284
285       The configuration file syntax is roughly:
286
287           INCLUDE <anotherconfigfile>
288
289           OPTIONS {
290                   OPTION1 = VALUE
291                   OPTION2 = YES|NO
292                   ...
293                   OPTIONN = VALUE
294           }
295
296           # comment
297
298       Configuration file options
299
300       HEADERS = FILE
301           -a, --args
302
303       INDENT_SYM = VALUE
304           -i, --indent-sym
305
306       PIPE = BOOL
307           -p, --pipe
308
309       TIMESTAMP = BOOL
310           -S, --timestamp
311
312       FRAMESIZE = VALUE
313           -y, --framesize
314
315       FRAMESIZE_CHECK = BOOL
316           -Y, --no-framesize-check
317
318       HIDE_TID = BOOL
319           -T, --hide-tid
320
321       FOLLOW_FORK = BOOL
322           -F, --no-follow-fork
323
324       FOLLOW_EXEC = BOOL
325           -E, --no-follow-exec
326
327       DEMANGLE = BOOL
328           -d, --demangle
329
330       BRACES = BOOL
331           -B, --braces
332
333       ENABLE_ARGS = BOOL
334           -A, --enable-args
335
336       DETAIL_ARGS = BOOL
337           -D, --detail-args
338
339       OUTPUT_TTY = FILE
340
341           ·   stores tracee terminal output to the file
342
343       LIBS = LIB1[,LIB2,...]
344           -l, --libs
345
346       LIBS_TO = LIB1[,LIB2,...]
347           -t, --libs-to
348
349       LIBS_FROM = LIB1[,LIB2,...]
350           -f, --libs-from
351
352       SYM = SYM1[,SYM2,...]
353           -s, --sym
354
355       SYM_OMIT = SYM1[,SYM2,...]
356           -n, --sym-omit
357
358       SYM_BELOW = SYM1[,SYM2,...]
359           -b, --flow-below
360
361       SYM_NOEXIT = SYM1[,SYM2,...]
362
363           ·   symbols which do no run exit callback (plt_exit)
364
365       ARGS_STRING_POINTER_LENGTH = BOOL
366
367           ·   function arguments - display string length and pointer value
368
369   HEADERS
370       The latrace header file allows user to define symbols as an classic C
371       functions with arguments. Argument names will be displayed together
372       with values as the latrace output. The more arguments are defined, the
373       more performance and memory penalties should be expected.
374
375       The package is delivered with several predefined header files for the
376       most commonly used functions. List of the glibc header files used
377       follows (the list mostly follows the ltrace header files list, and
378       author is willing to update it according to the needs)
379
380           ctype.h dirent.h dlfcn.h fcntl.h getopt.h inet.h ioctl.h
381           libintl.h libio.h locale.h misc.h mman.h ncurses.h netdb.h
382           pthread.h pwd.h resource.h signal.h socket.h stat.h stdio.h
383           stdlib.h string.h syslog.h term.h termios.h time.h typedefs.h
384           unistd.h utmp.h wait.h
385
386       The latrace header files are usually stored under directory:
387
388           /etc/latrace.d/headers/
389
390       User can specify single header file using command line option or
391       configuration file. This file then can include other needed headers. As
392       already mentioned, the latrace config file syntax lightly follows the C
393       language syntax. Following part describes the latrace config file
394       language.
395
396       ·   Several POD types (plain old data), are hardcoded in latrace. Size
397           of those arguments is determined by the sizeof macro. The list
398           follows.
399
400               void
401               char    u_char
402               short   u_short
403               int     u_int
404               long    u_long
405               llong   u_llong  # (long long)
406               float   double
407
408       ·   The typedef keyword allows to specify new type based on the already
409           existing one (POD or typedefed). Eventhough there’s a way for
410           multiple pointer layers in the type definition (*), only one is
411           taken.
412
413               typedef base_type new_type;
414               typedef base_type * new_type;
415               typedef base_type ** new_type;
416
417       ·   Comments follow the C style /\* \*/ logic.
418
419           /\* comments \*/
420
421       ·   The include keyword allows to include another config file.
422
423           #include "filename"
424
425       ·   The struct keyword allows to define the structure. The syntax
426           folows following grammar rules.
427
428               START::         struct NAME { STRUCT_DEF };
429               STRUCT_DEF::    DEF | EMPTY
430               DEF::           NAME NAME |
431                               NAME '*' NAME |
432                               struct NAME NAME |
433                               struct NAME '*' NAME
434               NAME::          [-0-9a-zA-Z_]+
435
436       ·   The function definition follows following syntax (DEF and NAME are
437           the same as for struct definition).
438
439               START::         DEF '(' ARGS ')' ';'
440               ARGS::          ARGS ',' DEF | DEF | EMPTY
441
442       ·   The enum definition follows following syntax (NAME is same as for
443           struct definition).
444
445               START::         ENUM NAME '{' ENUM_DEF '}' ';'
446               ENUM_DEF::      ENUM_DEF ',' ENUM_ELEM | ENUM_ELEM
447               ENUM_ELEM::     NAME '=' NAME | NAME
448
449       ·   Example of a simple latrace config file.
450
451               ---[ cut here ]-----------------------------
452               enum krava {
453                       krava1 = 1,
454                       krava2,
455                       krava3 = 100
456               };
457
458               #include "krava.conf"
459
460               typedef u_int pid_t;
461
462               struct ex_st {
463                       pid_t   p;
464                       int     cnt;
465                       char   *name;
466               };
467
468               int f1(pid_t p, struct ex_st *k);
469               int f2(char* name, struct ex_st k, int k = krava);
470               struct ex_st* f3(pid_t *p, struct ex_st k);
471               ---[ cut here ]-----------------------------
472
473       ·   Arrays are not supported yet, so there’s no way to define some
474           structures. For such a structures use void* type where the
475           structure argu- ment is passed by pointer. If it is passed by
476           value, there’s no workaround so far (aside from filling the
477           structure body with POD types up to the actual length of the
478           structure :).
479
480       ·   Variable argument lists (va_list/...) are not supported yet. The
481           function definition needs to stop before the first variable
482           argument list argument.
483

PORTS

485       The latrace should work on any glibc system with LD_AUDIT support.
486       However arguments details are architecture specific and need special
487       support inside latrace itself.
488
489       Author is willing to port the latrace to any architecture, as long as
490       he got an access to corresponding system. Currently functional ports
491       are:
492
493
494       x86      ok
495
496       x86_64   ok
497
498       arm      ok
499
500

BUGS

502       MANY, plz report bugs to <latrace@lists.fedorahosted.org[1]> or
503       <olsajiri@gmail.com[2]>.
504
505       You can also visit the http://people.redhat.com/jolsa/latrace/ page to
506       see the latest release notes information.
507
508       LD_AUDIT related glibc bugs:
509
510       ·   Bug 7055 (no longer reproducible)
511
512       ·   Bug 9893 (FIXED in 2.10)
513
514       ·   Bug 3924 (FIXED in 2.7-2)
515

AUTHOR

517       Jiri Olsa <olsajiri@gmail.com[2]>
518

CONTRIBUTORS

520       ·   Nix <nix@esperi.org.uk[3]>
521
522       ·   Akos Pasztory <akos.pasztory@gmail.com[4]>
523
524       ·   Artur Skawina <art.08.09@gmail.com[5]>
525
526       ·   Dr. David Alan Gilbert <david.gilbert@linaro.org[6]>
527
528       ·   Sebastian Pipping <sping@gentoo.org[7]>
529

LICENSE

531       This is free software, distributed under the GPLv3 license.
532

SEE ALSO

534       strace(1), ltrace(1)
535

AUTHOR

537       Jiri Olsa <olsajiri@gmail.com>
538           Author.
539

NOTES

541        1. latrace@lists.fedorahosted.org
542           mailto:latrace@lists.fedorahosted.org
543
544        2. olsajiri@gmail.com
545           mailto:olsajiri@gmail.com
546
547        3. nix@esperi.org.uk
548           mailto:nix@esperi.org.uk
549
550        4. akos.pasztory@gmail.com
551           mailto:akos.pasztory@gmail.com
552
553        5. art.08.09@gmail.com
554           mailto:art.08.09@gmail.com
555
556        6. david.gilbert@linaro.org
557           mailto:david.gilbert@linaro.org
558
559        7. sping@gentoo.org
560           mailto:sping@gentoo.org
561
562
563
564  0.5.11                         November 2015                      LATRACE(1)
Impressum