added Arrays and other minor edits

4 files changed, 248 insertions, 170 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml
new file mode 100644
index 00000000..13122189
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml
@@ -0,0 +1,79 @@
+<?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="associativearrays">
+	<title>Associative Arrays</title>
+	
+<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a list of values arranged in tabular format. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it. Illustrating this visually would be similar to creating a two-column table: the first column would have the unique key, while the second column would have the associated value.</para>
+
+<para>Associative arrays are useful in processing data that would normally be represented best in tabular format. For example, let's say you wanted to see how many times <emphasis>any</emphasis> specific program performs a read to the virtual file system. In this case, your probe would use the event <command>kernel.function("vfs_read")</command>; <command>execname()</command> identifies which program or process performs the read.</para>
+	
+<formalpara id="simplesimplevfsread">
+	<title>vfsreads.stp</title>
+<para>
+<programlisting>
+probe kernel.function("vfs_read") 
+{

+	printf("%s\n", execname())

+}

+</programlisting>
+</para>
+</formalpara>
+
+<para><xref linkend="simplesimplevfsread"/> will display the name of each program that performs a read to the virtual file system <emphasis>as each read is performed</emphasis>. This means that the output of <xref linkend="simplesimplevfsread"/> will be a long list of process names, most of which will be repeating. For <xref linkend="simplesimplevfsread"/> to be useful, you'd need to feed its output to another program that counts how many times each process name appears and tally the results.</para>
+
+<para>However, with the help of arrays, you can simplify the task using the following script:</para>
+
+<formalpara id="arraysvfsread">
+	<title>vfsreads-using-arrays.stp</title>
+<para>
+<programlisting>
+global reads


+probe kernel.function("vfs_read")

+{

+	reads[execname()] += $count

+}

+probe timer.s(2)

+{

+	foreach (key in reads) 

+		printf("%s : %d\n", key, reads[key])

+	exit()

+}
+</programlisting>
+</para>
+</formalpara>
+
+<para>The handler in the first probe of <xref linkend="arraysvfsread"/> does three things:</para> 
+
+<orderedlist>
+	<listitem><para>First, the handler defines the variable <command>reads</command> as the associative array.</para></listitem>
+	<listitem><para>Next, the handler uses <command>execname()</command> (the names of the processes that execute the VFS reads) as the array's unique keys. For example, once the process <command>gnome-terminal</command> performs a VFS read, the array creates a unique key named <literal>gnome-terminal</literal>, which has an initial associated value of 1.</para></listitem>
+	<listitem><para>Finally, the statement <command>+= $count</command> increments the <emphasis>value associated with each unique key</emphasis> every time that unique key "occurs"; for example, each time that the process <command>gnome-terminal</command> performs a VFS read, the value associated with the unique key <literal>gnome-terminal</literal> gets incremented by 1.</para></listitem>
+</orderedlist>
+
+<note>
+	<title>Note</title>
+	<para>In <xref linkend="arraysvfsread"/>, <command>$count</command> is <emphasis>not</emphasis> a variable; rather, it is an operation that instructs the array to perform an increment to the array. This book will discuss other similar operations in detail later.</para>
+</note>
+
+<remark>TBD WILL ADD MORE INFO ON ARRAY SYNTAX IN A SUBSEQUENT SECTION, FIX PREVIOUS NOTE TO XREF TO SECTION ONCE ITS BUILT</remark>
+
+<para>The handler in the second probe of <xref linkend="arraysvfsread"/> prints the script's output o the format <computeroutput><replaceable>name</replaceable> : <replaceable>value</replaceable></computeroutput> over the span of two seconds, then exits. <computeroutput><replaceable>name</replaceable></computeroutput> is the process that executed a VFS read, and <computeroutput><replaceable>value</replaceable></computeroutput> is how many times <computeroutput><replaceable>name</replaceable></computeroutput> executed a VFS read). For example:</para> 
+
+<example id="arraysvfsreadoutput">
+	<title>Sample Output for <xref linkend="arraysvfsread"/></title>
+<screen>
+gnome-terminal : 64

+gnome-screensav : 128

+gnome-power-man : 512

+pcscd : 534

+cupsd : 1023

+mixer_applet2 : 1440

+gnome-vfs-daemo : 2048

+snmpd : 2048

