diff options
author | Anas Nashif <anas.nashif@intel.com> | 2013-01-15 08:32:18 -0800 |
---|---|---|
committer | Anas Nashif <anas.nashif@intel.com> | 2013-01-15 08:32:18 -0800 |
commit | 689b9dbb8d7f88ab91e7741932ed000b6e49be9a (patch) | |
tree | 463f5a1df8b2d35644c260e7bf6c8e0a26198af1 /ltrace.1 | |
parent | 59749d048d9e452f049f9151735b5256756919c3 (diff) | |
download | ltrace-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.1 | 166 |
1 files changed, 118 insertions, 48 deletions
@@ -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) - |