public inbox for frysk-cvs@sourceware.org
help / color / mirror / Atom feed
* [SCM] master: Ftrace man page updates
@ 2007-11-30 12:52 pmachata
0 siblings, 0 replies; only message in thread
From: pmachata @ 2007-11-30 12:52 UTC (permalink / raw)
To: frysk-cvs
The branch, master has been updated
via f35d16f56550ed70b845dd3c6c975b8f133361e5 (commit)
from 480e607f47241817fb2d52a7a52054475926056e (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email.
- Log -----------------------------------------------------------------
commit f35d16f56550ed70b845dd3c6c975b8f133361e5
Author: Petr Machata <pmachata@redhat.com>
Date: Fri Nov 30 13:52:17 2007 +0100
Ftrace man page updates
-----------------------------------------------------------------------
Summary of changes:
frysk-core/frysk/bindir/ChangeLog | 4 +
frysk-core/frysk/bindir/ftrace.xml | 218 ++++++++++++++++++++++++------------
2 files changed, 149 insertions(+), 73 deletions(-)
First 500 lines of diff:
diff --git a/frysk-core/frysk/bindir/ChangeLog b/frysk-core/frysk/bindir/ChangeLog
index 1a693b9..c9fcddd 100644
--- a/frysk-core/frysk/bindir/ChangeLog
+++ b/frysk-core/frysk/bindir/ChangeLog
@@ -1,3 +1,7 @@
+2007-11-30 Petr Machata <pmachata@redhat.com>
+
+ * ftrace.xml: Updated.
+
2007-11-28 Teresa Thomas <tthomas@redhat.com>
* fdebugrpm.sh: Enable all debuginfo repos.
diff --git a/frysk-core/frysk/bindir/ftrace.xml b/frysk-core/frysk/bindir/ftrace.xml
index 3da2fe6..71279d7 100644
--- a/frysk-core/frysk/bindir/ftrace.xml
+++ b/frysk-core/frysk/bindir/ftrace.xml
@@ -68,7 +68,13 @@
<refsynopsisdiv>
<cmdsynopsis>
<command>ftrace</command>
+ <arg choice="opt">-c</arg>
+ <arg choice="opt">-m</arg>
+ <arg choice="opt">-o=<replaceable>FILE</replaceable></arg>
+ <arg choice="opt" rep="repeat">-p=<replaceable>PID</replaceable></arg>
<arg choice="opt">-s=<replaceable>SYSCALL</replaceable>[,<replaceable>SYSCALL</replaceable>...]</arg>
+ <arg choice="opt">-S</arg>
+ <arg choice="opt">-t=<replaceable>SYSCALL</replaceable>[,<replaceable>SYSCALL</replaceable>...]</arg>
<arg choice="opt">-plt=<replaceable>RULE</replaceable>[,<replaceable>RULE</replaceable>...]</arg>
<arg choice="opt">-dyn=<replaceable>RULE</replaceable>[,<replaceable>RULE</replaceable>...]</arg>
<arg choice="opt">-sym=<replaceable>RULE</replaceable>[,<replaceable>RULE</replaceable>...]</arg>
@@ -82,69 +88,132 @@
<para><function>ftrace</function> starts given
<replaceable>command</replaceable> and according to tracing script
- given via command line argument, it traces its system calls,
- runtime library calls, and symbol entry points in general. It
- uses the Frysk framework to implement tracing.</para>
-
- <para>Which functions and/or syscalls <function>ftrace</function>
- traces, and whether it traces given group at all, is configurable
- through command-line options <option>-s</option>,
- <option>-plt</option>, <option>-dyn</option> and
- <option>-sym</option>. Neither option is turned on by
- default.</para>
-
- <variablelist>
- <varlistentry>
- <term>-s=<replaceable>SYSCALL</replaceable>[,<replaceable>SYSCALL</replaceable>...]</term>
- <listitem>
- <para>Stack trace on this set of system calls. Each
- <replaceable>SYSCALL</replaceable> entry is name of one
- system call.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-plt=<replaceable>RULE</replaceable>[,<replaceable>RULE</replaceable>...]</term>
- <listitem>
- <para>Trace library calls done via PLT entries matching each
- given <replaceable>RULE</replaceable>. By tracing PLT
- entry, you effectively trace calls done FROM given library
- or executable, and generally can't say which library the
- call leads TO. (At least for now. Ftrace may grow brains
- for this in future.) See below for description of
- <replaceable>RULE</replaceable> syntax.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-dyn=<replaceable>RULE</replaceable>[,<replaceable>RULE</replaceable>...]</term>
- <listitem>
- <para>Trace calls through the symbol entry points. By
- tracing entry points, you catch all calls that end up at
- this symbol, including the calls that don't go through PLT
- and as such are not intended as inter-library calls, but
- rather intra-library calls. This is probably not what you
- usually want, because you get lots of output when various
- functions call each other in the library internals. On the
- other hand, it may be useful to cherry pick few entry points
- to see when or if they are called, and with which arguments.
- See below for description of <replaceable>RULE</replaceable>
- syntax.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-sym=<replaceable>RULE</replaceable>[,<replaceable>RULE</replaceable>...]</term>
- <listitem>
- <para>Just like <option>-dyn</option>, but doesn't look for
- symbols in dynamic symbol table, but normal symbol table.
- (Which doesn't have to be present, e.g. when a binary is
- stripped.) See below for description of
- <replaceable>RULE</replaceable> syntax.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
+ given via command-line arguments, it traces its system calls,
+ symbol entry points in general, and possibly other events as well.
+ It uses the Frysk framework to implement tracing.</para>
+
+ <para>The working set of events <function>ftrace</function> should
+ trace is defined by the following arguments.</para>
+
+ <refsect2>
+ <title>Process Selection Options</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>-p=<replaceable>PID</replaceable></term>
+ <listitem>
+ <para>Attach to a process with given
+ <replaceable>PID</replaceable>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-c</term>
+ <listitem>
+ <para>Trace children: automatically attach to forks of
+ traced process.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>System Call Tracing</title>
+
+ <para>System calls are traced by default.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>-S</term>
+ <listitem>
+ <para>Suppress system call tracing.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-s=<replaceable>SYSCALL</replaceable>[,<replaceable>SYSCALL</replaceable>...]</term>
+ <listitem>
+ <para>Stack trace on this set of system calls.
+ When stack-traced syscall is encountered, a stack
+ trace of the calling task is printed out. Each
+ <replaceable>SYSCALL</replaceable> entry is name
+ of one system call.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-t=<replaceable>SYSCALL</replaceable>[,<replaceable>SYSCALL</replaceable>...]</term>
+ <listitem>
+ <para>Explicitly define syscalls that should be
+ traced. Each <replaceable>SYSCALL</replaceable>
+ entry is name of one system call.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+
+ <refsect2>
+ <title>Entry Point Tracing</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>-plt=<replaceable>RULE</replaceable>[,<replaceable>RULE</replaceable>...]</term>
+ <listitem>
+ <para>Trace library calls done via PLT entries matching each
+ given <replaceable>RULE</replaceable>. By tracing PLT
+ entry, you effectively trace calls done FROM given library
+ or executable, and generally can't say which library the
+ call leads TO. (At least for now. Ftrace may grow brains
+ for this in future.) See below for description of
+ <replaceable>RULE</replaceable> syntax.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-dyn=<replaceable>RULE</replaceable>[,<replaceable>RULE</replaceable>...]</term>
+ <listitem>
+ <para>Trace calls through the symbol entry points. By
+ tracing entry points, you catch all calls that end up at
+ this symbol, including the calls that don't go through PLT
+ and as such are not intended as inter-library calls, but
+ rather intra-library calls. This is probably not what you
+ usually want, because you get lots of output when various
+ functions call each other in the library internals. On the
+ other hand, it may be useful to cherry pick few entry points
+ to see when or if they are called, and with which arguments.
+ See below for description of <replaceable>RULE</replaceable>
+ syntax.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-sym=<replaceable>RULE</replaceable>[,<replaceable>RULE</replaceable>...]</term>
+ <listitem>
+ <para>Just like <option>-dyn</option>, but doesn't look for
+ symbols in dynamic symbol table, but normal symbol table.
+ (Which doesn't have to be present, e.g. when a binary is
+ stripped.) See below for description of
+ <replaceable>RULE</replaceable> syntax.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Other Traceable Events</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>-m</term>
+ <listitem>
+ <para>Print each file mapped to or unmapped from address
+ space of the traced process.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
</refsect1>
<refsect1>
@@ -161,7 +230,7 @@
<para>Optional "-" at the beginning of the rule means
removal from the working set. When the sign is omitted, the
default action is to add to the working set. Optional
- "#" means that fltrace should print out stack trace when
+ "#" means that ftrace should print out stack trace when
it hits the call. The combination of "-#" then means
that the call should still be traced, but stack trace shouldn't be
generated. <replaceable>pattern</replaceable> defines which PLT
@@ -196,23 +265,26 @@
is possible to request symbol without a version with the pattern
"foo@@".)</para>
- <para>Empty rule is considered to miss all components, not contain
- symbol component with empty contents, which makes little sense.
- If you need to match empty symbol, use regular expression
- "^$".</para>
+ <para>Empty rule is considered to miss all components. If you
+ need to match empty symbol, use regular expression "^$".</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>EXAMPLES</title>
<informalexample>
<para>Trace all plt library calls:</para>
- <cmdsynopsis><command>fltrace -plt= ls</command></cmdsynopsis>
+ <cmdsynopsis><command>ftrace -plt= ls</command></cmdsynopsis>
<para>Trace all library calls to functions that contain
substring "write" in their names:</para>
- <cmdsynopsis><command>fltrace -plt=".*write.*" ls</command></cmdsynopsis>
+ <cmdsynopsis><command>ftrace -plt=".*write.*" ls</command></cmdsynopsis>
<para>Trace memory functions done from libraries, i.e. not from
main executable:</para>
- <cmdsynopsis><command>fltrace -plt="[cm]alloc|free,-@MAIN" ls</command></cmdsynopsis>
+ <cmdsynopsis><command>ftrace -plt="[cm]alloc|free,-@MAIN" ls</command></cmdsynopsis>
<para>Stack trace on everything, except for memory allocation
functions (which should still be traced):</para>
- <cmdsynopsis><command>fltrace -plt="#,-#[cm]alloc|free" ls</command></cmdsynopsis>
+ <cmdsynopsis><command>ftrace -plt="#,-#[cm]alloc|free" ls</command></cmdsynopsis>
</informalexample>
</refsect1>
@@ -283,7 +355,7 @@
<refsect1>
<title>BUGS</title>
- <para>I think ltrace wouldn't handle tracing one function both through entry point and plt.</para>
+ <para>I think ftrace doesn't handle tracing one function through both entry point and plt.</para>
<para>Report bugs to <ulink url="http:/sources.redhat.com/frysk">http://sources.redhat.com/frysk</ulink>.</para>
</refsect1>
hooks/post-receive
--
frysk system monitor/debugger
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2007-11-30 12:52 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2007-11-30 12:52 [SCM] master: Ftrace man page updates pmachata
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).