Update ltrace.1, add ltrace.conf.5

1 files changed, 237 insertions, 0 deletions

diff --git a/ltrace.conf.5 b/ltrace.conf.5
new file mode 100644
index 0000000..ab7d195
--- /dev/null
+++ b/ltrace.conf.5
@@ -0,0 +1,237 @@
+.\" -*-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
+.\"
+.TH ltrace.conf "1" "October 2012" "" "ltrace configuration file"
+.SH "NAME"
+.LP
+\fBltrace.conf\fR \- Configuration file for \fBltrace(1)\fR.
+
+.SH DESCRIPTION
+
+This manual page describes \fBltrace.conf\fR, a file that describes
+prototypes of functions in binaries for \fBltrace(1)\fR 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.
+
+.SH PROTOTYPES
+
+A prototype describes return type and parameter types of a single
+function.  The syntax is as follows:
+
+.RS
+\fILENS\fR \fINAME\fR \fB(\fR[\fILENS\fR{,\fILENS\fR}]\fB);\fR
+.RE
+
+\fINAME\fR is the (mangled) name of a symbol.  In the elementary case,
+\fILENS\fR is simply a type.  For description of both lenses and
+types, see below.
+
+.SH TYPES
+
+Ltrace understands a range of primitive types.  Those are interpreted
+according to C convention native on a given architecture.
+E.g. \fBulong\fR is interpreted as 4-byte unsigned integer on 32-bit
+GNU/Linux machine, but 8-byte unsigned integer on 64-bit GNU/Linux
+machine.
+
+.TP
+.B 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.
+.TP
+.B char
+8-bit quantity rendered as a character
+.TP
+.B ushort,short
+unsigned or signed short integer
+.TP
+.B uint,int
+unsigned or signed integer
+.TP
+.B ulong,long
+unsigned or signed long integer
+.TP
+.B float
+floating point number with single precision
+.TP
+.B double
+floating point number with double precision
+.PP
+Besides primitive types, the following composed types are possible:
+
+.TP
+\fBstruct(\fR[\fILENS\fR{,\fILENS\fR}]\fB)\fR
+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.
+
+.TP
+\fBarray(\fR\fILENS\fR\fB,\fIEXPR\fR\fB)\fR
+Describes array of length \fIEXPR\fR, which is composed of types
+described by \fILENS\fR.  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.
+
+.TP
+\fILENS\fR\fB*\fR
+Describes a pointer to a given type.
+
+.SH LENSES
+
+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:
+
+.TP
+.B oct(\fITYPE\fB)
+The argument, which should be an integer type, is formatted in base-8.
+
+.TP
+.B hex(\fITYPE\fB)
+The argument, which should be an integer type, is formatted in
+base-16.
+
+.TP
+.B hide(\fITYPE\fB)
+The argument is not shown in argument list.
+
+.TP
+.B bool(\fITYPE\fB)
+Arguments with zero value are shown as "false", other are shown as
+"true".
+
+.TP
+.B string\fR[(\fITYPE\fB)\fR]
+The argument, which should be either a \fBchar*\fR, or
+\fBarray(char,\fIEXPR\fB)\fR, or \fBarray(char,\fIEXPR\fB)*\fR, is
+formatted as a string.  If an array is given, the length will
+typically be a \fBzero\fR 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 \fBstruct(string(array(char,
+\fR6\fB)))\fR, which describes the C type \fBstruct {char
+\fRs\fB[\fR6\fB];}\fR.
+
+Because simple C-like strings are pretty common, plain \fBstring\fR
+(without an argument) is taken to mean the same as \fBstring(char*)\fR
+(which is itself taken to mean the same as
+\fBstring(array(char,zero))\fR).  Note that \fBchar*\fR describes a
+pointer to a char.  Ltrace will dereference the pointer, and read and
+display the single character that it points to.
+
+.PP
+.B enum(\fINAME\fR[\fB=\fIVALUE\fR]{,\fINAME\fR[\fB=\fIVALUE\fR]}\fB)
+.br
+.B enum[\fITYPE\fB]\fB(\fINAME\fR[\fB=\fIVALUE\fR]{,\fINAME\fR[\fB=\fIVALUE\fR]}\fB)
+.RS
+This describes an enumeration type--which is itself just a
+sophisticated lens.  If an argument has any of the given values, it is
+instead shown as the corresponding \fINAME\fR.  If a \fIVALUE\fR is
+omitted, the next consecutive value following after the previous
+\fIVALUE\fR is taken instead.  If the first \fIVALUE\fR is omitted,
+it's \fB0\fR by default.
+
+\fITYPE\fR, if given, is the underlying type.  It is thus possible to
+create enums over shorts or longs--arguments that are themselves
+plain, non-enum types in C, but whose value can be meaningfully
+described as enumerations.  If omitted, \fITYPE\fR is taken to be
+\fBint\fR.
+.RE
+
+.SH TYPE ALIASES
+
+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:
+
+.RS
+\fBtypedef \fINAME\fB = \fITYPE\fB;\fR
+.RE
+
+Note that \fITYPE\fR currently cannot be a lens, but must really be a
+type.
+
+.SH EXPRESSIONS
+
+XXX TODO
+
+.SH PARAMETER PACKS
+
+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:
+
+.TP
+.B format
+When \fBformat\fR 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 \fBformat\fR was replaced by
+\fBstring, string, int\fR.
+
+.SH EXAMPLES
+
+In the following, the first is the C prototype, and following that is
+ltrace configuration line.
+
+.TP
+.B void\fR func_charp_string\fB(char\fR str\fB[]);
+.B void\fR func_charp_string\fB(string);
+
+.PP
+.B enum\fR e_foo \fB{\fRRED\fB, \fRGREEN\fB, \fRBLUE\fB};
+.br
+.B void\fR func_enum\fB(enum\fR e_foo bar\fB);\fR
+.RS
+.B void\fR func_enum\fB(enum(\fRRED\fB,\fRGREEN\fB,\fRBLUE\fB));\fR
+.RS
+- or -
+.RE
+.B typedef\fR e_foo \fB= enum(\fRRED\fB,\fRGREEN\fB,\fRBLUE\fB);\fR
+.br
+.B void\fR func_enum\fB(\fRe_foo\fB);\fR
+.RE
+
+.TP
+.B void\fR func_arrayi\fB(int\fR arr\fB[],\fR int len\fB);
+.B void\fR func_arrayi\fB(array(int,arg2)*,int);
+
+.PP
+.B struct\fR S1 \fB{float\fR f\fB; char\fR a\fB; char \fRb\fB;};
+.br
+.B struct\fR S2 \fB{char\fR str\fB[\fR6\fB]; float\fR f\fB;};
+.br
+.B struct\fR S1 func_struct\fB(int \fRa\fB, struct \fRS2\fB, double \fRd\fB);
+.RS
+.B struct(float,char,char)\fR func_struct_2\fB(int, struct(string(array(char, \fR6\fB)),float), double);
+.RE
+
+.SH AUTHOR
+Petr Machata <pmachata@redhat.com>