summaryrefslogtreecommitdiff
path: root/ltrace.1
diff options
context:
space:
mode:
authorAnas Nashif <anas.nashif@intel.com>2013-01-15 08:32:18 -0800
committerAnas Nashif <anas.nashif@intel.com>2013-01-15 08:32:18 -0800
commit689b9dbb8d7f88ab91e7741932ed000b6e49be9a (patch)
tree463f5a1df8b2d35644c260e7bf6c8e0a26198af1 /ltrace.1
parent59749d048d9e452f049f9151735b5256756919c3 (diff)
downloadltrace-689b9dbb8d7f88ab91e7741932ed000b6e49be9a.tar.gz
ltrace-689b9dbb8d7f88ab91e7741932ed000b6e49be9a.tar.bz2
ltrace-689b9dbb8d7f88ab91e7741932ed000b6e49be9a.zip
Imported Upstream version 0.7.2upstream/0.7.2
Diffstat (limited to 'ltrace.1')
-rw-r--r--ltrace.1166
1 files changed, 118 insertions, 48 deletions
diff --git a/ltrace.1 b/ltrace.1
index 358d6aa..8b459ee 100644
--- a/ltrace.1
+++ b/ltrace.1
@@ -1,12 +1,29 @@
+.\" -*-nroff-*-
+.\" Copyright (c) 2012 Petr Machata, Red Hat Inc.
.\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
-.\" This file is covered by the GNU GPL
-.TH ltrace 1
+.\"
+.\" 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 "1" "October 2012" "" "User Commands"
.SH NAME
ltrace \- A library call tracer
.SH SYNOPSIS
.B ltrace
-.I "[-CfhiLrStttV] [-a column] [-A maxelts] [-D level] [-e expr] [-l filename] [-n nr] [-o filename] [-p pid] ... [-s strsize] [-u username] [-X extern] [-x extern] ... [--align=column] [--debug=level] [--demangle] [--help] [--indent=nr] [--library=filename] [--output=filename] [--version] [command [arg ...]]"
+.I "[-bCfghiLrStttV] [-a column] [-A maxelts] [-D level] [-e expr] [-l library_pattern] [-n nr] [-o filename] [-p pid] ... [-s strsize] [-u username] [-w count] [-x extern] ... [--align=column] [--debug=level] [--demangle] [--help] [--indent=nr] [--library=library_pattern] [--no-signals] [--output=filename] [--version] [--where=NR] [command [arg ...]]"
.SH DESCRIPTION
.B ltrace
@@ -23,10 +40,17 @@ Its use is very similar to
.SH OPTIONS
.TP
.I \-a, \-\-align column
-Align return values in a specific column (default column is 5/8 of screen width).
+Align return values in a specific
+.IR column
+(default column is 5/8 of screen width).
.TP
.I \-A maxelts
-Maximum number of array elements to print before suppressing the rest with an ellipsis ("...")
+Maximum number of array elements to print before suppressing the rest
+with an ellipsis ("..."). This also limits number of recursive
+structure expansions.
+.TP
+.I \-b, \-\-no-signals
+Disable printing of signals recieved by the traced process.
.TP
.I \-c
Count time and calls for each library call and report a summary on program exit.
@@ -59,22 +83,12 @@ carries upon a traced process
DEBUG_FUNCTION. Shows every entry to internal functions
.RE
.TP
-.I \-e expr
-A qualifying expression which modifies which events to trace.
-The format of the expression is:
-.br
-[!]value1[,value2]...
-.br
-where the values are the functions to trace. Using an exclamation
-mark negates the set of values. For example
-.I \-e printf
-means to trace only the printf library call. By contrast,
-.I \-e !printf
-means to trace every library call except printf.
-.IP
-Note that some shells use the exclamation point for history
-expansion; even inside quoted arguments. If so, you must escape
-the exclamation point with a backslash.
+.I \-e filter
+A qualifying expression which modifies which library calls to trace.
+The format of the filter expression is described in the section
+\fBFILTER EXPRESSIONS\fR. If more than one \-e option appears on the
+command line, the library calls that match any of them are traced. If
+no \-e is given, \fB@MAIN\fR is assumed as a default.
.TP
.I \-f
Trace child processes as they are created by
@@ -94,16 +108,22 @@ Show a summary of the options to ltrace and exit.
.I \-i
Print the instruction pointer at the time of the library call.
.TP
-.I \-l, \-\-library filename
-Display only the symbols included in the library
-.I filename.
-Up to 30 library names can be specified with several instances
-of this option.
+.I \-l, \-\-library library_pattern
+Display only calls to functions implemented by libraries that match
+.I library_pattern.
+Multiple library patters can be specified with several instances of
+this option. Syntax of library_pattern is described in section
+\fBFILTER EXPRESSIONS\fR.
+
+Note that while this option selects calls that might be directed to
+the selected libraries, there's no actual guarantee that the call
+won't be directed elsewhere due to e.g. LD_PRELOAD or simply
+dependency ordering. If you want to make sure that symbols in given
+library are actually called, use \fB-x @\fIlibrary_pattern\fR instead.
.TP
.I \-L
-DON'T display library calls (use it with the
-.I \-S
-option).
+When no -e option is given, don't assume the default action of
+\fB@MAIN\fR.
.TP
.I \-n, \-\-indent nr
Indent trace output by
@@ -153,35 +173,83 @@ Run command with the userid, groupid and supplementary groups of
This option is only useful when running as root and enables the
correct execution of setuid and/or setgid binaries.
.TP
-.I \-X extern
-Some architectures need to know where to set a breakpoint that will be hit
-after the dynamic linker has run. If this flag is used, then the breakpoint
-is set at
-.IR extern ,
-which must be an external function. By default, '_start' is used.
-NOTE: this flag is only available on the architectures that need it.
+.I \-w, --where NR
+Show backtrace of NR stack frames for each traced function. This option enabled
+only if libunwind support was enabled at compile time.
.TP
-.I \-x extern
-Trace the external function
-.IR extern .
-This option may be repeated.
+.I \-x filter
+A qualifying expression which modifies which symbol table entry points
+to trace. The format of the filter expression is described in the
+section \fBFILTER EXPRESSIONS\fR. If more than one \-x option appears
+on the command line, the symbols that match any of them are traced.
+No entry points are traced if no \-x is given.
.TP
.I \-V, \-\-version
Show the version number of ltrace and exit.
+.SH FILTER EXPRESSIONS
+
+Filter expression is a chain of glob- or regexp-based rules that are
+used to pick symbols for tracing from libraries that the process uses.
+Most of it is intuitive, so as an example, the following would trace
+calls to malloc and free, except those done by libc:
+
+-e malloc+free-@libc.so*
+
+This reads: trace malloc and free, but don't trace anything that comes
+from libc. Semi-formally, the syntax of the above example looks
+approximately like this:
+
+{[+-][\fIsymbol_pattern\fR][@\fIlibrary_pattern\fR]}
+
+\fISymbol_pattern\fR is used to match symbol names,
+\fIlibrary_pattern\fR to match library SONAMEs. Both are implicitly
+globs, but can be regular expressions as well (see below). The glob
+syntax supports meta-characters \fB*\fR and \fB?\fR and character
+classes, similarly to what basic bash globs support. \fB^\fR and
+\fB$\fR are recognized to mean, respectively, start and end of given
+name.
+
+Both \fIsymbol_pattern\fR and \fIlibrary_pattern\fR have to match the
+whole name. If you want to match only part of the name, surround it
+with one or two *'s as appropriate. The exception is if the pattern
+is not mentioned at all, in which case it's as if the corresponding
+pattern were \fB*\fR. (So \fBmalloc\fR is really \fBmalloc@*\fR and
+\fB@libc.*\fR is really \fB*@libc.*\fR.)
+
+In libraries that don't have an explicit SONAME, basename is taken for
+SONAME. That holds for main binary as well: \fB/bin/echo\fR has an
+implicit SONAME of \fBecho\fR. In addition to that, special library
+pattern \fBMAIN\fR always matches symbols in the main binary and never
+a library with actual SONAME \fBMAIN\fR (use e.g. \fB^MAIN\fR or
+\fB[M]AIN\fR for that).
+
+If the symbol or library pattern is surrounded in slashes (/like
+this/), then it is considered a regular expression instead. As a
+shorthand, instead of writing \fB/x/@/y/\fR, you can write
+\fB/x@y/\fR.
+
+If the library pattern starts with a slash, it is not a SONAME
+expression, but a path expression, and is matched against the library
+path name.
+
+The first rule may lack a sign, in which case \fB+\fR is assumed. If,
+on the other hand, the first rule has a \fB-\fR sign, it is as if
+there was another rule \fB@*\fR in front of it.
+
+The above rules are used to construct the set of traced symbols. Each
+candidate symbol is passed through the chain of above rules.
+Initially, the symbol is \fIunmarked\fR. If it matches a \fB+\fR
+rule, it becomes \fImarked\fR, if it matches a \fB-\fR rule, it
+becomes \fIunmarked\fR again. If, after applying all rules, the
+symbol is \fImarked\fR, it will be traced.
+
.SH BUGS
It has most of the bugs stated in
.BR strace(1) .
.LP
-Manual page and documentation are not very up-to-date.
-.LP
-Option -f sometimes fails to trace some children.
-.LP
It only works on Linux and in a small subset of architectures.
.LP
-Only ELF32 binaries are supported.
-.LP
-Calls to dlopen()ed libraries will not be traced.
.PP
If you would like to report a bug, send a message to the mailing list
(ltrace-devel@lists.alioth.debian.org), or use the
@@ -199,8 +267,10 @@ Personal config file, overrides
.SH AUTHOR
Juan Cespedes <cespedes@debian.org>
+.br
+Petr Machata <pmachata@redhat.com>
.SH "SEE ALSO"
+.BR ltrace.conf(5),
.BR strace(1) ,
.BR ptrace(2)
-