summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMark Wielaard <mjw@redhat.com>2009-02-20 14:56:38 +0100
committerMark Wielaard <mjw@redhat.com>2009-02-20 14:56:38 +0100
commit02615365a92ca2570c1f96abc8a97674aa2ccae1 (patch)
treeebedfd91a0f6d299b39e84295e091e12c0767dc8 /doc
parentc3bad3042df505a3470f1e20b09822a9df1d4761 (diff)
parentadc67597f327cd43d58b1d0cb740dab14a75a058 (diff)
downloadsystemtap-steved-02615365a92ca2570c1f96abc8a97674aa2ccae1.tar.gz
systemtap-steved-02615365a92ca2570c1f96abc8a97674aa2ccae1.tar.xz
systemtap-steved-02615365a92ca2570c1f96abc8a97674aa2ccae1.zip
Merge branch 'master' into pr6866
Conflicts: ChangeLog: Removed runtime/ChangeLog: Removed runtime/sym.c: Merged runtime/task_finder.c: Merged tapset/ChangeLog: Removed testsuite/ChangeLog: Removed
Diffstat (limited to 'doc')
-rw-r--r--doc/ChangeLog127
-rw-r--r--doc/Makefile.in25
-rw-r--r--doc/SystemTap_Beginners_Guide/Makefile10
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml12
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml8
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Installation.xml131
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Introduction.xml4
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Legal_Notice.xml30
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-syscallsbyprocpid.xml132
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml136
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml131
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml3
-rwxr-xr-xdoc/SystemTap_Beginners_Guide/syncandbuild.sh23
-rw-r--r--doc/SystemTap_Tapset_Reference/.gitignore1
-rw-r--r--doc/SystemTap_Tapset_Reference/Makefile.in24
-rw-r--r--doc/SystemTap_Tapset_Reference/tapsets.tmpl9
-rw-r--r--doc/Tapset_Reference_Guide/en-US/Author_Group.xml25
-rwxr-xr-xdoc/Tapset_Reference_Guide/publicanize.sh48
-rw-r--r--doc/langref.tex8
19 files changed, 657 insertions, 230 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog
deleted file mode 100644
index b3fd1d78..00000000
--- a/doc/ChangeLog
+++ /dev/null
@@ -1,127 +0,0 @@
-2009-01-21 William Cohen <wcohen@redhat.com>
-
- * S_T_R/tapsets.tmpl: Use context-symbols.stp and context-unwind.stp.
-
-2009-01-21 William Cohen <wcohen@redhat.com>
-
- * S_T_R/tapsets.tmpl: Update copyright date and correct paragraph.
-
-2009-01-12 William Cohen <wcohen@redhat.com>
-
- * S_T_R/tapsets.tmpl: Correct author's name.
-
-2009-01-07 William Cohen <wcohen@redhat.com>
-
- * S_T_R/Makefile.am: Use BUILD_REFDOCS.
- * S_T_R/Makefile.in: Regenerated.
-
-2009-01-06 Frank Ch. Eigler <fche@elastic.org>
-
- * S_T_R/Makefile.am: Regenerate docs only as necessary, via
- stamp-* files for html/man, and cmp for tapsets.xml.
- * S_T_R/Makefile.in: Regenerated.
-
-2008-12-30 Dave Brolley <brolley@redhat.com>
-
- PR9692
- * Makefile.in: Regenerated.
- * SystemTap_Tapset_Reference/Makefile.in: Regenerated.
-
-2008-12-24 Dave Brolley <brolley@redhat.com>
-
- * Makefile.in: Regenerated.
- * SystemTap_Tapset_Reference/Makefile.in: Regenerated.
-
-2008-12-21 Will Cohen <wcohen@redhat.com>
-
- * Makefile.am: Add generations of tapset reference manual material.
- * SystemTap_Tapset_Reference/Makefile.am: Install tapset reference man.
- * Makfile.am, SystemTap_Tapset_Reference/Makefile.in: Regenerated.
-
-2008-11-26 Will Cohen <wcohen@redhat.com>
-
- * SystemTap_Tapset_Reference/tapsets.tmpl: Add scsi.
-
-2008-11-26 Will Cohen <wcohen@redhat.com>
-
- * SystemTap_Tapset_Reference/tapsets.am: Correct location for html/man.
- * SystemTap_Tapset_Reference/tapsets.in: Regenerate.
-
-2008-11-26 Will Cohen <wcohen@redhat.com>
-
- * SystemTap_Tapset_Reference/tapsets.tmpl: Add process.
-
-2008-11-25 Will Cohen <wcohen@redhat.com>
-
- * SystemTap_Tapset_Reference/tapsets.tmpl: Add ioscheduler, socket, tcp,
- and upd.
-
-2008-11-24 Will Cohen <wcohen@redhat.com>
-
- * SystemTap_Tapset_Reference/tapsets.tmpl: Add context, timestamp,
- memory, and networking tapsets.
-
-2008-11-24 Will Cohen <wcohen@redhat.com>
-
- * SystemTap_Tapset_Reference: Add kernel-doc based version.
-
-2008-11-24 Will Cohen <wcohen@redhat.com>
-
- * SystemTap_Tapset_Reference: Remove.
-
-2008-10-23 Will Cohen <wcohen@redhat.com>
-
- * SystemTap_Tapset_Reference: New.
-
-2008-08-28 Stan Cox <scox@redhat.com>
-
- * langref.tex: Document written but unread global variable display.
-
-2008-08-25 Frank Ch. Eigler <fche@elastic.org>
-
- * Makefile.am: Removed dist-related targets and macros.
- * Makefile.in: Regenerated.
-
-2008-07-14 Dave Brolley <brolley@redhat.com>
-
- * Makefile.in: Regenerated.
-
-2008-07-07 Mark Wielaard <mwielaard@redhat.com>
-
- * Makefile.am (install-data-hook): New, install pdf files.
- (uninstall-local): New, uninstall them again.
- * Makefile.in: Regenerated.
-
-2008-04-24 Will Cohen <wcohen@redhat.com>
-
- * Makefile.in: Regenerated.
-
-2008-04-09 David Smith <dsmith@redhat.com>
-
- * .gitignore: New file.
-
-2008-03-25 Frank Ch. Eigler <fche@elastic.org>
-
- * langref.tex: Clarify utility of epilogue-type probe aliases.
-
-2008-03-04 David Smith <dsmith@redhat.com>
-
- * tutorial.tex: Made minor changes to remove warnings.
-
-2008-03-03 Frank Ch. Eigler <fche@elastic.org>
-
- From Masami Hiramatsu <mhiramat@redhat.com>
- * Makefile.am (EXTRA_DIST): Add nomencl.sty.
- * Makefile.in: Hand-regenerated.
-
-2008-02-27 Frank Ch. Eigler <fche@elastic.org>
-
- * nomencl.sty: Bundle F8 version of package, for use on older distros.
-
-2008-02-27 Frank Ch. Eigler <fche@redhat.com>
-
- * langref.tex, tutorial.tex: Copied over & aggregated
- from former comfy digs under /cvs/doc.
- * tutorial/*: Samples scripts from tutorial.
- * Makefile.am: New build instructions.
- * Makefile.in: New generated file.
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 776381d8..e23a6699 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -1,8 +1,8 @@
-# Makefile.in generated by automake 1.10 from Makefile.am.
+# Makefile.in generated by automake 1.10.1 from Makefile.am.
# @configure_input@
# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-# 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
@@ -32,7 +32,7 @@ NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
subdir = doc
-DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in ChangeLog
+DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/configure.ac
am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
@@ -101,8 +101,9 @@ PACKAGE_STRING = @PACKAGE_STRING@
PACKAGE_TARNAME = @PACKAGE_TARNAME@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
+PIECFLAGS = @PIECFLAGS@
+PIECXXFLAGS = @PIECXXFLAGS@
PIELDFLAGS = @PIELDFLAGS@
-PKG_CONFIG = @PKG_CONFIG@
PROCFLAGS = @PROCFLAGS@
RANLIB = @RANLIB@
SET_MAKE = @SET_MAKE@
@@ -147,9 +148,7 @@ localstatedir = @localstatedir@
mandir = @mandir@
mkdir_p = @mkdir_p@
nspr_CFLAGS = @nspr_CFLAGS@
-nspr_LIBS = @nspr_LIBS@
nss_CFLAGS = @nss_CFLAGS@
-nss_LIBS = @nss_LIBS@
oldincludedir = @oldincludedir@
pdfdir = @pdfdir@
prefix = @prefix@
@@ -164,6 +163,7 @@ staplog_CPPFLAGS = @staplog_CPPFLAGS@
subdirs = @subdirs@
sysconfdir = @sysconfdir@
target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
PDF_FILES = tutorial.pdf langref.pdf
@@ -279,8 +279,8 @@ ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES)
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | \
- $(AWK) ' { files[$$0] = 1; } \
- END { for (i in files) print i; }'`; \
+ $(AWK) '{ files[$$0] = 1; nonemtpy = 1; } \
+ END { if (nonempty) { for (i in files) print i; }; }'`; \
mkid -fID $$unique
tags: TAGS
@@ -305,8 +305,8 @@ TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | \
- $(AWK) ' { files[$$0] = 1; } \
- END { for (i in files) print i; }'`; \
+ $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
+ END { if (nonempty) { for (i in files) print i; }; }'`; \
if test -z "$(ETAGS_ARGS)$$tags$$unique"; then :; else \
test -n "$$unique" || unique=$$empty_fix; \
$(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
@@ -316,13 +316,12 @@ ctags: CTAGS
CTAGS: ctags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \
$(TAGS_FILES) $(LISP)
tags=; \
- here=`pwd`; \
list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | \
- $(AWK) ' { files[$$0] = 1; } \
- END { for (i in files) print i; }'`; \
+ $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
+ END { if (nonempty) { for (i in files) print i; }; }'`; \
test -z "$(CTAGS_ARGS)$$tags$$unique" \
|| $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \
$$tags $$unique
diff --git a/doc/SystemTap_Beginners_Guide/Makefile b/doc/SystemTap_Beginners_Guide/Makefile
index 7cbd8b2e..32dc0d50 100644
--- a/doc/SystemTap_Beginners_Guide/Makefile
+++ b/doc/SystemTap_Beginners_Guide/Makefile
@@ -2,7 +2,8 @@
XML_LANG = en-US
-BRAND = RedHat
+BRAND = RedHat
+# please define the BRAND in the pre:: section below
#SHOW_REMARKS = 1
#OTHER_LANGS = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW
@@ -12,3 +13,10 @@ CONDITION=$(BRAND)
COMMON_CONFIG = /usr/share/publican
include $(COMMON_CONFIG)/make/Makefile.common
+pre::
+ cp -a ../../testsuite en-US/extras/;
+
+post::
+ rm -rf en-US/extras/testsuite
+ sed -i -e 's/<productname>Fedora/<productname>Red Hat Enterprise Linux/g' en-US/Book_Info.xml;
+ sed -i -e 's/<productnumber>10/<productnumber>5/g' en-US/Book_Info.xml;
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml b/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml
index 676af712..0c55a7ee 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml
@@ -3,7 +3,7 @@
]>
<authorgroup>
- <corpauthor>Red Hat Enterprise Linux Documentation</corpauthor>
+ <corpauthor>Red Hat, Inc.</corpauthor>
<author>
<firstname>Don</firstname>
<surname>Domingo </surname>
@@ -13,4 +13,14 @@
</affiliation>
<email>ddomingo@redhat.com</email>
</author>
+
+ <author>
+ <firstname>William</firstname>
+ <surname>Cohen</surname>
+ <affiliation>
+ <orgname>Engineering Services and Operations</orgname>
+ <orgdiv>Performance Tools</orgdiv>
+ </affiliation>
+ <email>wcohen@redhat.com</email>
+ </author>
</authorgroup>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml b/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml
index 1599dc53..07c3f74d 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml
@@ -7,10 +7,14 @@
<subtitle condition="RedHat">Introduction to SystemTap (for Red Hat Enterprise Linux 5.3)</subtitle>
<subtitle condition="fedora">Introduction to SystemTap (for Fedora Core 10)</subtitle>
<edition>2.0</edition>
+
<productname>Red Hat Enterprise Linux</productname>
<productnumber>5</productnumber>
+
<pubsnumber>2</pubsnumber>
- <abstract><para>This guide provides basic instructions on how to use SystemTap to monitor different subsystems of &PRODUCT; in finer detail. The <citetitle>SystemTap Beginners Guide</citetitle> is recommended for users who have taken <ulink url="https://www.redhat.com/courses/rh133_red_hat_linux_system_administration_and_rhct_exam/">RHCT</ulink> or have a similar level of expertise in &PRODUCT;.</para></abstract>
+ <abstract condition="RedHat"><para>This guide provides basic instructions on how to use SystemTap to monitor different subsystems of &PRODUCT; in finer detail. The <citetitle>SystemTap Beginners Guide</citetitle> is recommended for users who have taken <ulink url="https://www.redhat.com/courses/rh133_red_hat_linux_system_administration_and_rhct_exam/">RHCT</ulink> or have a similar level of expertise in &PRODUCT;.</para></abstract>
+
+ <abstract condition="fedora"><para>This guide provides basic instructions on how to use SystemTap to monitor different subsystems of Fedora Core 10 in finer detail. The <citetitle>SystemTap Beginners Guide</citetitle> is recommended for users who have taken <ulink url="https://www.redhat.com/courses/rh133_red_hat_linux_system_administration_and_rhct_exam/">RHCT</ulink> or have a similar level of expertise in Fedora Core 10.</para></abstract>
<corpauthor>
<inlinemediaobject>
<imageobject>
@@ -23,7 +27,7 @@
<year>&YEAR;</year>
<holder>&HOLDER;</holder>
</copyright>
- <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
index 1ff2ff29..d0ce1f26 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
@@ -70,7 +70,7 @@
<listitem><para><filename>systemtap-runtime</filename></para></listitem>
</itemizedlist>
- <para>Assuming that your system is configured to use Red Hat Network (RHN) or <command>yum</command> is available, these two rpms can be installed with <command>yum install systemtap systemtap-runtime</command>. Note that before you can use SystemTap, you will still need to install the required kernel information RPMs.
+ <para>Assuming that <command>yum</command> is installed in the system, these two rpms can be installed with <command>yum install systemtap systemtap-runtime</command>. Note that before you can use SystemTap, you will still need to install the required kernel information RPMs.
</para>
</section>
@@ -99,9 +99,12 @@
<indexterm>
<primary>kernel information packages</primary>
</indexterm>
- <para> SystemTap needs information about the kernel in order to place instrumentation in it (i.e. probe it). This information also allows SystemTap to generate the code for the instrumentation. This information is contained in the matching <filename>-devel</filename> and <filename>-debuginfo</filename> packages for your kernel. The necessary <filename>-devel</filename> and
- <filename>-debuginfo</filename> packages for the ordinary "vanilla" kernel
- are as follows:
+ <para>
+ SystemTap needs information about the kernel in order to place instrumentation in it (i.e. probe it). This
+ information also allows SystemTap to generate the code for the instrumentation. This information is contained
+ in the matching <filename>-devel</filename>, <filename>-debuginfo</filename>, and <filename>-debuginfo-common</filename>
+ packages for your kernel. The necessary <filename>-devel</filename> and <filename>-debuginfo</filename> packages for the ordinary
+ "vanilla" kernel are as follows:
</para>
<itemizedlist>
@@ -137,7 +140,9 @@
uname -r
</screen>
- <para>For example, if you wish to use SystemTap on kernel version <filename>2.6.18-53.el5</filename> on an i686 machine, then you would need to download and install the following RPMs:
+ <para>
+ For example, if you wish to use SystemTap on kernel version <filename>2.6.18-53.el5</filename> on an i686 machine, then you would
+ need to download and install the following RPMs:
</para>
<itemizedlist>
@@ -146,78 +151,75 @@ uname -r
<listitem><para><filename>kernel-devel-2.6.18-53.1.13.el5.i686.rpm</filename></para></listitem>
</itemizedlist>
- <important>
+ <important>
<title>Important</title>
<para>
- The version, variant, and architecture of the <filename>-devel</filename>, <filename>-debuginfo</filename> and <filename>-debuginfo-common</filename> packages must match the kernel you wish to probe with SystemTap <emphasis>exactly</emphasis>.
+ The version, variant, and architecture of the <filename>-devel</filename>, <filename>-debuginfo</filename> and
+ <filename>-debuginfo-common</filename> packages must match the kernel you wish to probe with SystemTap <emphasis>exactly</emphasis>.
</para>
</important>
+
+
+ <para>
+ The easiest way to install the required kernel information packages is through <command>yum install</command>
+ and <command>debuginfo-install</command>. <command>debuginfo-install</command> is included with later versions of the
+ <filename>yum-utils</filename> package (for example, version 1.1.10), and also requires an appropriate <command>yum</command>
+ repository from which to download and install <command>-debuginfo</command>/<filename>-debuginfo-common</filename> packages.
+ </para>
+
+ <para condition="fedora">
+ Most of the required kernel packages can be found at
+ <ulink url="http://download.fedoraproject.org/pub/fedora/linux/releases/"/>. Configure
+ <command>yum</command> accordingly by adding a new "debug" <command>yum</command> repository file
+ under <filename>/etc/yum.repos.d</filename> containing the following lines:
+ </para>
+
+<programlisting condition="fedora">
+[fedora-debuginfo]
+name=Fedora $releasever - $basearch - Debug
+failovermethod=priority
+baseurl=http://download.fedoraproject.org/pub/fedora/linux/releases/$releasever/Everything/$basearch/debug/
+enabled=1
+</programlisting>
+
+
+ <para condition="RedHat">
+ Most required kernel packages can be found at
+ <ulink url="ftp://ftp.redhat.com/pub/redhat/linux/enterprise/"/>; navigate there until you find the
+ appropriate <filename>Debuginfo</filename> directory for your system. Configure
+ <command>yum</command> accordingly by adding a new "debug" <command>yum</command> repository file under
+ <filename>/etc/yum.repos.d</filename> containing the following lines:
+ </para>
+<programlisting condition="RedHat">
+[rhel-debuginfo]
+name=Red Hat Enterprise Linux $releasever - $basearch - Debug
+baseurl=ftp://ftp.redhat.com/pub/redhat/linux/enterprise/$releasever/en/os/$basearch/Debuginfo/
+enabled=1
+</programlisting>
<para>
- To help ease your deployment of SystemTap, you can use <xref linkend="stapprep"/>.
- <xref linkend="stapprep"/> determines the kernel information packages you need to install in order
- to run SystemTap. If you run <xref linkend="stapprep"/> (as an ordinary, non-root user) without
- any arguments, it will display the kernel information packages required for the
- <emphasis>loaded</emphasis> kernel. You can also pass a specific kernel version to
- <xref linkend="stapprep"/> (e.g. <computeroutput>2.6.18-92.el5</computeroutput>) if you wish
- to probe a kernel that is not currently loaded.
+ After configuring <command>yum</command> with the appropriate repository, you can now install
+ the required <filename>-devel</filename>, <filename>-debuginfo</filename>, and <filename>-debuginfo-common</filename>
+ packages for your kernel. To install the corresponding packages for a specific kernel, run the following commands:
</para>
-<indexterm>
- <primary>Installation</primary>
- <secondary>stapprep.sh</secondary>
-</indexterm>
-
-<indexterm>
- <primary>stapprep.sh</primary>
-</indexterm>
-
-
-<!-- next 2 indexterms for installation script -->
-<indexterm>
- <primary>Installation</primary>
- <secondary>installation script</secondary>
-</indexterm>
+<itemizedlist>
+<listitem><para><command>yum install <replaceable>kernelname</replaceable>-devel-<replaceable>version</replaceable></command></para></listitem>
+<listitem><para><command>debuginfo-install <replaceable>kernelname</replaceable>-<replaceable>version</replaceable></command></para></listitem>
+</itemizedlist>
-<indexterm>
- <primary>installation script</primary>
-</indexterm>
-<note>
- <title>Note</title>
- <para>Running <xref linkend="stapprep"/> as root will display the required kernel packages <emphasis>and</emphasis> install them as well, provided that <command>yum</command> and <command>yum-utils</command> are configured properly.</para>
-</note>
-
-<!-- Running <xref linkend="stapprep"/> without any arguments will display and install the required kernel information packages for the currently loaded kernel. If you wish to probe a kernel other than the one currently loaded, you can pass a specific kernel version as an argument to <xref linkend="stapprep"/>; the script will then install that kernel's corresponding kernel information packages.
-</para> -->
-
-<!--
-<para>
- To determine what kernel information RPMs you need to install in order to run SystemTap, run the <xref linkend="stapprep"/>. Running <xref linkend="stapprep"/> without any arguments will display what packages you
-
-
-
- <para> The script <xref linkend="stapprep"/> can be used by normal users to determine what supporting kernel RPMs need to be installed on the machine to use SystemTap with a particular kernel. The script run without any arguments detemines the RPMs needed for the currently running kernel. The script can also accept one argument, the output <command>uname -r</command>, to determine the related RPMs required for a kernel that may not be currently running on the machine.
- </para>-->
-<indexterm>
-<primary>script for installing kernel information packages</primary>
-</indexterm>
-<formalpara id="stapprep">
-<title>stapprep.sh</title>
<para>
-<programlisting>
-<xi:include parse="text" href="extras/stapprep.sh" xmlns:xi="http://www.w3.org/2001/XInclude" />
-</programlisting>
+ Replace <command><replaceable>kernelname</replaceable></command> with the appropriate kernel variant name
+ (for example, <filename>kernel-PAE</filename>), and <command><replaceable>version</replaceable></command>
+ with the target kernel's version. For example, to install the required kernel information packages for
+ the <command>kernel-PAE--2.6.18-53.1.13.el5</command> kernel, run:
</para>
-</formalpara>
-<!--
- <para>
- If the <filename>yum-utils</filename> package is installed and the <command>yum</command> repositories are set up properly, you can run the <xref linkend="stapprep"/> script as root. <xref linkend="stapprep"/> will automatically download and install the required packages via <command>yum</command> and <command>rpm</command> commands (assuming that the kernel you wish to probe is currently loaded).
- </para>-->
-<!-- The script assumes the Red Hat Enterprise Linux debuginfo repository,
-<filename>rhel-debuginfo</filename>, but this could be changed. One could
-search the /etc/yum.repo.d/ directory for debuginfo repositories -->
+<itemizedlist>
+ <listitem><para><command>yum install kernel-PAE-devel-2.6.18-53.1.13.el5</command></para></listitem>
+ <listitem><para><command>debuginfo-install kernel-PAE-2.6.18-53.1.13.el5</command></para></listitem>
+</itemizedlist>
<para>
If you do not have <command>yum</command> and <command>yum-utils</command> installed (and you are unable to install them), you will have to manually download and install the required kernel information packages. To generate the URL from which to download the required packages, use the following script:
@@ -266,6 +268,7 @@ Once you have manually downloaded the required packages to the machine, install
</section>
+
<section id="testing">
<title>Initial Testing</title>
<indexterm>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
index 005bfba0..afb9e738 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
@@ -101,7 +101,9 @@
<primary>capabilities of SystemTap</primary>
<secondary>Introduction</secondary>
</indexterm>
- <para>SystemTap was originally developed to provide functionality for &PROD; similar to previous Linux probing tools such as <application>dprobes</application> and the Linux Trace Toolkit. SystemTap aims to supplement the existing suite of Linux monitoring tools by providing users with the infrastructure to track kernel activity. In addition, SystemTap combines this capability with two things:</para>
+<para condition="RedHat">SystemTap was originally developed to provide functionality for &PROD; similar to previous Linux probing tools such as <application>dprobes</application> and the Linux Trace Toolkit. SystemTap aims to supplement the existing suite of Linux monitoring tools by providing users with the infrastructure to track kernel activity. In addition, SystemTap combines this capability with two things:</para>
+
+<para condition="fedora">SystemTap was originally developed to provide functionality for Fedora Core 10 similar to previous Linux probing tools such as <application>dprobes</application> and the Linux Trace Toolkit. SystemTap aims to supplement the existing suite of Linux monitoring tools by providing users with the infrastructure to track kernel activity. In addition, SystemTap combines this capability with two things:</para>
<!--
<para>SystemTap was originally developed as a working &PROD; version of old Linux probing tools such as <application>dprobes</application> and the Linux Trace Toolkit. Further, SystemTap can also be considered the Linux answer to <firstterm>Dtrace</firstterm>. Dtrace is a Sun Microsystems "dynamic tracing" framework that assists administrators in monitoring and troubleshooting kernel and user-space applications in real time.</para>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Legal_Notice.xml b/doc/SystemTap_Beginners_Guide/en-US/Legal_Notice.xml
new file mode 100644
index 00000000..1fcb7b99
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Legal_Notice.xml
@@ -0,0 +1,30 @@
+<?xml version='1.0'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<legalnotice>
+ <para>
+ This documentation is free software; you can redistribute
+ it and/or modify it under the terms of the GNU General Public
+ License version 2 as published by the Free Software Foundation.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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., 59 Temple Place, Suite 330, Boston,
+ MA 02111-1307 USA
+ </para>
+
+ <para>
+ For more details see the file COPYING in the source
+ distribution of Linux.
+ </para>
+</legalnotice>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-syscallsbyprocpid.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-syscallsbyprocpid.xml
new file mode 100644
index 00000000..d8fe4b39
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-syscallsbyprocpid.xml
@@ -0,0 +1,132 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+
+<section id="syscallsbyprocpidsect">
+<title>Tracking System Call Volume Per Process</title>
+<indexterm>
+<primary>script examples</primary>
+<secondary>monitoring system calls (volume per process)</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>monitoring system calls (volume per process)</secondary>
+</indexterm>
+
+<indexterm>
+<primary>monitoring system calls (volume per process)</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<!--
+<indexterm>
+<primary>counting function calls</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+-->
+
+<indexterm>
+<primary>system calls volume (per process), monitoring</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<remark>
+uses systemtap/testsuite/systemtap.examples/process/syscalls_by_p*.stp
+</remark>
+
+ <para>
+ This section illustrates how to determine which processes
+ are performing the highest volume of system calls. In
+ previous sections, we've described how to monitor the top system
+ calls used by the system over time (<xref linkend="topsyssect"/>).
+ We've also described how to identify which applications use a
+ specific set of "polling suspect" system calls the most
+ (<xref linkend="timeoutssect"/>). Monitoring the volume of
+ system calls made by each process provides more data in
+ investigating your system for polling processes and other resource
+ hogs.
+ </para>
+
+<formalpara id="syscallsbyprocpid">
+ <title>syscalls_by_proc.stp</title>
+<para>
+<programlisting>
+<xi:include parse="text" href="extras/testsuite/systemtap.examples/process/syscalls_by_proc.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+</para>
+</formalpara>
+
+<para>
+ <xref linkend="syscallsbyprocpid"/> lists the top 20 processes performing the
+ highest number of system calls. It also lists how many system calls each process
+ performed during the time period. Refer to
+ <xref linkend="syscallsbyprocpidoutput"/> for a sample output.
+
+</para>
+
+<example id="syscallsbyprocpidoutput">
+ <title><xref linkend="topsys"/> Sample Output</title>
+<screen>
+Collecting data... Type Ctrl-C to exit and display results
+#SysCalls Process Name
+1577 multiload-apple
+692 synergyc
+408 pcscd
+376 mixer_applet2
+299 gnome-terminal
+293 Xorg
+206 scim-panel-gtk
+95 gnome-power-man
+90 artsd
+85 dhcdbd
+84 scim-bridge
+78 gnome-screensav
+66 scim-launcher
+[...]
+</screen>
+</example>
+
+<para>
+ If you prefer the output to display the process IDs instead of the process names,
+ use the following script instead.
+</para>
+
+<formalpara id="syscallsbypid">
+ <title>syscalls_by_pid.stp</title>
+<para>
+<programlisting>
+<xi:include parse="text" href="extras/testsuite/systemtap.examples/process/syscalls_by_pid.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+</para>
+</formalpara>
+
+
+<para>
+ As indicated in the output, you need to manually exit the script in order to display the
+ results. You can add a timed expiration to either script by simply adding
+ a <command>timer.s()</command> probe; for example, to instruct the script to expire after
+ 5 seconds, add the following probe to the script:
+</para>
+
+<screen>
+probe timer.s(5)
+{
+ exit()
+}
+</screen>
+
+<!--probe kernel.function(@1) { # probe function passed as argument from stdin
+called[probefunc()] &lt;&lt;&lt; 1 # add a count efficiently
+}
+global called
+probe end,timer.ms(30000) {
+foreach (fn+ in called) # Sort by function name
+# (fn in called-) # Sort by call count (in decreasing order)
+printf("%s %d\n", fn, @count(called[fn]))
+exit()
+}-->
+
+ </section>
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
new file mode 100644
index 00000000..719f5c6d
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
@@ -0,0 +1,136 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+
+<section id="timeoutssect">
+<title>Monitoring Polling Applications</title>
+<indexterm>
+<primary>script examples</primary>
+<secondary>monitoring polling applications</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>monitoring polling applications</secondary>
+</indexterm>
+
+<indexterm>
+<primary>monitoring polling applications</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<!--
+<indexterm>
+<primary>counting function calls</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+-->
+
+<indexterm>
+<primary>polling applications, monitoring</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<remark>
+uses systemtap/testsuite/systemtap.examples/profiling/timeout.stp
+</remark>
+
+
+ <para>
+ This section how to identify and monitor which applications are polling. Doing so allows you to track
+ unnecessary or excessive polling, which can help you pinpoint areas for improvement in terms of CPU usage
+ and power savings.
+ </para>
+
+<formalpara id="timeouts">
+ <title>timeout.stp</title>
+<para>
+<programlisting>
+<xi:include parse="text" href="extras/testsuite/systemtap.examples/profiling/timeout.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+</para>
+</formalpara>
+
+ <para>
+ <xref linkend="timeouts"/> tracks how many times each application used the following system calls over time:
+ </para>
+
+ <itemizedlist>
+ <listitem><para><command>poll</command></para></listitem>
+ <listitem><para><command>select</command></para></listitem>
+ <listitem><para><command>epoll</command></para></listitem>
+ <listitem><para><command>itimer</command></para></listitem>
+ <listitem><para><command>futex</command></para></listitem>
+ <listitem><para><command>nanosleep</command></para></listitem>
+ <listitem><para><command>signal</command></para></listitem>
+ </itemizedlist>
+
+ <para>
+ In some applications, these system calls are used excessively. As such, they are normally identified as "likely
+ culprits" for polling applications. Note, however, that an application may be using a different system
+ call to poll excessively; sometimes, it is useful to find out the top system calls used by the system (refer to
+ <xref linkend="topsyssect"/> for instructions). Doing so can help you identify any additional suspects, which you
+ can add to <xref linkend="timeouts"/> for tracking.
+ </para>
+
+
+<indexterm>
+<primary>script examples</primary>
+<secondary>timer.s(), sample usage</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>timer.s(), sample usage</secondary>
+</indexterm>
+
+<indexterm>
+<primary>timer.s(), sample usage</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<example id="timeoutsoutput">
+ <title><xref linkend="timeouts"/> Sample Output</title>
+<screen>
+ uid | poll select epoll itimer futex nanosle signal| process
+28937 | 148793 0 0 4727 37288 0 0| firefox
+22945 | 0 56949 0 1 0 0 0| scim-bridge
+ 0 | 0 0 0 36414 0 0 0| swapper
+ 4275 | 23140 0 0 1 0 0 0| mixer_applet2
+ 4191 | 0 14405 0 0 0 0 0| scim-launcher
+22941 | 7908 1 0 62 0 0 0| gnome-terminal
+ 4261 | 0 0 0 2 0 7622 0| escd
+ 3695 | 0 0 0 0 0 7622 0| gdm-binary
+ 3483 | 0 7206 0 0 0 0 0| dhcdbd
+ 4189 | 6916 0 0 2 0 0 0| scim-panel-gtk
+ 1863 | 5767 0 0 0 0 0 0| iscsid
+ 2562 | 0 2881 0 1 0 1438 0| pcscd
+ 4257 | 4255 0 0 1 0 0 0| gnome-power-man
+ 4278 | 3876 0 0 60 0 0 0| multiload-apple
+ 4083 | 0 1331 0 1728 0 0 0| Xorg
+ 3921 | 1603 0 0 0 0 0 0| gam_server
+ 4248 | 1591 0 0 0 0 0 0| nm-applet
+ 3165 | 0 1441 0 0 0 0 0| xterm
+29548 | 0 1440 0 0 0 0 0| httpd
+ 1862 | 0 0 0 0 0 1438 0| iscsid
+</screen>
+</example>
+<!--probe kernel.function(@1) { # probe function passed as argument from stdin
+called[probefunc()] &lt;&lt;&lt; 1 # add a count efficiently
+}
+global called
+probe end,timer.ms(30000) {
+foreach (fn+ in called) # Sort by function name
+# (fn in called-) # Sort by call count (in decreasing order)
+printf("%s %d\n", fn, @count(called[fn]))
+exit()
+}-->
+<para>
+ You can increase the sample time by editing the timer in the second probe (<command>timer.s()</command>).
+ The output of <xref linkend="countcalls"/> contains the name and UID of the top 20 polling applications,
+ along with how many times each application performed each polling system call (over time).
+ <xref linkend="timeoutsoutput"/> contains an excerpt of the script:
+</para>
+ </section>
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml
new file mode 100644
index 00000000..700ef4ed
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml
@@ -0,0 +1,131 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+
+<section id="topsyssect">
+<title>Tracking Most Frequently Used System Calls</title>
+<indexterm>
+<primary>script examples</primary>
+<secondary>monitoring system calls</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>monitoring system calls</secondary>
+</indexterm>
+
+<indexterm>
+<primary>monitoring system calls</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<!--
+<indexterm>
+<primary>counting function calls</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+-->
+
+<indexterm>
+<primary>system calls, monitoring</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<remark>
+uses systemtap/testsuite/systemtap.examples/profiling/topsys.stp
+</remark>
+
+
+ <para>
+ <xref linkend="timeouts"/> from <xref linkend="timeoutssect"/> helps you identify which applications
+ are polling by pointing out which ones used the following system calls most frequently:
+ </para>
+
+ <itemizedlist>
+ <listitem><para><command>poll</command></para></listitem>
+ <listitem><para><command>select</command></para></listitem>
+ <listitem><para><command>epoll</command></para></listitem>
+ <listitem><para><command>itimer</command></para></listitem>
+ <listitem><para><command>futex</command></para></listitem>
+ <listitem><para><command>nanosleep</command></para></listitem>
+ <listitem><para><command>signal</command></para></listitem>
+ </itemizedlist>
+
+ <para>
+ However, in some systems, a different system call might be responsible for excessive polling. If you suspect
+ that a polling application might is using a different system call to poll, you need to identify first the top
+ system calls used by the system. To do this, use <xref linkend="topsys"/>.
+ </para>
+
+<formalpara id="topsys">
+ <title>topsys.stp</title>
+<para>
+<programlisting>
+<xi:include parse="text" href="extras/testsuite/systemtap.examples/profiling/topsys.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+</para>
+</formalpara>
+
+<para>
+ <xref linkend="topsys"/> lists the top 20 system calls used by the system per 5-second interval. It also lists
+ how many times each system call was used during that period. Refer to <xref linkend="topsysoutput"/> for a sample output.
+</para>
+
+<indexterm>
+<primary>script examples</primary>
+<secondary>timer.s(), sample usage</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>timer.s(), sample usage</secondary>
+</indexterm>
+
+<indexterm>
+<primary>timer.s(), sample usage</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+
+<example id="topsysoutput">
+ <title><xref linkend="topsys"/> Sample Output</title>
+<screen>
+--------------------------------------------------------------
+ SYSCALL COUNT
+ gettimeofday 1857
+ read 1821
+ ioctl 1568
+ poll 1033
+ close 638
+ open 503
+ select 455
+ write 391
+ writev 335
+ futex 303
+ recvmsg 251
+ socket 137
+ clock_gettime 124
+ rt_sigprocmask 121
+ sendto 120
+ setitimer 106
+ stat 90
+ time 81
+ sigreturn 72
+ fstat 66
+--------------------------------------------------------------
+</screen>
+</example>
+<!--probe kernel.function(@1) { # probe function passed as argument from stdin
+called[probefunc()] &lt;&lt;&lt; 1 # add a count efficiently
+}
+global called
+probe end,timer.ms(30000) {
+foreach (fn+ in called) # Sort by function name
+# (fn in called-) # Sort by call count (in decreasing order)
+printf("%s %d\n", fn, @count(called[fn]))
+exit()
+}-->
+
+ </section>
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
index 8b7fc741..b18062f3 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -62,6 +62,9 @@
<xi:include href="Useful_Scripts-functioncalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Useful_Scripts-paracallgraph.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Useful_Scripts-threadtimes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Useful_Scripts-timeout.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Useful_Scripts-topsys.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Useful_Scripts-syscallsbyprocpid.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</section>
<!-- removed; handler function no longer working as expected
<xi:include href="Useful_Scripts-kernelprofiling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
diff --git a/doc/SystemTap_Beginners_Guide/syncandbuild.sh b/doc/SystemTap_Beginners_Guide/syncandbuild.sh
index 75e8bd0d..e6a6c1f4 100755
--- a/doc/SystemTap_Beginners_Guide/syncandbuild.sh
+++ b/doc/SystemTap_Beginners_Guide/syncandbuild.sh
@@ -1,14 +1,25 @@
#!/bin/bash
# Instead of running the original makefile to build the document, run this script instead
-echo -n "Please specify your build target (e.g. html-en-US, pdf-en-US, etc) "
+echo -n "Please specify your build target (e.g. html, pdf, or html-single) "
read TARG
-echo -n "Thank you. Now specify any build parameters you'd like to use (skip this step for none). "
+echo -n "Please specify the product you are building for (enter 1 for Fedora, 2 for RHEL) "
+read PROD
+echo -n "Please specify any build parameters you'd like to use (skip this step for none). "
read PARM
-cp -a ../../testsuite en-US/extras/.
+if [ $PROD = 1 ];
+then
+ sed -i -e 's/<productname>Red Hat Enterprise Linux/<productname>Fedora/g' en-US/Book_Info.xml;
+ sed -i -e 's/<productnumber>5/<productnumber>10/g' en-US/Book_Info.xml;
+ sed -i -e 's/BRAND = RedHat/BRAND = fedora/g' Makefile;
+ make $PARM $TARG-en-US post
-make $PARM $TARG
+else
+sed -i -e 's/BRAND = fedora/BRAND = RedHat/g' Makefile;
+make post $PARM $TARG-en-US
+fi
+echo "done."
echo "Cleaning sync'd files..."
-rm -rf en-US/extras/testsuite
-echo "...done."
+make post
+echo "...done." \ No newline at end of file
diff --git a/doc/SystemTap_Tapset_Reference/.gitignore b/doc/SystemTap_Tapset_Reference/.gitignore
new file mode 100644
index 00000000..af43f913
--- /dev/null
+++ b/doc/SystemTap_Tapset_Reference/.gitignore
@@ -0,0 +1 @@
+/docproc
diff --git a/doc/SystemTap_Tapset_Reference/Makefile.in b/doc/SystemTap_Tapset_Reference/Makefile.in
index f840d8c5..84d2114c 100644
--- a/doc/SystemTap_Tapset_Reference/Makefile.in
+++ b/doc/SystemTap_Tapset_Reference/Makefile.in
@@ -1,8 +1,8 @@
-# Makefile.in generated by automake 1.10 from Makefile.am.
+# Makefile.in generated by automake 1.10.1 from Makefile.am.
# @configure_input@
# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-# 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
@@ -46,7 +46,7 @@ PROGRAMS = $(noinst_PROGRAMS)
docproc_SOURCES = docproc.c
docproc_OBJECTS = docproc.$(OBJEXT)
docproc_LDADD = $(LDADD)
-DEFAULT_INCLUDES = -I. -I$(top_builddir)@am__isrc@
+DEFAULT_INCLUDES = -I.@am__isrc@ -I$(top_builddir)
depcomp = $(SHELL) $(top_srcdir)/depcomp
am__depfiles_maybe = depfiles
COMPILE = $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) \
@@ -104,8 +104,9 @@ PACKAGE_STRING = @PACKAGE_STRING@
PACKAGE_TARNAME = @PACKAGE_TARNAME@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
+PIECFLAGS = @PIECFLAGS@
+PIECXXFLAGS = @PIECXXFLAGS@
PIELDFLAGS = @PIELDFLAGS@
-PKG_CONFIG = @PKG_CONFIG@
PROCFLAGS = @PROCFLAGS@
RANLIB = @RANLIB@
SET_MAKE = @SET_MAKE@
@@ -150,9 +151,7 @@ localstatedir = @localstatedir@
mandir = @mandir@
mkdir_p = @mkdir_p@
nspr_CFLAGS = @nspr_CFLAGS@
-nspr_LIBS = @nspr_LIBS@
nss_CFLAGS = @nss_CFLAGS@
-nss_LIBS = @nss_LIBS@
oldincludedir = @oldincludedir@
pdfdir = @pdfdir@
prefix = @prefix@
@@ -241,8 +240,8 @@ ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES)
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | \
- $(AWK) ' { files[$$0] = 1; } \
- END { for (i in files) print i; }'`; \
+ $(AWK) '{ files[$$0] = 1; nonemtpy = 1; } \
+ END { if (nonempty) { for (i in files) print i; }; }'`; \
mkid -fID $$unique
tags: TAGS
@@ -254,8 +253,8 @@ TAGS: $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | \
- $(AWK) ' { files[$$0] = 1; } \
- END { for (i in files) print i; }'`; \
+ $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
+ END { if (nonempty) { for (i in files) print i; }; }'`; \
if test -z "$(ETAGS_ARGS)$$tags$$unique"; then :; else \
test -n "$$unique" || unique=$$empty_fix; \
$(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
@@ -265,13 +264,12 @@ ctags: CTAGS
CTAGS: $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \
$(TAGS_FILES) $(LISP)
tags=; \
- here=`pwd`; \
list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | \
- $(AWK) ' { files[$$0] = 1; } \
- END { for (i in files) print i; }'`; \
+ $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
+ END { if (nonempty) { for (i in files) print i; }; }'`; \
test -z "$(CTAGS_ARGS)$$tags$$unique" \
|| $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \
$$tags $$unique
diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
index f1750d45..d6b3b309 100644
--- a/doc/SystemTap_Tapset_Reference/tapsets.tmpl
+++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
@@ -10,6 +10,7 @@
<author>
<firstname>William</firstname>
<surname>Cohen</surname>
+ <contrib></contrib>
<affiliation>
<address>
<email>wcohen@redhat.com</email>
@@ -204,5 +205,13 @@
</para>
!Itapset/process.stp
</chapter>
+ <chapter id="signal.stp">
+ <title>Signal Tapset</title>
+ <para>
+ This family of probe points is used to probe signal activities.
+ It contains the following probe points:
+ </para>
+!Itapset/signal.stp
+ </chapter>
</book>
diff --git a/doc/Tapset_Reference_Guide/en-US/Author_Group.xml b/doc/Tapset_Reference_Guide/en-US/Author_Group.xml
new file mode 100644
index 00000000..67ea97dc
--- /dev/null
+++ b/doc/Tapset_Reference_Guide/en-US/Author_Group.xml
@@ -0,0 +1,25 @@
+<?xml version='1.0'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<authorgroup>
+ <corpauthor>Red Hat Enterprise Linux Documentation</corpauthor>
+ <author>
+ <firstname>Don</firstname>
+ <surname>Domingo</surname>
+ <affiliation>
+ <orgname>Engineering Services and Operations</orgname>
+ <orgdiv>Content Services</orgdiv>
+ </affiliation>
+ <email>ddomingo@redhat.com</email>
+ </author>
+ <author>
+ <firstname>William</firstname>
+ <surname>Cohen</surname>
+ <affiliation>
+ <orgname>Engineering Services and Operations</orgname>
+ <orgdiv>Performance Tools</orgdiv>
+ </affiliation>
+ <email>wcohen@redhat.com</email>
+ </author>
+</authorgroup>
diff --git a/doc/Tapset_Reference_Guide/publicanize.sh b/doc/Tapset_Reference_Guide/publicanize.sh
new file mode 100755
index 00000000..96c20a11
--- /dev/null
+++ b/doc/Tapset_Reference_Guide/publicanize.sh
@@ -0,0 +1,48 @@
+#!/bin/bash
+
+#copy the automated tapsets.xml
+cp ../SystemTap_Tapset_Reference/tapsets.xml en-US/Tapset_Reference_Guide.xml ;
+
+#remove all excess whitespace
+sed -i -e 's/^\s*//g' en-US/Tapset_Reference_Guide.xml ;
+
+#re-convert programlisting tags
+sed -i -e 's/&lt;programlisting&gt;/<programlisting>/g' en-US/Tapset_Reference_Guide.xml;
+sed -i -e 's/&lt;\/programlisting&gt;/<\/programlisting>/g' en-US/Tapset_Reference_Guide.xml;
+
+#replace header
+
+cat en-US/Tapset_Reference_Guide.xml |
+perl -p -e 'undef $/;s|<bookinfo>\n<title>SystemTap Tapset Reference Manual</title>|<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />\n<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />|msg' |
+perl -p -e 'undef $/;s|<authorgroup>\n<author>\n<firstname>William</firstname>\n<surname>Cohen</surname>\n<contrib></contrib>\n<affiliation>\n<address>\n<email>wcohen\@redhat.com</email>\n</address>\n</affiliation>\n</author>\n</authorgroup>||msg' |
+perl -p -e 'undef $/;s|<copyright>\n<year>2008, 2009</year>\n<holder>Red Hat, Inc.</holder>\n</copyright>||msg' |
+perl -p -e 'undef $/;s|<legalnotice>\n<para>\nThis documentation is free software\; you can redistribute\nit and/or modify it under the terms of the GNU General Public\nLicense version 2 as published by the Free Software Foundation.\n</para>||msg' |
+perl -p -e 'undef $/;s|<para>\nThis program is distributed in the hope that it will be\nuseful, but WITHOUT ANY WARRANTY; without even the implied\nwarranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\nSee the GNU General Public License for more details.\n</para>||msg' |
+perl -p -e 'undef $/;s|<para>\nYou should have received a copy of the GNU General Public\nLicense along with this program; if not, write to the Free\nSoftware Foundation, Inc., 59 Temple Place, Suite 330, Boston,\nMA 02111-1307 USA\n</para>||msg' |
+perl -p -e 'undef $/;s|<para>\nFor more details see the file COPYING in the source\ndistribution of Linux.\n</para>\n</legalnotice>\n</bookinfo>||msg' |
+perl -p -e 'undef $/;s|<toc></toc>||msg' |
+perl -p -e 'undef $/;s|\n\n\n\n\n\n\n\n\n\n\n\n\n\n||msg' |
+perl -p -e 'undef $/;s|<programlisting>\n|<programlisting>\n<emphasis>(sfunction) <\/emphasis>|msg' |
+perl -p -e 'undef $/;s|<para>\n</para>||msg' |
+perl -p -e 'undef $/;s|<para>\n\n</para>||msg' |
+perl -p -e 'undef $/;s|<para>\n<programlisting>|<programlisting>|msg' |
+perl -p -e 'undef $/;s|</programlisting>\n</para>|</programlisting>|msg' > clean.xml
+
+cp clean.xml en-US/Tapset_Reference_Guide.xml
+rm clean.xml
+
+# statements change synopsis tags, as they are still currently unfixed in publican-redhat
+sed -i -e 's/refsynopsisdiv>/refsect1>/g' en-US/Tapset_Reference_Guide.xml;
+sed -i -e 's/refsect1>/refsection>/g' en-US/Tapset_Reference_Guide.xml;
+sed -i -e 's/synopsis>/programlisting>\n/g' en-US/Tapset_Reference_Guide.xml;
+
+# re-convert tags
+
+sed -i -e 's/&lt;emphasis&gt;/<emphasis>/g' en-US/Tapset_Reference_Guide.xml;
+sed -i -e 's/&lt;\/emphasis&gt;/<\/emphasis>/g' en-US/Tapset_Reference_Guide.xml;
+
+sed -i -e 's/&lt;remark&gt;/<remark>/g' en-US/Tapset_Reference_Guide.xml;
+sed -i -e 's/&lt;\/remark&gt;/<\/remark>/g' en-US/Tapset_Reference_Guide.xml;
+
+sed -i -e 's/&lt;command&gt;/<command>/g' en-US/Tapset_Reference_Guide.xml;
+sed -i -e 's/&lt;\/command&gt;/<\/command>/g' en-US/Tapset_Reference_Guide.xml; \ No newline at end of file
diff --git a/doc/langref.tex b/doc/langref.tex
index 3af2bd15..5aefa278 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -706,6 +706,7 @@ kernel.function(PATTERN).call
kernel.function(PATTERN).return
kernel.function(PATTERN).return.maxactive(VALUE)
kernel.function(PATTERN).inline
+kernel.function(PATTERN).label(LPATTERN)
module(MPATTERN).function(PATTERN)
module(MPATTERN).function(PATTERN).call
module(MPATTERN).function(PATTERN).return.maxactive(VALUE)
@@ -737,8 +738,11 @@ The \textbf{.statement} variant places a probe at the exact spot, exposing those
variables that are visible there.
In the above probe descriptions, MPATTERN stands for a string literal
-that identifies the loaded kernel module of interest. It may include asterisk
-({*}), square brackets \char`\"{}{[}]\char`\"{}, and question mark (?) wildcards.
+that identifies the loaded kernel module of interest and LPATTERN
+stands for a source program label. Both MPATTERN and LPATTERN may
+include asterisk ({*}), square brackets \char`\"{}{[}]\char`\"{}, and
+question mark (?) wildcards.
+
PATTERN stands for a string literal that identifies a point in the program.
It is composed of three parts: