ltrace.conf.5

   1 .\" -*-nroff-*-
   2 .\" Copyright (c) 2012 Petr Machata, Red Hat Inc.
   3 .\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
   4 .\"
   5 .\" This program is free software; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of the
   8 .\" License, or (at your option) any later version.
   9 .\"
  10 .\" This program is distributed in the hope that it will be useful, but
  11 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 .\" General Public License for more details.
  14 .\"
  15 .\" You should have received a copy of the GNU General Public License
  16 .\" along with this program; if not, write to the Free Software
  17 .\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  18 .\" 02110-1301 USA
  19 .\"
  20 .TH ltrace.conf "5" "October 2012" "" "ltrace configuration file"
  21 .SH "NAME"
  22 .LP
  23 \fBltrace.conf\fR \- Configuration file for \fBltrace(1)\fR.
  24
  25 .SH DESCRIPTION
  26
  27 This manual page describes \fBltrace.conf\fR, a file that describes
  28 prototypes of functions in binaries for \fBltrace(1)\fR to use.
  29 Ltrace needs this information to display function call arguments.
  30
  31 Each line of a configuration file describes at most a single item.
  32 Lines composed entirely of white space are ignored, as are lines
  33 starting with semicolon character (comment lines).  Described items
  34 can be either function prototypes, or definitions of type aliases.
  35
  36 .SH PROTOTYPES
  37
  38 A prototype describes return type and parameter types of a single
  39 function.  The syntax is as follows:
  40
  41 .RS
  42 \fILENS\fR \fINAME\fR \fB(\fR[\fILENS\fR{,\fILENS\fR}]\fB);\fR
  43 .RE
  44
  45 \fINAME\fR is the (mangled) name of a symbol.  In the elementary case,
  46 \fILENS\fR is simply a type.  Both lenses and types are described
  47 below.  For example, a simple function prototype might look like this:
  48
  49 .RS
  50 .B int\fR kill\fB(int,int);
  51 .RE
  52
  53 Despite the apparent similarity with C, \fBltrace.conf\fR is really
  54 its own language that's only somewhat inspired by C.
  55
  56 .SH TYPES
  57
  58 Ltrace understands a range of primitive types.  Those are interpreted
  59 according to C convention native on a given architecture.
  60 E.g. \fBulong\fR is interpreted as 4-byte unsigned integer on 32-bit
  61 GNU/Linux machine, but 8-byte unsigned integer on 64-bit GNU/Linux
  62 machine.
  63
  64 .TP
  65 .B void
  66 Denotes that a function does not return anything.  Can be also used to
  67 construct a generic pointer, i.e. pointer-sized number formatted in
  68 hexadecimal format.
  69 .TP
  70 .B char
  71 8-bit quantity rendered as a character
  72 .TP
  73 .B ushort,short
  74 Denotes unsigned or signed short integer.
  75 .TP
  76 .B uint,int
  77 Denotes unsigned or signed integer.
  78 .TP
  79 .B ulong,long
  80 Denotes unsigned or signed long integer.
  81 .TP
  82 .B float
  83 Denotes floating point number with single precision.
  84 .TP
  85 .B double
  86 Denotes floating point number with double precision.
  87 .PP
  88
  89 Besides primitive types, the following composed types are possible:
  90
  91 .TP
  92 .B struct(\fR[\fILENS\fR{,\fILENS\fR}]\fB)\fR
  93 Describes a structure with given types as fields,
  94 e.g. \fBstruct(int,int,float)\fR.
  95
  96 Alignment is computed as customary on the architecture.  Custom
  97 alignment (e.g. packed structs) and bit-fields are not supported.
  98 It's also not possible to differentiate between structs and non-POD
  99 C++ classes, for arches where it makes a difference.
 100
 101 .TP
 102 .B array(\fR\fILENS\fR\fB,\fIEXPR\fR\fB)
 103 Describes array of length \fIEXPR\fR, which is composed of types
 104 described by \fILENS\fR, e.g. \fBarray(int, \fR6\fB)\fR.
 105
 106 Note that in C, arrays in role of function argument decay into
 107 pointers.  Ltrace currently handles this automatically, but for full
 108 formal correctness, any such arguments should be described as pointers
 109 to arrays.
 110
 111 .TP
 112 .I LENS\fR\fB*
 113 Describes a pointer to a given type, e.g. \fBchar*\fR or \fBint***\fR.
 114 Note that the former example actually describes a pointer to a
 115 character, not a string.  See below for \fBstring\fR lens, which is
 116 applicable to these cases.
 117
 118 .SH LENSES
 119
 120 Lenses change the way that types are described.  In the simplest case,
 121 a lens is directly a type.  Otherwise a type is decorated by the lens.
 122 Ltrace understands the following lenses:
 123
 124 .TP
 125 .B oct(\fITYPE\fB)
 126 The argument, which should be an integer type, is formatted in base-8.
 127
 128 .TP
 129 .B hex(\fITYPE\fB)
 130 The argument, which should be an integer or floating point type, is
 131 formatted in base-16.  Floating point arguments are converted to
 132 double and then displayed using the \fB%a\fR fprintf modifier.
 133
 134 .TP
 135 .B hide(\fITYPE\fB)
 136 The argument is not shown in argument list.
 137
 138 .TP
 139 .B bool(\fITYPE\fB)
 140 Arguments with zero value are shown as "false", others are shown as
 141 "true".
 142
 143 .TP
 144 .B bitvec(\fITYPE\fB)
 145 Underlying argument is interpreted as a bit vector and a summary of
 146 bits set in the vector is displayed.  For example if bits 3,4,5 and 7
 147 of the bit vector are set, ltrace shows <3-5,7>.  Empty bit vector is
 148 displayed as <>.  If there are more bits set than unset, inverse is
 149 shown instead: e.g. ~<0> when a number 0xfffffffe is displayed.  Full
 150 set is thus displayed ~<>.
 151
 152 If the underlying type is integral, then bits are shown in their
 153 natural big-endian order, with LSB being bit 0.
 154 E.g. \fBbitvec(ushort)\fR with value 0x0102 would be displayed as
 155 <1,8>, irrespective of underlying byte order.
 156
 157 For other data types (notably structures and arrays), the underlying
 158 data is interpreted byte after byte.  Bit 0 of first byte has number
 159 0, bit 0 of second byte number 8, and so on.  Thus
 160 \fBbitvec(struct(int))\fR is endian sensitive, and will show bytes
 161 comprising the integer in their memory order.  Pointers are first
 162 dereferenced, thus \fBbitvec(array(char, \fR32\fB)*)\fR is actually a
 163 pointer to 256-bit bit vector.
 164
 165 .PP
 166 .B string(\fITYPE\fB)
 167 .br
 168 .B string[\fIEXPR\fB]
 169 .br
 170 .B string
 171 .RS
 172 The first form of the argument is canonical, the latter two are
 173 syntactic sugar.  In the canonical form, the function argument is
 174 formatted as string.  The \fITYPE\fR shall be either a \fBchar*\fR, or
 175 \fBarray(char,\fIEXPR\fB)\fR, or \fBarray(char,\fIEXPR\fB)*\fR.  If an
 176 array is given, the length will typically be a \fBzero\fR expression
 177 (but doesn't have to be).  Using argument that is plain array
 178 (i.e. not a pointer to array) makes sense e.g. in C structs, in cases
 179 like \fBstruct(string(array(char, \fR6\fB)))\fR, which describes the C
 180 type \fBstruct {char \fRs\fB[\fR6\fB];}\fR.
 181
 182 Because simple C-like strings are pretty common, there are two
 183 shorthand forms.  The first shorthand form (with brackets) means the
 184 same as \fBstring(array(char, \fIEXPR\fB)*)\fR.  Plain \fBstring\fR
 185 without an argument is then taken to mean the same as
 186 \fBstring[zero]\fR.
 187
 188 Note that \fBchar*\fR by itself describes a pointer to a char.  Ltrace
 189 will dereference the pointer, and read and display the single
 190 character that it points to.
 191 .RE
 192
 193 .B enum(\fINAME\fR[\fB=\fIVALUE\fR]{,\fINAME\fR[\fB=\fIVALUE\fR]}\fB)
 194 .br
 195 .B enum[\fITYPE\fB]\fB(\fINAME\fR[\fB=\fIVALUE\fR]{,\fINAME\fR[\fB=\fIVALUE\fR]}\fB)
 196 .RS
 197 This describes an enumeration lens.  If an argument has any of the
 198 given values, it is instead shown as the corresponding \fINAME\fR.  If
 199 a \fIVALUE\fR is omitted, the next consecutive value following after
 200 the previous \fIVALUE\fR is taken instead.  If the first \fIVALUE\fR
 201 is omitted, it's \fB0\fR by default.
 202
 203 \fITYPE\fR, if given, is the underlying type.  It is thus possible to
 204 create enums over shorts or longs\(emarguments that are themselves
 205 plain, non-enum types in C, but whose values can be meaningfully
 206 described as enumerations.  If omitted, \fITYPE\fR is taken to be
 207 \fBint\fR.
 208 .RE
 209
 210 .SH TYPE ALIASES
 211
 212 A line in config file can, instead of describing a prototype, create a
 213 type alias.  Instead of writing the same enum or struct on many places
 214 (and possibly updating when it changes), one can introduce a name for
 215 such type, and later just use that name:
 216
 217 .RS
 218 \fBtypedef \fINAME\fB = \fILENS\fB;\fR
 219 .RE
 220
 221 .SH RECURSIVE STRUCTURES
 222
 223 Ltrace allows you to express recursive structures.  Such structures
 224 are expanded to the depth described by the parameter -A.  To declare a
 225 recursive type, you first have to introduce the type to ltrace by
 226 using forward declaration.  Then you can use the type in other type
 227 definitions in the usual way:
 228
 229 .RS
 230 .B typedef \fINAME\fB = struct;
 231 .br
 232 .B typedef \fINAME\fB = struct(\fINAME\fR can be used here\fB)
 233 .RE
 234
 235 For example, consider the following singy-linked structure and a
 236 function that takes such list as an argument:
 237
 238 .RS
 239 .B typedef\fR int_list \fB= struct;
 240 .br
 241 .B typedef\fR int_list \fB= struct(int,\fR int_list\fB*);
 242 .br
 243 .B void\fR ll\fB(\fRint_list\fB*);
 244 .RE
 245
 246 Such declarations might lead to an output like the following:
 247
 248 .RS
 249 ll({ 9, { 8, { 7, { 6, ... } } } }) = <void>
 250 .RE
 251
 252 Ltrace detects recursion and will not expand already-expanded
 253 structures.  Thus a doubly-linked list would look like the following:
 254
 255 .RS
 256 .B typedef\fR int_list \fB= struct;
 257 .br
 258 .B typedef\fR int_list \fB= struct(int,\fR int_list\fB*,\fR int_list\fB*);
 259 .RE
 260
 261 With output e.g. like:
 262
 263 .RS
 264 ll({ 9, { 8, { 7, { 6, ..., ... }, recurse^ }, recurse^ }, nil })
 265 .RE
 266
 267 The "recurse^" tokens mean that given pointer points to a structure
 268 that was expanded in the previous layer.  Simple "recurse" would mean
 269 that it points back to this object.  E.g. "recurse^^^" means it points
 270 to a structure three layers up.  For doubly-linked list, the pointer
 271 to the previous element is of course the one that has been just
 272 expanded in the previous round, and therefore all of them are either
 273 recurse^, or nil.  If the next and previous pointers are swapped, the
 274 output adjusts correspondingly:
 275
 276 .RS
 277 ll({ 9, nil, { 8, recurse^, { 7, recurse^, { 6, ..., ... } } } })
 278 .RE
 279
 280
 281 .SH EXPRESSIONS
 282
 283 Ltrace has support for some elementary expressions.  Each expression
 284 can be either of the following:
 285
 286 .TP
 287 .I NUM
 288 An integer number.
 289
 290 .TP
 291 .B arg\fINUM
 292 Value of \fINUM\fR-th argument.  The expression has the same value as
 293 the corresponding argument.  \fBarg1\fR refers to the first argument,
 294 \fBarg0\fR to the return value of the given function.
 295
 296 .TP
 297 .B retval
 298 Return value of function, same as \fBarg0\fR.
 299
 300 .TP
 301 .B elt\fINUM
 302 Value of \fINUM\fR-th element of the surrounding structure type.  E.g.
 303 \fBstruct(ulong,array(int,elt1))\fR describes a structure whose first
 304 element is a length, and second element an array of ints of that
 305 length.
 306
 307 .PP
 308 .B zero
 309 .br
 310 .B zero(\fIEXPR\fB)
 311 .RS
 312 Describes array which extends until the first element, whose each byte
 313 is 0.  If an expression is given, that is the maximum length of the
 314 array.  If NUL terminator is not found earlier, that's where the array
 315 ends.
 316 .RE
 317
 318 .SH PARAMETER PACKS
 319
 320 Sometimes the actual function prototype varies slightly depending on
 321 the exact parameters given.  For example, the number and types of
 322 printf parameters are not known in advance, but ltrace might be able
 323 to determine them in runtime.  This feature has wider applicability,
 324 but currently the only parameter pack that ltrace supports is
 325 printf-style format string itself:
 326
 327 .TP
 328 .B format
 329 When \fBformat\fR is seen in the parameter list, the underlying string
 330 argument is parsed, and GNU-style format specifiers are used to
 331 determine what the following actual arguments are.  E.g. if the format
 332 string is "%s %d\\n", it's as if the \fBformat\fR was replaced by
 333 \fBstring, string, int\fR.
 334
 335 .SH RETURN ARGUMENTS
 336
 337 C functions often use one or more arguments for returning values back
 338 to the caller.  The caller provides a pointer to storage, which the
 339 called function initializes.  Ltrace has some support for this idiom.
 340
 341 When a traced binary hits a function call, ltrace first fetches all
 342 arguments.  It then displays \fIleft\fR portion of the argument list.
 343 Only when the function returns does ltrace display \fIright\fR portion
 344 as well.  Typically, left portion takes up all the arguments, and
 345 right portion only contains return value.  But ltrace allows you to
 346 configure where exactly to put the dividing line by means of a \fB+\fR
 347 operator placed in front of an argument:
 348
 349 .RS
 350 .B int\fR asprintf\fB(+string*, format);
 351 .RE
 352
 353 Here, the first argument to asprintf is denoted as return argument,
 354 which means that displaying the whole argument list is delayed until
 355 the function returns:
 356
 357 .RS
 358 a.out->asprintf( <unfinished ...>
 359 .br
 360 libc.so.6->malloc(100)                   = 0x245b010
 361 .br
 362 [... more calls here ...]
 363 .br
 364 <... asprintf resumed> "X=1", "X=%d", 1) = 5
 365 .RE
 366
 367 It is currently not possible to have an "inout" argument that passes
 368 information in both directions.
 369
 370 .SH EXAMPLES
 371
 372 In the following, the first is the C prototype, and following that is
 373 ltrace configuration line.
 374
 375 .TP
 376 .B void\fR func_charp_string\fB(char\fR str\fB[]);
 377 .B void\fR func_charp_string\fB(string);
 378
 379 .PP
 380 .B enum\fR e_foo \fB{\fRRED\fB, \fRGREEN\fB, \fRBLUE\fB};
 381 .br
 382 .B void\fR func_enum\fB(enum\fR e_foo bar\fB);\fR
 383 .RS
 384 .B void\fR func_enum\fB(enum(\fRRED\fB,\fRGREEN\fB,\fRBLUE\fB));\fR
 385 .RS
 386 - or -
 387 .RE
 388 .B typedef\fR e_foo \fB= enum(\fRRED\fB,\fRGREEN\fB,\fRBLUE\fB);\fR
 389 .br
 390 .B void\fR func_enum\fB(\fRe_foo\fB);\fR
 391 .RE
 392
 393 .TP
 394 .B void\fR func_arrayi\fB(int\fR arr\fB[],\fR int len\fB);
 395 .B void\fR func_arrayi\fB(array(int,arg2)*,int);
 396
 397 .PP
 398 .B struct\fR S1 \fB{float\fR f\fB; char\fR a\fB; char \fRb\fB;};
 399 .br
 400 .B struct\fR S2 \fB{char\fR str\fB[\fR6\fB]; float\fR f\fB;};
 401 .br
 402 .B struct\fR S1 func_struct\fB(int \fRa\fB, struct \fRS2\fB, double \fRd\fB);
 403 .RS
 404 .B struct(float,char,char)\fR func_struct_2\fB(int, struct(string(array(char, \fR6\fB)),float), double);
 405 .RE
 406
 407 .SH AUTHOR
 408 Petr Machata <pmachata@redhat.com>