1ltrace.conf(5)             ltrace configuration file            ltrace.conf(5)
2
3
4

NAME

6       ltrace.conf - Configuration file for ltrace(1).
7
8

DESCRIPTION

10       This  manual  page  describes ltrace.conf, a file that describes proto‐
11       types of functions in binaries for ltrace(1) to use.  Ltrace needs this
12       information to display function call arguments.
13
14       Each  line  of  a  configuration  file describes at most a single item.
15       Lines composed entirely of white space are ignored, as are lines start‐
16       ing  with  semicolon character (comment lines).  Described items can be
17       either function prototypes, or definitions of type aliases.
18
19

PROTOTYPES

21       A prototype describes return type and parameter types of a single func‐
22       tion.  The syntax is as follows:
23
24              LENS NAME ([LENS{,LENS}]);
25
26       NAME  is  the (mangled) name of a symbol.  In the elementary case, LENS
27       is simply a type.  Both lenses and  types  are  described  below.   For
28       example, a simple function prototype might look like this:
29
30              int kill(int,int);
31
32       Despite  the  apparent similarity with C, ltrace.conf is really its own
33       language that's only somewhat inspired by C.
34
35

TYPES

37       Ltrace understands a range of primitive types.  Those  are  interpreted
38       according  to  C convention native on a given architecture.  E.g. ulong
39       is interpreted as 4-byte unsigned integer on 32-bit GNU/Linux  machine,
40       but 8-byte unsigned integer on 64-bit GNU/Linux machine.
41
42
43       void   Denotes  that  a function does not return anything.  Can be also
44              used to construct a generic pointer, i.e.  pointer-sized  number
45              formatted in hexadecimal format.
46
47       char   8-bit quantity rendered as a character
48
49       ushort,short
50              Denotes unsigned or signed short integer.
51
52       uint,int
53              Denotes unsigned or signed integer.
54
55       ulong,long
56              Denotes unsigned or signed long integer.
57
58       float  Denotes floating point number with single precision.
59
60       double Denotes floating point number with double precision.
61
62       Besides primitive types, the following composed types are possible:
63
64
65       struct([LENS{,LENS}])
66              Describes   a   structure  with  given  types  as  fields,  e.g.
67              struct(int,int,float).
68
69              Alignment is computed as customary on the architecture.   Custom
70              alignment  (e.g.  packed  structs)  and  bit-fields are not sup‐
71              ported.  It's also not possible to differentiate between structs
72              and non-POD C++ classes, for arches where it makes a difference.
73
74
75       array(LENS,EXPR)
76              Describes  array  of  length  EXPR,  which  is composed of types
77              described by LENS, e.g. array(int, 6).
78
79              Note that in C, arrays in role of function argument  decay  into
80              pointers.   Ltrace currently handles this automatically, but for
81              full formal correctness, any such arguments should be  described
82              as pointers to arrays.
83
84
85       LENS*  Describes a pointer to a given type, e.g. char* or int***.  Note
86              that the former example actually describes a pointer to a  char‐
87              acter, not a string.  See below for string lens, which is appli‐
88              cable to these cases.
89
90

LENSES

