1LATRACE(1) LATRACE(1)
2
6 latrace - LD_AUDIT 2.4+ libc frontend
7
9 latrace [-snltfvhiBdISbcCyYLpoaNADVTFERq] command [arg ... ]
10
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 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 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 The latrace use is similar to strace(1) and ltrace(1).
29
31 -l, --libs lib1[,lib2,...]
32 audit from and to lib1, lib2 ...
33 -t, --libs-to lib1[,lib2,...]
35 audit to lib1, lib2 ...
36 -f, --libs-from lib1[,lib2,...]
38 audit from lib1, lib2 ...
39 -s, --sym sym1[,sym2,...]
41 audit symbols sym1, sym2 ...
42 -n, --sym-omit sym1[,sym2,...]
44 omit symbols sym1, sym2 ...
45 -L, --lib-subst s1[,s2,...]
47 objsearch LD_AUDIT interface (See the section called “OBJSEARCH”)
48 -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 -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 -p, --pipe
58 use pipe to latrace process to send audit data (see the section
59 called “PIPE mode”)
60 -N, --conf
62 config file (see the section called “CONFIG”)
63 -A, --enable-args
65 enable arguments output (definitions from /etc/latrace.conf)
66 -D, --detail-args
68 display struct arguments in more detail
69 -a, --args file
71 specify arguments definition file, implies -A (without the default
72 definition file of course)
73 -y, --framesize number
75 framesize for storing the stack before pltexit (default 100)
76 -Y, --no-framesize-check
78 disable framesize check
79 -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 -E, --no-follow-exec
86 dont follow exec calls
87 -S, --timestamp
89 display timestamp for each symbol
90 -b, --flow-below sym1[,sym2,...]
92 display flow for sym1, sym2 ...
93 -I, --no-indent-sym
95 do no indent symbols based on the their stack depth
96 -i, --indent-sym indent_size
98 indent size specification in indent_size
99 -B, --braces
101 allways display { } for the around the symbol body
102 -d, --demangle
104 C++ demangle symbols on the output
105 -T, --hide-tid
107 dont display thread id
108 -o, --output file
110 store output to file
111 -R, --ctl-config
113 controled config feature
114 -q, --disable
116 run with disabled auditing
117 -v, --verbose
119 verbose output
120 -V, --version
122 display version
123 -h, --help
125 display help
126
128 · The simplest way to run latrace is like this:
129 latrace cat
131 · To see the argument values specified by default config file run:
133 latrace -A cat
135 · Same as above but using the pipe mode to get all the end symbols
137 printed:
138 latrace -Ap cat
140 · To see the argument values specified by specified config file run:
142 latrace -a latrace.conf cat
144 · To get output only for specified symbol (eg. read and write) run:
146 latrace -A -s read,write cat
148 · To get flow under the specified symbol (eg. sysconf) run:
150 latrace -b sysconf kill
152 · To get output only for specified library (eg. libproc) run:
154 latrace -Al libproc w
156 · To get symbol statistics run:
158 latrace -c ls
160 · To get symbol statistics sorted by time run:
162 latrace -C time ls
164 · To get output stored to the text file run:
166 latrace -o output.latrace ls
168 · To change the libkrava1.so dependency to the libkrava2.so run one
170 of these:
171 latrace -L krava1%krava2 ex
173 latrace -L krava1~libkrava2.so ex
175 latrace -L libkrava1.so=libkrava2.so ex
177
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 Examples:
185 -s "*krava" checks for symbols with "krava" substring.
187 -s "krava" checks only for "krava" symbol
189 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 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 The audit library needs to export following symbols (the "la_PLTENTER"
202 and "la_PLTEXIT" names are architecture dependent).
203 "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 As for the latrace package the audit shared library is called
215 libltaudit.so.
216 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 -L s1[,s2,...] where sN is src [=%~] dst
223 The src is the source pattern/name and dst is the destination
225 name/pattern.
226 = 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 final library name - /lib/krava2.so
237 % 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 final library name - /lib/krava2.so
246 ~ 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 final library name - /lib/krava2.so
255 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 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 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 /etc/latrace.d/latrace.conf
280 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 The configuration file syntax is roughly:
286 INCLUDE <anotherconfigfile>
288 OPTIONS {
290 OPTION1 = VALUE
291 OPTION2 = YES|NO
292 ...
293 OPTIONN = VALUE
294 }
295 # comment
297 Configuration file options
299 HEADERS = FILE
301 -a, --args
302 INDENT_SYM = VALUE
304 -i, --indent-sym
305 PIPE = BOOL
307 -p, --pipe
308 TIMESTAMP = BOOL
310 -S, --timestamp
311 FRAMESIZE = VALUE
313 -y, --framesize
314 FRAMESIZE_CHECK = BOOL
316 -Y, --no-framesize-check
317 HIDE_TID = BOOL
319 -T, --hide-tid
320 FOLLOW_FORK = BOOL
322 -F, --no-follow-fork
323 FOLLOW_EXEC = BOOL
325 -E, --no-follow-exec
326 DEMANGLE = BOOL
328 -d, --demangle
329 BRACES = BOOL
331 -B, --braces
332 ENABLE_ARGS = BOOL
334 -A, --enable-args
335 DETAIL_ARGS = BOOL
337 -D, --detail-args
338 OUTPUT_TTY = FILE
340 · stores tracee terminal output to the file
342 LIBS = LIB1[,LIB2,...]
344 -l, --libs
345 LIBS_TO = LIB1[,LIB2,...]
347 -t, --libs-to
348 LIBS_FROM = LIB1[,LIB2,...]
350 -f, --libs-from
351 SYM = SYM1[,SYM2,...]
353 -s, --sym
354 SYM_OMIT = SYM1[,SYM2,...]
356 -n, --sym-omit
357 SYM_BELOW = SYM1[,SYM2,...]
359 -b, --flow-below
360 SYM_NOEXIT = SYM1[,SYM2,...]
362 · symbols which do no run exit callback (plt_exit)
364 ARGS_STRING_POINTER_LENGTH = BOOL
366 · function arguments - display string length and pointer value
368 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 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 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 The latrace header files are usually stored under directory:
387 /etc/latrace.d/headers/
389 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 · 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 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 · 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 typedef base_type new_type;
414 typedef base_type * new_type;
415 typedef base_type ** new_type;
416 · Comments follow the C style /\* \*/ logic.
418 /\* comments \*/
420 · The include keyword allows to include another config file.
422 #include "filename"
424 · The struct keyword allows to define the structure. The syntax
426 folows following grammar rules.
427 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 · The function definition follows following syntax (DEF and NAME are
437 the same as for struct definition).
438 START:: DEF '(' ARGS ')' ';'
440 ARGS:: ARGS ',' DEF | DEF | EMPTY
441 · The enum definition follows following syntax (NAME is same as for
443 struct definition).
444 START:: ENUM NAME '{' ENUM_DEF '}' ';'
446 ENUM_DEF:: ENUM_DEF ',' ENUM_ELEM | ENUM_ELEM
447 ENUM_ELEM:: NAME '=' NAME | NAME
448 · Example of a simple latrace config file.
450 ---[ cut here ]-----------------------------
452 enum krava {
453 krava1 = 1,
454 krava2,
455 krava3 = 100
456 };
457 #include "krava.conf"
459 typedef u_int pid_t;
461 struct ex_st {
463 pid_t p;
464 int cnt;
465 char *name;
466 };
467 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 · 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 · 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
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 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 x86 ok
495 x86_64 ok
497 arm ok
499
502 MANY, plz report bugs to <latrace@lists.fedorahosted.org[1]> or
503 <olsajiri@gmail.com[2]>.
504 You can also visit the http://people.redhat.com/jolsa/latrace/ page to
506 see the latest release notes information.
507 LD_AUDIT related glibc bugs:
509 · Bug 7055 (no longer reproducible)
511 · Bug 9893 (FIXED in 2.10)
513 · Bug 3924 (FIXED in 2.7-2)
515
517 Jiri Olsa <olsajiri@gmail.com[2]>
518
520 · Nix <nix@esperi.org.uk[3]>
521 · Akos Pasztory <akos.pasztory@gmail.com[4]>
523 · Artur Skawina <art.08.09@gmail.com[5]>
525 · Dr. David Alan Gilbert <david.gilbert@linaro.org[6]>
527 · Sebastian Pipping <sping@gentoo.org[7]>
529
531 This is free software, distributed under the GPLv3 license.
532
534 strace(1), ltrace(1)
535
537 Jiri Olsa <olsajiri@gmail.com>
538 Author.
539
541 1. latrace@lists.fedorahosted.org
542 mailto:latrace@lists.fedorahosted.org
543 2. olsajiri@gmail.com
545 mailto:olsajiri@gmail.com
546 3. nix@esperi.org.uk
548 mailto:nix@esperi.org.uk
549 4. akos.pasztory@gmail.com
551 mailto:akos.pasztory@gmail.com
552 5. art.08.09@gmail.com
554 mailto:art.08.09@gmail.com
555 6. david.gilbert@linaro.org
557 mailto:david.gilbert@linaro.org
558 7. sping@gentoo.org
560 mailto:sping@gentoo.org
561 0.5.11 February 2017 LATRACE(1)