public inbox for frysk-cvs@sourceware.org
help / color / mirror / Atom feed
From: pmachata@sourceware.org
To: frysk-cvs@sourceware.org
Subject: [SCM] master: Ftrace man page updates
Date: Fri, 30 Nov 2007 12:52:00 -0000 [thread overview]
Message-ID: <20071130125233.30747.qmail@sourceware.org> (raw)
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
reply other threads:[~2007-11-30 12:52 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20071130125233.30747.qmail@sourceware.org \
--to=pmachata@sourceware.org \
--cc=frysk-cvs@sourceware.org \
--cc=frysk@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).