92       Lenses change the way that types are described.  In the simplest  case,
93       a  lens is directly a type.  Otherwise a type is decorated by the lens.
94       Ltrace understands the following lenses:
95
96
97       oct(TYPE)
98              The argument, which should be an integer type, is  formatted  in
99              base-8.
100
101
102       hex(TYPE)
103              The argument, which should be an integer or floating point type,
104              is formatted in base-16.  Floating point arguments are converted
105              to double and then displayed using the %a fprintf modifier.
106
107
108       hide(TYPE)
109              The argument is not shown in argument list.
110
111
112       bool(TYPE)
113              Arguments with zero value are shown as "false", others are shown
114              as "true".
115
116
117       bitvec(TYPE)
118              Underlying argument is interpreted as a bit vector and a summary
119              of  bits  set  in  the vector is displayed.  For example if bits
120              3,4,5 and 7 of the bit vector are  set,  ltrace  shows  <3-5,7>.
121              Empty bit vector is displayed as <>.  If there are more bits set
122              than unset, inverse is shown instead: e.g. ~<0>  when  a  number
123              0xfffffffe is displayed.  Full set is thus displayed ~<>.
124
125              If the underlying type is integral, then bits are shown in their
126              natural  big-endian  order,  with  LSB  being   bit   0.    E.g.
127              bitvec(ushort)  with  value  0x0102 would be displayed as <1,8>,
128              irrespective of underlying byte order.
129
130              For other data types (notably structures and arrays), the under‐
131              lying  data is interpreted byte after byte.  Bit 0 of first byte
132              has number 0, bit 0 of second byte number 8, and  so  on.   Thus
133              bitvec(struct(int))  is  endian  sensitive,  and will show bytes
134              comprising the integer in  their  memory  order.   Pointers  are
135              first  dereferenced, thus bitvec(array(char, 32)*) is actually a
136              pointer to 256-bit bit vector.
137
138
139       string(TYPE)
140       string[EXPR]
141       string
142              The first form of the argument is canonical, the latter two  are
143              syntactic  sugar.   In the canonical form, the function argument
144              is formatted as string.  The TYPE shall be either  a  char*,  or
145              array(char,EXPR),  or  array(char,EXPR)*.  If an array is given,
146              the length will typically be a zero expression (but doesn't have
147              to  be).  Using argument that is plain array (i.e. not a pointer
148              to  array)  makes  sense  e.g.  in  C  structs,  in  cases  like
149              struct(string(array(char,  6))),  which  describes  the  C  type
150              struct {char s[6];}.
151
152              Because simple C-like strings are pretty common, there  are  two
153              shorthand forms.  The first shorthand form (with brackets) means
154              the same as string(array(char, EXPR)*).  Plain string without an
155              argument is then taken to mean the same as string[zero].
156
157              Note that char* by itself describes a pointer to a char.  Ltrace
158              will dereference the pointer, and read and  display  the  single
159              character that it points to.
160
161       enum(NAME[=VALUE]{,NAME[=VALUE]})
162       enum[TYPE](NAME[=VALUE]{,NAME[=VALUE]})
163              This  describes  an enumeration lens.  If an argument has any of
164              the given values, it is instead shown as the corresponding NAME.
165              If  a  VALUE  is  omitted,  the next consecutive value following
166              after the previous VALUE is taken instead.  If the  first  VALUE
167              is omitted, it's 0 by default.
168
169              TYPE,  if given, is the underlying type.  It is thus possible to
170              create enums over shorts or longs—arguments that are  themselves
171              plain, non-enum types in C, but whose values can be meaningfully
172              described as enumerations.  If omitted, TYPE is taken to be int.
173
174

TYPE ALIASES

176       A line in config file can, instead of describing a prototype, create  a
177       type  alias.  Instead of writing the same enum or struct on many places
178       (and possibly updating when it changes), one can introduce a  name  for
179       such type, and later just use that name:
180
181              typedef NAME = LENS;
182
183

RECURSIVE STRUCTURES

185       Ltrace allows you to express recursive structures.  Such structures are
186       expanded to the depth described by the  parameter  -A.   To  declare  a
187       recursive type, you first have to introduce the type to ltrace by using
188       forward declaration.  Then you can use the type in other  type  defini‐
189       tions in the usual way:
190
191              typedef NAME = struct;
192              typedef NAME = struct(NAME can be used here)
193
194       For  example, consider the following singy-linked structure and a func‐
195       tion that takes such list as an argument:
196
197              typedef int_list = struct;
198              typedef int_list = struct(int, int_list*);
199              void ll(int_list*);
200
201       Such declarations might lead to an output like the following:
202
203              ll({ 9, { 8, { 7, { 6, ... } } } }) = <void>
204
205       Ltrace detects recursion and will not  expand  already-expanded  struc‐
206       tures.  Thus a doubly-linked list would look like the following:
207
208              typedef int_list = struct;
209              typedef int_list = struct(int, int_list*, int_list*);
210
211       With output e.g. like:
212
213              ll({  9,  { 8, { 7, { 6, ..., ... }, recurse^ }, recurse^ }, nil
214              })
215
216       The "recurse^" tokens mean that given pointer  points  to  a  structure
217       that  was  expanded in the previous layer.  Simple "recurse" would mean
218       that it points back to this object.  E.g. "recurse^^^" means it  points
219       to a structure three layers up.  For doubly-linked list, the pointer to
220       the previous element is of course the one that has been  just  expanded
221       in  the  previous round, and therefore all of them are either recurse^,
222       or nil.  If the next and previous  pointers  are  swapped,  the  output
223       adjusts correspondingly:
224
225              ll({  9,  nil, { 8, recurse^, { 7, recurse^, { 6, ..., ... } } }
226              })
227
228
229