+</screen>
+</example>
+
+
+</section>
\ No newline at end of file
diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
new file mode 100644
index 00000000..42054cb9
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
@@ -0,0 +1,165 @@
+<?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="scriptconstructions">
+<title>Basic SystemTap Handler Constructs</title>
+	
+	<para>SystemTap supports the use of several basic constructs in handlers. The syntax for most of these handler constructs are mostly based on C and <command>awk</command> syntax. This section describes several of the most useful SystemTap handler constructs, which should provide you with enough information to write simple yet useful SystemTap scripts.</para> 
+	
+<section 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>
+
+
+<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. Consider the following example:</para>
+
+<example id="timerjiffies">
+	<title>timer-jiffies.stp</title>
+<programlisting>
+global count_jiffies, count_ms
+probe timer.jiffies(100) { count_jiffies ++ }
+probe timer.ms(100) { count_ms ++ }
+probe timer.ms(12345)
+{
+  hz=(1000*count_jiffies) / count_ms
+  printf ("jiffies:ms ratio %d:%d => CONFIG_HZ=%d\n",
+    count_jiffies, count_ms, hz)
+  exit ()
+}
+</programlisting>
+</example>
+	
+<para><xref linkend="timerjiffies"/> attempts to compute the <command>CONFIG_HZ</command> setting of the kernel using timers that count jiffies and milliseconds, then computing accordingly. The <command>global</command> statement allows the script to use the variables <command>count_jiffies</command> and <command>count_ms</command> (set in their own respective probes) to be shared with <command>probe timer.ms(12345)</command>.</para>
+
+<note>
+	<title>Note</title>
+	<para>The <command>++</command> notation in <xref linkend="timerjiffies"/> (i.e. <command>count_jiffies ++</command> and <command>count_ms ++</command>) is used to increment the value of a variable by 1. In the following probe, <command>count_jiffies</command> is incremented by 1 every 100 jiffies:</para>
+<screen>
+probe timer.jiffies(100) { count_jiffies ++ }
+</screen>
+	<para>In this instance, SystemTap understands that <command>count_jiffies</command> is an integer. Because no initial value was assigned to <command>count_jiffies</command>, its initial value is zero by default.</para>   
+</note>	
+<!--
+<note>
+	<title>Note</title>
+	<para>In some cases, such as in <xref linkend="timerjiffies"/>, a variable may be declared without any specific value as yet. You need to declare such values as integers using the notation <command>++</command>.</para>
+</note>	
+	-->
+</section>
+<xi:include href="Arrays.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />	
+
+<section id="handlerconditionalstatements">
+	<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>statement</replaceable>} else {<replaceable>statement</replaceable>}
+</programlisting>
+
+<example id="simpleifelseexample">
+	<title>ifelse.stp</title>
+<programlisting>
+global countread, countnonread

+probe vfs.read,vfs.write

+{

+	if (probefunc()=="vfs_read") {

+	countread ++ }

+	else {countnonread ++}

+}

+probe timer.s(5) {

+	exit()}

+probe end {

+	printf("VFS reads total %d\n VFS writes total %d\n", countread, countnonread)} 

+</programlisting>
+</example>
+
+<para><xref linkend="simpleifelseexample"/> is a script that counts how many virtual file system reads (<command>vfs.read</command>) and writes (<command>vfs.write</command>) the system performs within a 5-second span. When run, the script increments the value of the variable <command>countread</command> by 1 if the name of the function it probed matches <command>vfs_read</command> (as noted by the condition <command>if (probefunc()=="vfs_read")</command>); otherwise, it increments <command>countnonread</command> (<command>else {countnonread ++}</command>).</para>
+
+	</listitem>	
+</varlistentry>	
+	
+<varlistentry>
+	<term>While Loops</term>
+	<listitem>
+		<para>Format:</para>
+<programlisting>
+while (<replaceable>condition</replaceable>) {<replaceable>statement</replaceable>}
+</programlisting>
+<!--
+<example id="simplewhileexample">
+	<title>while.stp</title>
+<programlisting>
+global foo

+probe timer.s(1) {

+foo ++

+while (foo&lt;6) {printf("hello world\n")}

+printf("goodbye world\n")

+</programlisting>
+</example>
+
+<para><xref linkend="simplewhileexample"/> is a script that prints <computeroutput>hello world</computeroutput> while less than 6 seconds has passed (<command>while (foo&lt;6)</command>). Once the <command>while</command> condition no longer applies, the script prints out <computeroutput>goodbye world</computeroutput>.</para>
+
+	--></listitem>	
+</varlistentry>	
+
+<varlistentry>
+	<term>For Loops</term>
+	<listitem>
+		<para>Format:</para>
+<programlisting>
+for (<replaceable>argument1</replaceable>; <replaceable>argument2</replaceable>; <replaceable>argument3</replaceable>) {<replaceable>statement</replaceable>}
+</programlisting>	
+	</listitem>	
+</varlistentry>
+
+<!--<para>Each conditional statement must be enclosed in <command>{ }</command>.</para>-->
+<!--	
+<varlistentry>
+	<term></term>
+	<listitem>
+		<para></para>
+	</listitem>	
+</varlistentry>
+-->	
+	
+</variablelist>	
+	
+<para>These constructs are better illustrated in the different examples available in <xref linkend="useful-systemtap-scripts"/>.</para>
+
+<remark>will get back to these ones later</remark>
+</section>
+<section id="commandlineargssect">
+	<title>Command-Line Arguments</title>
+	<para>You can also allow a SystemTap script to accept simple command-line arguments and declare them in the script without using <command>target()</command>. One way to do this is to use the variable notation <command>$</command> or <command>@</command>.</para>
+<!-- </formalpara> -->
+
+
+<example id="commandlineargs"><title>commandlineargs.stp</title>
+<programlisting>
+probe kernel.function(@1) { }
+probe kernel.function(@1).return { }
+</programlisting>	
+</example>	
+
+<para><xref linkend="commandlineargs"/> is similar to <xref linkend="wildcards"/>, except that it allows you to pass the kernel function to be probed as a command-line argument (as in <command>stap commandlineargs.stp <replaceable>kernel function</replaceable></command>). You can also specify the script to accept multiple command-line arguments, noting them as <command>@1</command>, <command>@2</command>, and so on, in the order they are entered by the user.</para>
+ 
+<para>Both variable notations <command>$</command> and <command>@</command> also represent a specific variable type. Use <command>$</command> if you are expecting the user to enter an integer as a command-line argument, and <command>@</command> if you are expecting a string.</para>  
+	</section>
+	
+<!-- endsection	 -->
+</section>
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index f35bb058..fad12dee 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -51,7 +51,7 @@ probe	<replaceable>event</replaceable>, {<replaceable>handler</replaceable>}
 	</para>
 </important>	
 	<section id="systemtapscript-events">
-		<title>Events</title>
+		<title>Event</title>
 	
 <para>SystemTap events can be broadly classified into two types: <firstterm>synchronous</firstterm> and <firstterm>asynchronous</firstterm>.</para>
 
@@ -215,7 +215,7 @@ probe timer.ms(4000)
 	</section>
 	
 	<section id="systemtapscript-handlers">
-		<title>Handlers/Probe Body</title>
+		<title>Handler/Probe Body</title>
 
 <para>
 Consider the following sample script:
@@ -304,7 +304,7 @@ hald(2360) open
 
 <formalpara>
 	<title>SystemTap Functions</title>	
-	<para>SystemTap supports a wide variety of functions that can be used as <command>printf ()</command> arguments. <xref linkend="syscall-open"/> uses the SystemTap functions <command>execname()</command> (current process name) and <command>pid()</command> (current process ID).</para>
+	<para>SystemTap supports a wide variety of functions that can be used as <command>printf ()</command> arguments. <xref linkend="syscall-open"/> uses the SystemTap functions <command>execname()</command> (name of the process that called a kernel function/performed a system call) and <command>pid()</command> (current process ID).</para>
 </formalpara>		
 
 <remark>is "handler function" an appropriate term? wcohen: use "SystemTap functions" to match up language in man pages</remark>
@@ -479,172 +479,5 @@ probe syscall.* {
 
 
 	</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 mostly based on C and <command>awk</command> syntax. This section describes several of the most useful SystemTap handler constructs.</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. Consider the following example:</para>
-
-<example id="timerjiffies">
-	<title>timer-jiffies.stp</title>
-<programlisting>
-global count_jiffies, count_ms
-probe timer.jiffies(100) { count_jiffies ++ }
-probe timer.ms(100) { count_ms ++ }
-probe timer.ms(12345)
-{
-  hz=(1000*count_jiffies) / count_ms
-  printf ("jiffies:ms ratio %d:%d => CONFIG_HZ=%d\n",
-    count_jiffies, count_ms, hz)
-  exit ()
-}
-</programlisting>
-</example>
-	
-<para><xref linkend="timerjiffies"/> attempts to compute the <command>CONFIG_HZ</command> setting of the kernel using timers that count jiffies and milliseconds, then computing accordingly. The <command>global</command> statement allows the script to use the variables <command>count_jiffies</command> and <command>count_ms</command> (set in their own respective probes) to be shared with <command>probe timer.ms(12345)</command>.</para>
-
-<note>
-	<title>Note</title>
-	<para>The <command>++</command> notation in <xref linkend="timerjiffies"/> (i.e. <command>count_jiffies ++</command> and <command>count_ms ++</command>) is used to increment the value of a variable by 1. In the following probe, <command>count_jiffies</command> is incremented by 1 every 100 jiffies:</para>
-<screen>
-probe timer.jiffies(100) { count_jiffies ++ }
-</screen>
-	<para>In this instance, SystemTap understands that <command>count_jiffies</command> is an integer. Because no initial value was assigned to <command>count_jiffies</command>, its initial value is zero by default.</para>   
-</note>	
-	
-	
-
-<!--
-<note>
-	<title>Note</title>
-	<para>In some cases, such as in <xref linkend="timerjiffies"/>, a variable may be declared without any specific value as yet. You need to declare such values as integers using the notation <command>++</command>.</para>
-</note>	
-	-->
-	
-
 
-<section id="handlerconditionalstatements">
-	<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>
-
-<example id="simpleifelseexample">
-	<title>ifelse.stp</title>
-<programlisting>
-global countread, countnonread

-probe vfs.read,vfs.write

-{

-	if (probefunc()=="vfs_read") {

-	countread ++ }

-	else {countnonread ++}

-}

-probe timer.s(5) {

-	exit()}

-probe end {

-	printf("VFS reads total %d\n VFS writes total %d\n", countread, countnonread)} 

-</programlisting>
-</example>
-
-<para><xref linkend="simpleifelseexample"/> is a script that counts how many virtual file system reads (<command>vfs.read</command>) and writes (<command>vfs.write</command>) the system performs within a 5-second span. When run, the script increments the value of the variable <command>countread</command> by 1 if the name of the function it probed matches <command>vfs_read</command> (as noted by the condition <command>if (probefunc()=="vfs_read")</command>); otherwise, it increments <command>countnonread</command> (<command>else {countnonread ++}</command>).</para>
-
-	</listitem>	
-</varlistentry>	
-	
-<varlistentry>
-	<term>While Loops</term>
-	<listitem>
-		<para>Format:</para>
-<programlisting>
-while (<replaceable>condition</replaceable>) {<replaceable>handler</replaceable>}
-</programlisting>
-<!--
-<example id="simplewhileexample">
-	<title>while.stp</title>
-<programlisting>
-global foo

-probe timer.s(1) {

-foo ++

-while (foo&lt;6) {printf("hello world\n")}

-printf("goodbye world\n")

-</programlisting>
-</example>
-
-<para><xref linkend="simplewhileexample"/> is a script that prints <computeroutput>hello world</computeroutput> while less than 6 seconds has passed (<command>while (foo&lt;6)</command>). Once the <command>while</command> condition no longer applies, the script prints out <computeroutput>goodbye world</computeroutput>.</para>
-
-	--></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>	
-	
-<para>These constructs are better illustrated in the different examples available in <xref linkend="useful-systemtap-scripts"/>.</para>
-
-<remark>will get back to these ones later</remark>
-</section>
-<section id="commandlineargssect">
-	<title>Command-Line Arguments</title>
-	<para>You can also allow a SystemTap script to accept simple command-line arguments and declare them in the script without using <command>target()</command>. One way to do this is to use the variable notation <command>$</command> or <command>@</command>.</para>
-<!-- </formalpara> -->
-
-
-<example id="commandlineargs"><title>commandlineargs.stp</title>
-<programlisting>
-probe kernel.function(@1) { }
-probe kernel.function(@1).return { }
-</programlisting>	
-</example>	
-
-<para><xref linkend="commandlineargs"/> is similar to <xref linkend="wildcards"/>, except that it allows you to pass the kernel function to be probed as a command-line argument (as in <command>stap commandlineargs.stp <replaceable>kernel function</replaceable></command>). You can also specify the script to accept multiple command-line arguments, noting them as <command>@1</command>, <command>@2</command>, and so on, in the order they are entered by the user.</para>
- 
-<para>Both variable notations <command>$</command> and <command>@</command> also represent a specific variable type. Use <command>$</command> if you are expecting the user to enter an integer as a command-line argument, and <command>@</command> if you are expecting a string.</para>  
-	</section>
-	<!--	<section id="SystemTap_Beginners_Guide-Test-Section_2_Test">
-		<title>Section 2 Test</title>
-		<para>
-			Test of a section
-		</para>
-	</section>-->
-
-</section>
 </section>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
index 8dd1b803..81926b34 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
@@ -52,6 +52,7 @@
 
 </section>
 <xi:include href="Scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="ScriptConstructs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <!--	
 	<section id="understanding-scripts">
 		<title>SystemTap Scripts</title>