-*-nroff-*-
Copyright (c) 2012 Petr Machata, Red Hat Inc.
Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
02110-1301 USA

ltrace.conf - Configuration file for ltrace(1).

This manual page describes ltrace.conf, a file that describes prototypes of functions in binaries for ltrace(1) to use. Ltrace needs this information to display function call arguments. Each line of a configuration file describes at most a single item. Lines composed entirely of white space are ignored, as are lines starting with semicolon character (comment lines). Described items can be either function prototypes, or definitions of type aliases. A prototype describes return type and parameter types of a single function. The syntax is as follows: NAME is the (mangled) name of a symbol. In the elementary case, LENS is simply a type. For description of both lenses and types, see below. Ltrace understands a range of primitive types. Those are interpreted according to C convention native on a given architecture. E.g. ulong is interpreted as 4-byte unsigned integer on 32-bit GNU/Linux machine, but 8-byte unsigned integer on 64-bit GNU/Linux machine.

void Denotes that a function does not return anything. Can be also used to construct a generic pointer, i.e. pointer-sized number formatted in hexadecimal format.

char 8-bit quantity rendered as a character

ushort,short unsigned or signed short integer

uint,int unsigned or signed integer

ulong,long unsigned or signed long integer

float floating point number with single precision

double floating point number with double precision

Besides primitive types, the following composed types are possible:

struct([LENS{,LENS}]) Describes a structure with given types as fields. Alignment is computed as customary on the architecture. Custom alignment (e.g. packed structs) and bit-fields are not supported. It's also not possible to differentiate between structs and non-POD C++ classes, for arches where it makes a difference.

array(LENS,EXPR) Describes array of length EXPR, which is composed of types described by LENS. Note that in C, arrays in role of function argument decay into pointers. Ltrace currently handles this automatically, but for full formal correctness, any such arguments should be described as pointers to arrays.

LENS* Describes a pointer to a given type.

Lenses change the way that types are described. In the simplest case, a lens is directly a type. Otherwise a type is decorated by the lens. Ltrace understands the following lenses:

oct(TYPE) The argument, which should be an integer type, is formatted in base-8.

hex(TYPE) The argument, which should be an integer type, is formatted in base-16.

hide(TYPE) The argument is not shown in argument list.

bool(TYPE) Arguments with zero value are shown as "false", other are shown as "true".

string[(TYPE)] The argument, which should be either a char*, or array(char,EXPR), or array(char,EXPR)*, is formatted as a string. If an array is given, the length will typically be a zero expression (but doesn't have to be). Using argument that is plain array (i.e. not a pointer to array) makes sense e.g. in C structs, in cases like struct(string(array(char, 6))), which describes the C type struct {char s[6];}. Because simple C-like strings are pretty common, plain string (without an argument) is taken to mean the same as string(char*) (which is itself taken to mean the same as string(array(char,zero))). Note that char* describes a pointer to a char. Ltrace will dereference the pointer, and read and display the single character that it points to.

enum(NAME[=VALUE]{,NAME[=VALUE]})

enum[TYPE](NAME[=VALUE]{,NAME[=VALUE]})

A line in config file can, instead of describing a prototype, create a type alias. Instead of writing the same enum or struct on many places (and possibly updating when it changes), one can introduce a name for such type, and later just use that name: Note that TYPE currently cannot be a lens, but must really be a type. Ltrace has support for some elementary expressions. Each expression can be either of the following:

NUM An integer number.

argNUM Value of NUM-th argument. The expression has the same value as the corresponding argument. arg1 refers to the first argument, arg0 to the return value of the given function.

emtNUM Value of NUM-th element of the surrounding structure type. E.g. struct(ulong,array(int,elt1)) describes a structure whose first element is a length, and second element an array of ints of that length.

zero

zero(EXPR)

Sometimes the actual function prototype varies slightly depending on the exact parameters given. For example, the number and types of printf parameters are not known in advance, but ltrace might be able to determine them in runtime. This feature has wider applicability, but currently the only parameter pack that ltrace supports is printf-style format string itself:

format When format is seen in the parameter list, the underlying string argument is parsed, and GNU-style format specifiers are used to determine what the following actual arguments are. E.g. if the format string is "%s %d\\n", it's as if the format was replaced by string, string, int.

In the following, the first is the C prototype, and following that is ltrace configuration line.

void func_charp_string(char str[]); void func_charp_string(string);

enum e_foo {RED, GREEN, BLUE};

void func_enum(enum e_foo bar);

void func_arrayi(int arr[], int len); void func_arrayi(array(int,arg2)*,int);

struct S1 {float f; char a; char b;};

struct S2 {char str[6]; float f;};

struct S1 func_struct(int a, struct S2, double d);

Petr Machata <pmachata@redhat.com>