EXPRESSIONS

231       Ltrace has support for some elementary  expressions.   Each  expression
232       can be either of the following:
233
234
235       NUM    An integer number.
236
237
238       argNUM Value  of NUM-th argument.  The expression has the same value as
239              the corresponding argument.  arg1 refers to the first  argument,
240              arg0 to the return value of the given function.
241
242
243       retval Return value of function, same as arg0.
244
245
246       eltNUM Value of NUM-th element of the surrounding structure type.  E.g.
247              struct(ulong,array(int,elt1)) describes a structure whose  first
248              element is a length, and second element an array of ints of that
249              length.
250
251
252       zero
253       zero(EXPR)
254              Describes array which extends until  the  first  element,  whose
255              each  byte is 0.  If an expression is given, that is the maximum
256              length of the array.  If NUL terminator is  not  found  earlier,
257              that's where the array ends.
258
259

PARAMETER PACKS

261       Sometimes  the  actual  function prototype varies slightly depending on
262       the exact parameters given.  For  example,  the  number  and  types  of
263       printf parameters are not known in advance, but ltrace might be able to
264       determine them in runtime.  This feature has wider  applicability,  but
265       currently  the only parameter pack that ltrace supports is printf-style
266       format string itself:
267
268
269       format When format is seen in the parameter list, the underlying string
270              argument  is parsed, and GNU-style format specifiers are used to
271              determine what the following actual arguments are.  E.g. if  the
272              format  string  is "%s %d\n", it's as if the format was replaced
273              by string, string, int.
274
275

RETURN ARGUMENTS

277       C functions often use one or more arguments for returning  values  back
278       to  the  caller.   The  caller provides a pointer to storage, which the
279       called function initializes.  Ltrace has some support for this idiom.
280
281       When a traced binary hits a function call,  ltrace  first  fetches  all
282       arguments.   It  then displays left portion of the argument list.  Only
283       when the function returns does ltrace display right  portion  as  well.
284       Typically,  left  portion takes up all the arguments, and right portion
285       only contains return value.  But ltrace allows you to  configure  where
286       exactly  to  put  the  dividing line by means of a + operator placed in
287       front of an argument:
288
289              int asprintf(+string*, format);
290
291       Here, the first argument to asprintf is  denoted  as  return  argument,
292       which  means  that  displaying the whole argument list is delayed until
293       the function returns:
294
295              a.out->asprintf( <unfinished ...>
296              libc.so.6->malloc(100)                   = 0x245b010
297              [... more calls here ...]
298              <... asprintf resumed> "X=1", "X=%d", 1) = 5
299
300       It is currently not possible to have an "inout"  argument  that  passes
301       information in both directions.
302
303

EXAMPLES

305       In  the  following, the first is the C prototype, and following that is
306       ltrace configuration line.
307
308
309       void func_charp_string(char str[]);
310              void func_charp_string(string);
311
312
313       enum e_foo {RED, GREEN, BLUE};
314       void func_enum(enum e_foo bar);
315              void func_enum(enum(RED,GREEN,BLUE));
316                     - or -
317              typedef e_foo = enum(RED,GREEN,BLUE);
318              void func_enum(e_foo);
319
320
321       void func_arrayi(int arr[], int len);
322              void func_arrayi(array(int,arg2)*,int);
323
324
325       struct S1 {float f; char a; char b;};
326       struct S2 {char str[6]; float f;};
327       struct S1 func_struct(int a, struct S2, double d);
328              struct(float,char,char)                       func_struct_2(int,
329              struct(string(array(char, 6)),float), double);
330
331

AUTHOR

333       Petr Machata <pmachata@redhat.com>
334
335
336
337                                 October 2012                   ltrace.conf(5)
Impressum