348 lines
11 KiB
HTML
348 lines
11 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of LTRACE</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>LTRACE</H1>
|
|
Section: User Commands (1)<BR>Updated: January 2013<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
ltrace - A library call tracer
|
|
<P>
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<B>ltrace</B>
|
|
|
|
|
|
|
|
|
|
[-e <I>filter</I>|-L] [-l|--library=<I>library_pattern</I>]
|
|
[-x <I>filter</I>] [-S] [-b|--no-signals]
|
|
|
|
|
|
|
|
[-i] [-w|--where=<I>nr</I>] [-r|-t|-tt|-ttt] [-T]
|
|
|
|
|
|
|
|
[-F <I>filename</I>]
|
|
[-A <I>maxelts</I>] [-s <I>strsize</I>] [-C|--demangle]
|
|
[-a|--align <I>column</I>] [-n|--indent <I>nr</I>]
|
|
[-o|--output <I>filename</I>]
|
|
|
|
|
|
|
|
[-D|--debug <I>mask</I>] [-u <I>username</I>]
|
|
|
|
|
|
|
|
[-f] [-p <I>pid</I>] [[--] <I>command [arg ...]</I>]
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<B>ltrace</B> -c
|
|
|
|
|
|
|
|
|
|
[-e <I>filter</I>|-L] [-l|--library=<I>library_pattern</I>]
|
|
[-x <I>filter</I>] [-S]
|
|
|
|
|
|
|
|
[-o|--output <I>filename</I>]
|
|
|
|
|
|
|
|
[-f] [-p <I>pid</I>] [[--] <I>command [arg ...]</I>]
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<B>ltrace</B> -V|--version
|
|
|
|
<P>
|
|
|
|
<B>ltrace</B> -h|--help
|
|
|
|
<P>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>ltrace</B>
|
|
|
|
is a program that simply runs the specified
|
|
<I>command</I>
|
|
|
|
until it exits. It intercepts and records the dynamic library calls
|
|
which are called by the executed process and the signals which are
|
|
received by that process.
|
|
It can also intercept and print the system calls executed by the program.
|
|
<P>
|
|
|
|
Its use is very similar to
|
|
<B><A HREF="/cgi-bin/man/man2html?1+strace">strace</A>(1)</B>.
|
|
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<P>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">-a, --align <I>column<DD>
|
|
Align return values in a specific
|
|
column</I>
|
|
|
|
(default column is 5/8 of screen width).
|
|
<DT id="2">-A <I>maxelts<DD>
|
|
Maximum number of array elements to print before suppressing the rest
|
|
with an ellipsis ("..."). This also limits number of recursive
|
|
structure expansions.
|
|
<DT id="3">-b, --no-signals<DD>
|
|
Disable printing of signals recieved by the traced process.
|
|
<DT id="4">-c<DD>
|
|
Count time and calls for each library call and report a summary on
|
|
program exit.
|
|
<DT id="5">-C, --demangle<DD>
|
|
Decode (demangle) low-level symbol names into user-level names.
|
|
Besides removing any initial underscore prefix used by the system,
|
|
this makes C++ function names readable.
|
|
<DT id="6">-D, --debug </I>mask<I><DD>
|
|
Show debugging output of </I><B>ltrace</B> itself. <I>mask</I> is a number
|
|
with internal meaning that's not really well defined at all.
|
|
<I>mask</I> of 77 shows all debug messages, which is what you usually
|
|
need.
|
|
<DT id="7">-e <I>filter<DD>
|
|
A qualifying expression which modifies which library calls to trace.
|
|
The format of the filter expression is described in the section
|
|
</I><B>FILTER EXPRESSIONS</B>. 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, <B>@MAIN</B> is assumed as a default.
|
|
<DT id="8">-f<DD>
|
|
Trace child processes as they are created by
|
|
currently traced processes as a result of the <A HREF="/cgi-bin/man/man2html?2+fork">fork</A>(2)
|
|
or <A HREF="/cgi-bin/man/man2html?2+clone">clone</A>(2) system calls.
|
|
The new process is attached immediately.
|
|
<DT id="9">-F <I>filename<DD>
|
|
Load an alternate config file. Normally, /etc/ltrace.conf and
|
|
~/.ltrace.conf will be read (the latter only if it exists). Use this
|
|
option to load the given file or files instead of those two default
|
|
files. See <A HREF="/cgi-bin/man/man2html?5+ltrace.conf">ltrace.conf</A>(5) for details on the syntax of ltrace
|
|
configuration files.
|
|
<DT id="10">-h, --help<DD>
|
|
Show a summary of the options to ltrace and exit.
|
|
<DT id="11">-i<DD>
|
|
Print the instruction pointer at the time of the library call.
|
|
<DT id="12">-l, --library library_pattern<DD>
|
|
Display only calls to functions implemented by libraries that match
|
|
library_pattern.</I>
|
|
|
|
Multiple library patters can be specified with several instances of
|
|
this option. Syntax of library_pattern is described in section
|
|
<B>FILTER EXPRESSIONS</B>.
|
|
<P>
|
|
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 <B>-x @</B><I>library_pattern</I> instead.
|
|
<DT id="13">-L<DD>
|
|
When no -e option is given, don't assume the default action of
|
|
<B>@MAIN</B>.
|
|
<DT id="14">-n, --indent <I>nr<DD>
|
|
Indent trace output by nr</I> spaces for each level of call
|
|
nesting. Using this option makes the program flow visualization easy
|
|
to follow. This indents uselessly also functions that never return,
|
|
such as service functions for throwing exceptions in the C++ runtime.
|
|
<DT id="15">-o, --output <I>filename<DD>
|
|
Write the trace output to the file filename</I> rather than to
|
|
stderr.
|
|
<DT id="16">-p <I>pid<DD>
|
|
Attach to the process with the process ID pid</I> and begin tracing.
|
|
This option can be used together with passing a command to execute.
|
|
It is possible to attach to several processes by passing more than one
|
|
option -p.
|
|
<DT id="17">-r<DD>
|
|
Print a relative timestamp with each line of the trace. This records
|
|
the time difference between the beginning of successive lines.
|
|
<DT id="18">-s <I>strsize<DD>
|
|
Specify the maximum string size to print (the default is 32).
|
|
<DT id="19">-S<DD>
|
|
Display system calls as well as library calls
|
|
<DT id="20">-t<DD>
|
|
Prefix each line of the trace with the time of day.
|
|
<DT id="21">-tt<DD>
|
|
If given twice, the time printed will include the microseconds.
|
|
<DT id="22">-ttt<DD>
|
|
If given thrice, the time printed will include the microseconds and
|
|
the leading portion will be printed as the number of seconds since the
|
|
epoch.
|
|
<DT id="23">-T<DD>
|
|
Show the time spent inside each call. This records the time difference
|
|
between the beginning and the end of each call.
|
|
<DT id="24">-u username<DD>
|
|
Run command with the userid, groupid and supplementary groups of
|
|
username</I>.
|
|
|
|
This option is only useful when running as root and enables the
|
|
correct execution of setuid and/or setgid binaries.
|
|
<DT id="25">-w, --where <I>nr<DD>
|
|
Show backtrace of nr</I> stack frames for each traced function. This
|
|
option enabled only if libunwind support was enabled at compile time.
|
|
<DT id="26">-x <I>filter<DD>
|
|
A qualifying expression which modifies which symbol table entry points
|
|
to trace. The format of the filter expression is described in the
|
|
section </I><B>FILTER EXPRESSIONS</B>. 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.
|
|
<DT id="27">-V, --version<DD>
|
|
Show the version number of ltrace and exit.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>FILTER EXPRESSIONS</H2>
|
|
|
|
<P>
|
|
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:
|
|
<P>
|
|
-e <A HREF="mailto:malloc+free-@libc.so">malloc+free-@libc.so</A>*
|
|
<P>
|
|
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:
|
|
<P>
|
|
{[+-][<I>symbol_pattern</I>][@<I>library_pattern</I>]}
|
|
<P>
|
|
<I>Symbol_pattern</I> is used to match symbol names,
|
|
<I>library_pattern</I> to match library SONAMEs. Both are implicitly
|
|
globs, but can be regular expressions as well (see below). The glob
|
|
syntax supports meta-characters <B>*</B> and <B>?</B> and character
|
|
classes, similarly to what basic bash globs support. <B>^</B> and
|
|
<B>$</B> are recognized to mean, respectively, start and end of given
|
|
name.
|
|
<P>
|
|
Both <I>symbol_pattern</I> and <I>library_pattern</I> 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 <B>*</B>. (So <B>malloc</B> is really <B>malloc@*</B> and
|
|
<B>@libc.*</B> is really <B>*@libc.*</B>.)
|
|
<P>
|
|
In libraries that don't have an explicit SONAME, basename is taken for
|
|
SONAME. That holds for main binary as well: <B>/bin/echo</B> has an
|
|
implicit SONAME of <B>echo</B>. In addition to that, special library
|
|
pattern <B>MAIN</B> always matches symbols in the main binary and never
|
|
a library with actual SONAME <B>MAIN</B> (use e.g. <B>^MAIN</B> or
|
|
<B>[M]AIN</B> for that).
|
|
<P>
|
|
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 <B>/x/@/y/</B>, you can write
|
|
<B>/x@y/</B>.
|
|
<P>
|
|
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.
|
|
<P>
|
|
The first rule may lack a sign, in which case <B>+</B> is assumed. If,
|
|
on the other hand, the first rule has a <B>-</B> sign, it is as if
|
|
there was another rule <B>@</B> in front of it, which has the effect of
|
|
tracing complement of given rule.
|
|
<P>
|
|
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 <I>unmarked</I>. If it matches a <B>+</B>
|
|
rule, it becomes <I>marked</I>, if it matches a <B>-</B> rule, it
|
|
becomes <I>unmarked</I> again. If, after applying all rules, the
|
|
symbol is <I>marked</I>, it will be traced.
|
|
<P>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
It has most of the bugs stated in
|
|
<B><A HREF="/cgi-bin/man/man2html?1+strace">strace</A>(1)</B>.
|
|
|
|
<P>
|
|
|
|
It only works on Linux and in a small subset of architectures.
|
|
<P>
|
|
|
|
<P>
|
|
|
|
If you would like to report a bug, send a message to the mailing list
|
|
(<A HREF="mailto:ltrace-devel@lists.alioth.debian.org">ltrace-devel@lists.alioth.debian.org</A>), or use the
|
|
<B><A HREF="/cgi-bin/man/man2html?1+reportbug">reportbug</A>(1)</B>
|
|
|
|
program if you are under the Debian GNU/Linux distribution.
|
|
<P>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="28"><I>/etc/ltrace.conf</I>
|
|
|
|
<DD>
|
|
System configuration file
|
|
<DT id="29"><I>~/.ltrace.conf</I>
|
|
|
|
<DD>
|
|
Personal config file, overrides
|
|
<I>/etc/ltrace.conf</I>
|
|
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
Juan Cespedes <<A HREF="mailto:cespedes@debian.org">cespedes@debian.org</A>>
|
|
<BR>
|
|
|
|
Petr Machata <<A HREF="mailto:pmachata@redhat.com">pmachata@redhat.com</A>>
|
|
<P>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?5+ltrace.conf">ltrace.conf</A>(5),</B>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+strace">strace</A>(1)</B>,
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ptrace">ptrace</A>(2)</B>
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="30"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="31"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="32"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="33"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="34"><A HREF="#lbAF">FILTER EXPRESSIONS</A><DD>
|
|
<DT id="35"><A HREF="#lbAG">BUGS</A><DD>
|
|
<DT id="36"><A HREF="#lbAH">FILES</A><DD>
|
|
<DT id="37"><A HREF="#lbAI">AUTHOR</A><DD>
|
|
<DT id="38"><A HREF="#lbAJ">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:18 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|