From 986ad45b8bdbe661a44da48cae26977d923fa47d Mon Sep 17 00:00:00 2001
From: ddomingo <ddomingo@redhat.com>
Date: Mon, 6 Oct 2008 16:17:03 +1000
Subject: added target(), -c and -x to functions, also added Basic Constructs
 (conditional statements and variables)

---
 doc/SystemTap_Beginners_Guide/en-US/Scripts.xml    | 131 +++++++++++++++++++--
 .../en-US/Using_SystemTap.xml                      |  13 ++
 2 files changed, 134 insertions(+), 10 deletions(-)

(limited to 'doc/SystemTap_Beginners_Guide')

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index b928372b..4abd81a5 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -76,7 +76,7 @@ probe	<replaceable>event</replaceable>,
 		<para>The entry to the kernel function <replaceable>function</replaceable>. For example, <command>kernel.function("sys_open")</command> refers to the "event" that occurs when the kernel function <command>sys_open</command> is called by any thread in the system. To specify the <emphasis>return</emphasis> of the kernel function <command>sys_open</command>, append the <command>return</command> string to the event statement; i.e. <command>kernel.function("sys_open").return</command>.</para>
 		
 		<para>When defining functions, you can use asterisk (<literal>*</literal>) for wildcards. You can also trace the entry or exit of a function in a kernel source file. Consider the following example:</para>
-<example id="wildcards"><title>Wildcards and Kernel Source Files in an Event</title>
+<example id="wildcards"><title>wildcards.stp</title>
 <programlisting>
 probe kernel.function("*@net/socket.c") { }
 probe kernel.function("*@net/socket.c").return { }
@@ -101,11 +101,11 @@ probe kernel.function("*@net/socket.c").return { }
 	<listitem>
 		<para>Allows you to probe functions within modules. For example:</para>
 		
-		<example id="eventsmodules"><title>Module Probe</title>
-			<programlisting>
-				probe module("ext3").function("*") { }
-				probe module("ext3").function("*").return { }
-			</programlisting>	
+<example id="eventsmodules"><title>moduleprobe.stp</title>
+<programlisting>
+probe module("ext3").function("*") { }
+probe module("ext3").function("*").return { }
+</programlisting>	
 		</example>
 		
 		<para>
@@ -152,7 +152,7 @@ probe kernel.function("*@net/socket.c").return { }
 	<listitem>
 		<para>An event that specifies a handler to be executed every  specified period of time. For example:</para>
 		
