1LATRACE(1) [FIXME: manual] LATRACE(1)
2
6 latrace - LD_AUDIT 2.4+ libc frontend
7
9 latrace [-ltfsbcCpADaoyIiBdvTFELVh] command [arg ... ]
10
12 latrace is able to run a command and display its dynamic library calls
13 using a LD_AUDIT libc feature (available from libc version 2.4 onward -
14 see the section called “DISCUSSION” ). It is also capable to measure
15 and display various statistics of dynamic calls.
16 If the config file is provided, latrace will display symbol’s arguments
18 with detailed output for structures. The config file syntax is similar
19 to the C language, with several exceptions (see the section called
20 “CONFIG”).
21 The latrace by default fully operates inside of the traced program.
23 However another pipe mode is available, to move the main work to the
24 latrace binary (see the section called “PIPE mode”).
25 Its use is very similar to strace(1) and ltrace(1).
27
29 -l, --libs lib1[,lib2,...]
30 audit from and to lib1, lib2 ...
31 -t, --libs-to lib1[,lib2,...]
33 audit to lib1, lib2 ...
34 -f, --libs-from lib1[,lib2,...]
36 audit from lib1, lib2 ...
37 -s, --sym sym1[,sym2,...]
39 audit symbols sym1, sym2 ...
40 -S, --timestamp
42 display timestamp for each symbol
43 -b, --flow-below sym1[,sym2,...]
45 display flow for sym1, sym2 ...
46 -c, --counts
48 display statistics counts of symbols - implies pipe mode (see the
49 section called “PIPE mode”) an no symbol output is displayed
50 -C, --sort-counts stat
52 implies -c, plus sort the statistics by stat with following values:
53 time,per,call,ucall,lib,sym (default is call)
54 -p, --pipe
56 use pipe to latrace process to send audit data (see the section
57 called “PIPE mode”)
58 -o, --output file
60 store output to file
61 -A, --enable-args
63 enable arguments output (definitions from /etc/latrace.conf)
64 -D, --detail-args
66 display struct arguments in more detail
67 -a, --args file
69 specify arguments definition file, implies -A (without the default
70 definition file of course)
71 -y, --framesize number
73 framesize for storing the stack before pltexit (default 100)
74 -I, --no-indent-sym
76 do no indent symbols based on the their stack depth
77 -i, --indent-sym indent_size
79 indent size specification in indent_size
80 -B, --braces
82 allways display { } for the around the symbol body
83 -d, --demangle
85 C++ demangle symbols on the output
86 -v, --verbose
88 verbose output
89 -T, --hide-tid
91 dont display thread id
92 -F, --not-follow-fork
94 dont follow fork calls (childs). This is just supressing the
95 latrace output from new childs. The nature of the LD_AUDIT feature
96 prevents to disable it completely.
97 -E, --not-follow-exec
99 dont follow exec calls
100 -R, --ctl-config
102 controled config feature
103 -q, --disable
105 run with disabled auditing (enabled -R)
106
108 · The simplest way to run latrace is like this:
109 · latrace cat**
111 · To see the argument values specified by default config file run:
113 · latrace -A cat**
115 · Same as above but using the pipe mode to get all the end symbols
117 printed:
118 · latrace -Ap cat**
120 · To see the argument values specified by specified config file run:
122 · latrace -a latrace.conf cat**
124 · To get output only for specified symbol (eg. read and write) run:
126 · latrace -A -s read,write cat**
128 · To get flow under the specified symbol (eg. sysconf) run:
130 · latrace -b sysconf kill**
132 · To get output only for specified library (eg. libproc) run:
134 · latrace -Al libproc w**
136 · To get symbol statistics run:
138 · latrace -c ls**
140 · To get symbol statistics sorted by time run:
142 · latrace -C time ls**
144 · To get output stored to the text file run:
146 · latrace -o output.latrace ls**
148 · To change the libkrava1.so dependency to the libkrava2.so run one
150 of these:
151 · latrace -L krava1%krava2 ex**
153 · latrace -L krava1~libkrava2.so ex**
155 · latrace -L libkrava1.so=libkrava2.so ex**
157
159 LD_AUDIT
160 This is just a brief and vague description of the LD_AUDIT feature. For
161 more information look to rtld-audit(7) man done by Petr Baudis or study
162 the glibc/latrace source code. Very brief explanation follows.
163 The libc dynamic linker audit feature allows to trace/audit program’s
165 symbols/libraries. The feature is enabled by the LD_AUDIT environment
166 variable. This variable must contain path to the audit shared library.
167 This audit library needs to follow specific interface. The interface
168 functions will be then called by the dynamic linker appropriatelly.
169 The audit library needs to export following symbols (the "la_PLTENTER"
171 and "la_PLTEXIT" names are architecture dependent).
172 "la_activity"
174 "la_objsearch"
175 "la_objopen"
176 "la_preinit"
177 "la_symbind32"
178 "la_symbind64"
179 "la_PLTENTER"
180 "la_PLTEXIT"
181 "la_objclose"
182 +
184 As for the latrace package the audit shared library is called
186 libltaudit.so.
187 OBJSEARCH
189 The objsearch LD_AUDIT interface provide means for changing traced
190 program shared object names/locations. The -L option argument should
191 have following form:
192 -L s1[,s2,...] where sN is src [=%~] dst
194 The src is the source pattern/name and dst is the destination
196 name/pattern.
197 = Comparing src with the
201 library name. If matched,
202 replace the library name
203 with dst.
204 library name - /lib/krava1.so
205 src - /lib/krava1.so
206 dst - /lib/krava2.so
207 final library name - /lib/krava2.so
209 % Looking for the src in the library name. If
212 found, replace the src with dst part.
213 library name - /lib/krava1.so
214 src - krava1
215 dst - krava2
216 final library name - /lib/krava2.so
218 ~ Looking for the src in the library name. If
221 found, replace the library name with dst.
222 library name - /lib/krava1.so
223 src - krava1
224 dst - /lib/krava2.so
225 final library name - /lib/krava2.so
227 PIPE mode
231 The latrace can work in two modes. The first one native does does the
232 output directly in the traced program process. The other one, pipe mode
233 use the IPC fifo mechanism to send the data from the traced process to
234 the latrace process. The latrace process is then responsible for the
235 output. Using the pipe mode you loose the traced program standard
236 output context with printed symbols.
237 By using the pipe mode, the latrace is not dependent on the trace
239 program usage/manipulation of the standard output descriptor. Also the
240 symbol statistics counts -c, -C options use the pipe mode to transfer
241 symbol information to the latrace binary, and the latrace binary does
242 the counts at the end.
243 CONFIG
245 The latrace config file allows user to define symbols as an classic C
246 functions with arguments. Argument names will be display together with
247 values as the latrace output. The more arguments are defined, the more
248 performance and memory penalties should be expected.
249 The package is delivered with several config files for the most
251 commonly used functions. List of the glibc header files used follows
252 (the list mostly follows the ltrace header files list, and author is
253 willing to update it according to the needs.
254 /usr/include/arpa/inet.h
256 /usr/include/ctype.h
257 /usr/include/stdlib.h
258 /usr/include/string.h
259 /usr/include/ctype.h
260 /usr/include/ncurses.h
261 /usr/include/stdio.h
262 /usr/include/dirent.h
263 /usr/include/unistd.h
264 /usr/include/libintl.h
265 /usr/include/dlfcn.h
266 /usr/include/fcntl.h
267 /usr/include/getopt.h
268 /usr/include/signal.h
269 /usr/include/sys/ioctl.h
270 /usr/include/sys/socket.h
271 /usr/include/netdb.h
272 /usr/include/pthread.h
273 /usr/include/sys/resource.h
274 /usr/include/sys/mman.h
275 +
277 The config file structure consists of /etc/latrace.conf file, which is
279 the default one read by latrace. This config file includes other config
280 files placed in the /etc/latrace.d directory. This directory contain
281 all the config files for the above mentioned header files.
282 As already mentioned, the latrace config file syntax lightly follows
284 the C language syntax. Following part describes the latrace config file
285 language.
286 · Several POD types (plain old data), are hardcoded in latrace. Size
288 of those arguments is determined by the sizeof macro. The list
289 follows.
290 void
292 char u_char
293 short u_short
294 int u_int
295 long u_long
296 llong u_llong # (long long)
297 float double
298 · The typedef keyword allows to specify new type based on the already
300 existing one (POD or typedefed). Eventhough there’s a way for
301 multiple pointer layers in the type definition (*), only one is
302 taken.
303 typedef base_type new_type;
305 typedef base_type * new_type;
306 typedef base_type ** new_type;
307 · Comments follow the C style /\* \*/ logic.
309 /\* comments \*/
311 · The include keyword allows to include another config file.
313 #include "filename"
315 · The struct keyword allows to define the structure. The syntax
317 folows following grammar rules.
318 START:: struct NAME { STRUCT_DEF };
320 STRUCT_DEF:: DEF | EMPTY
321 DEF:: NAME NAME |
322 NAME ´*´ NAME |
323 struct NAME NAME |
324 struct NAME ´*´ NAME
325 NAME:: [-0-9a-zA-Z_]+
326 · The function definition follows following syntax (DEF and NAME are
328 the same as for struct definition).
329 START:: DEF ´(´ ARGS ´)´ ´;´
331 ARGS:: ARGS ´,´ DEF | DEF | EMPTY
332 · The enum definition follows following syntax (NAME is same as for
334 struct definition).
335 START:: ENUM NAME ´{´ ENUM_DEF ´}´ ´;´
337 ENUM_DEF:: ENUM_DEF ´,´ ENUM_ELEM | ENUM_ELEM
338 ENUM_ELEM:: NAME ´=´ NAME | NAME
339 · Example of a simple latrace config file.
341 ---[ cut here ]-----------------------------
343 enum krava {
344 krava1 = 1,
345 krava2,
346 krava3 = 100
347 };
348 #include "krava.conf"
350 typedef u_int pid_t;
352 struct ex_st {
354 pid_t p;
355 int cnt;
356 char *name;
357 };
358 int f1(pid_t p, struct ex_st *k);
360 int f2(char* name, struct ex_st k, int k = krava);
361 struct ex_st* f3(pid_t *p, struct ex_st k);
362 ---[ cut here ]-----------------------------
363 · Arrays are not supported yet, so there’s no way to define some
365 structures. For such a structures use void* type where the
366 structure argu- ment is passed by pointer. If it is passed by
367 value, there’s no workaround so far (aside from filling the
368 structure body with POD types up to the actual length of the
369 structure :).
370 · Variable argument lists (va_list/...) are not supported yet. The
372 function definition needs to stop before the first variable
373 argument list argument.
374
376 Author is willing to port the latrace to any architecture, as long as
377 he got an access to corresponding system. Currently functional ports
378 are:
379 x86 ok
382 x86_64 ok
384 arm ok (contributed and
386 maintained by Akos
387 Pasztory)
388 LD_AUDIT related glibc bugs:
391 · Bug 7055 (no longer reproducible) LD_AUDIT - gettimeofday function
393 segfaults if called from interface
394 http://sources.redhat.com/bugzilla/show_bug.cgi?id=7055
395 · Bug 9893 (FIXED in 2.10) LD_AUDIT - misaligned _dl_call_pltexit
397 parameter causing crash in audit library
398 http://sources.redhat.com/bugzilla/show_bug.cgi?id=9893
399 · Bug 3924 (FIXED in 2.7-2) LD_AUDIT implementation causing process
401 segfaulting http://sourceware.org/bugzilla/show_bug.cgi?id=3924
402
404 MANY, plz report bugs to <olsajiri@gmail.com[1]>. You can also visit
405 the latrace.sf.net page to see the latest release notes information.
406
408 Jiri Olsa <olsajiri@gmail.com[1]>
409
411 · Nix <nix@esperi.org.uk[2]>
412 · Akos Pasztory <akos.pasztory@gmail.com[3]>
414
416 This is free software, distributed under the GPLv3 license.
417
419 strace(1), ltrace(1)
420
422 1. olsajiri@gmail.com
423 mailto:olsajiri@gmail.com
424 2. nix@esperi.org.uk
426 mailto:nix@esperi.org.uk
427 3. akos.pasztory@gmail.com
429 mailto:akos.pasztory@gmail.com
430[FIXME: source] 11/11/2010 LATRACE(1)