-<example id="timer"><title>Using timer.ms</title>		
+<example id="timer"><title>timer-ms.stp</title>		
 <programlisting>
 probe timer.ms(4000)
 {
@@ -224,7 +224,7 @@ probe timer.ms(4000)
 Consider the following sample script:
 </para>
 
-<example id="helloworld"><title>Hello World</title>
+<example id="helloworld"><title>helloworld.stp</title>
 <programlisting>
 probe begin
 {
@@ -269,7 +269,7 @@ printf ("<replaceable>format string</replaceable>\n", <replaceable>argument</rep
 </para>
 
 <example id="syscall-open">
-	<title>Using Variables In printf ( ) Statements</title>
+	<title>variables-in-printf-statements.stp</title>
 <programlisting>
 # This probe will need to be manually terminated with Ctrl-C
 probe syscall.open
@@ -368,7 +368,7 @@ hald(2360) open
 			Consider the following example on the use of <command>thread_indent()</command>:
 		</para>
 		
-<example id="thread_indent"><title>Using thread_indent()</title>
+<example id="thread_indent"><title>thread_indent.stp</title>
 <programlisting>
 probe kernel.function("*@net/socket.c") 
 {
@@ -405,6 +405,41 @@ probe kernel.function("*@net/socket.c").return
 	
 	</listitem>	
 </varlistentry>
+
+<varlistentry>
+	<term>name</term>
+	<listitem>
+		<para>Identifies the name of a specific system call.</para>
+	</listitem>	
+</varlistentry>
+
+<varlistentry>
+	<term>target()</term>
+	<listitem>
+		<para>Used in conjunction with <command>stap <replaceable>script</replaceable> -x <replaceable>process ID</replaceable></command> or <command>stap <replaceable>script</replaceable> -c <replaceable>command</replaceable>. If you want to specify a script to take an argument of a process ID or command, use <command>target()</command> as the variable in the script to refer to it. For example:</para>
+			
+<example id="targetexample">
+	<title>targetexample.stp</title>
+<programlisting>
+probe syscall.* {
+	if (pid() == target()) {
+		printf("%s/n", name)
+	}}	
+</programlisting>
+</example>
+
+	<para>When <xref linkend="targetexample"/> is run with the argument <command>-x <replaceable>process ID</replaceable></command>, it watches all system calls (as specified by the event <command>syscall.*</command>) and prints out the name of all system calls made by the specified process.</para>
+	
+	<para>This has the same effect as specifying <command>if (pid() == <replaceable>process ID</replaceable></command> each time you wish to target a specific process. However, using <command>target()</command> makes it easier for you to re-use the script, giving you the ability to simply pass a process ID as an argument each time you wish to run the script (i.e. <command>stap allsyscalls.stp -x <replaceable>process ID</replaceable>).</para>
+<!--		
+<note>
+	<title>Note</title>
+	<para>In <xref linkend="targetexample"/>, <command>name</command> instructs SystemTap to capture the name of the process</para>
+</note>	-->
+		
+	</listitem>	
+</varlistentry>
+
 <!--	
 <varlistentry>
 	<term></term>
@@ -437,7 +472,83 @@ probe kernel.function("*@net/socket.c").return
 
 
 	</section>
+	<section id="handlerconditionals">
+		<title>Basic Handler Constructs</title>
+			
+<para>SystemTap supports the use of several basic constructs in handlers. The syntax for most of these handler constructs are loosely based on C and <command>awk</command> syntax; this section describes several of the most commonly used ones.</para>
+
+<formalpara id="variablesconstructs">
+	<title>Variables</title>
+		
+	<para>Variables can be used freely throughout a handler; simply choose a name, assign it to a function, and use it in an expression. SystemTap automatically identifies whether a variable should be identified as a string or integer, based on the function it is assigned to. For instance, if you use set the variable <command>foo</command> to <command>gettimeofday_s()</command> (as in <command>foo = gettimeofday_s()</command>), then <command>foo</command> can be used as an integer argument (<command>%d</command>) in <command>printf()</command>.</para>
+</formalpara>
+
+<para>Note, however, that by default variables are only local to the probe they are used in. This means that variables are initialized, used and disposed at each probe handler invocation. To share a variable between probes, declare the variable name first using <command>global</command> outside of any probe.</para>
+	
+
+<formalpara>
+	<title>Conditional Statements</title>
+<para>
+In some cases, the output of a SystemTap script may be too big. To address this, you need to further refine the script's logic in order to delimit the output into something more relevant or useful to your probe.
+</para>
+</formalpara>
+<para>
+You can do this by using <emphasis>conditionals</emphasis> in handlers. SystemTap accepts the following types of conditional statements:
+</para>
+
+<variablelist>
+<varlistentry>
+	<term>If/Else Statements</term>
+	<listitem>
+		<para>Format:</para>
+<programlisting>
+{ 
+if (<replaceable>condition</replaceable>) 
+	{<replaceable>handler</replaceable>} [else {<replaceable>handler</replaceable>}]
+}
+</programlisting>
+	</listitem>	
+</varlistentry>	
 	
+<varlistentry>
+	<term>While Loops</term>
+	<listitem>
+		<para>Format:</para>
+<programlisting>
+{
+while (<replaceable>condition</replaceable>) {<replaceable>handler</replaceable>}
+}
+</programlisting>	
+	</listitem>	
+</varlistentry>	
+
+<varlistentry>
+	<term>For Loops</term>
+	<listitem>
+		<para>Format:</para>
+<programlisting>
+{
+for (<replaceable>argument1</replaceable>; <replaceable>argument2</replaceable>; <replaceable>argument3</replaceable>) {<replaceable>handler</replaceable>}
+}
+</programlisting>	
+	</listitem>	
+</varlistentry>
+
+<!--<para>Each conditional statement must be enclosed in <command>{ }</command>.</para>-->
+<!--	
+<varlistentry>
+	<term></term>
+	<listitem>
+		<para></para>
+	</listitem>	
+</varlistentry>
+-->	
+	
+</variablelist>	
+	
+
+
+	</section>
 	<!--	<section id="SystemTap_Beginners_Guide-Test-Section_2_Test">
 		<title>Section 2 Test</title>
 		<para>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
index ebf71276..0e5b662d 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
@@ -70,6 +70,19 @@
 	</listitem>
 </varlistentry>
 
+<varlistentry>
+	<term>-x <replaceable>process ID</replaceable></term>
+	<listitem>
+		<para>Sets the SystemTap handler function <command>target()</command> to the specified process ID. For more information about <command>target()</command>, refer to <xref linkend="systemtapscript-handlers"/>.</para>
+	</listitem>	
+</varlistentry>
+
+<varlistentry>
+	<term>-c <replaceable>command</replaceable></term>
+	<listitem>
+		<para>Sets the SystemTap handler function <command>target()</command> to the specified command. Note that you must use the full path to the specified command; for example, instead of specifying <command>cp</command>, use <command>/bin/cp</command> (as in <command>stap <replaceable>script</replaceable> -c /bin/cp</command>). For more information about <command>target()</command>, refer to <xref linkend="systemtapscript-handlers"/>.</para>
+	</listitem>	
+</varlistentry>	
 <!--	
 <varlistentry>
 	<term></term>
-- 
cgit