more edits as per wcohen

6 files changed, 85 insertions, 50 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
index f428f5e5..b0d712bd 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
@@ -128,9 +128,9 @@ enabled=1
 <para><command>staprun <replaceable>instrumentation</replaceable></command></para>
 
 <para>
-	For example, to create the <emphasis>instrumentation module</emphasis> <filename>simple.ko</filename> from the SystemTap script <xref linkend="simplesimplescript"/> (from <xref linkend="installproper"/>) for the <emphasis>target kernel</emphasis> 2.6.25.9-76.fc9 (on i686 architecture), use the following command:
+	For example, to create the <emphasis>instrumentation module</emphasis> <filename>simple.ko</filename> from a SystemTap script named <filename>simple.stp</filename> for the <emphasis>target kernel</emphasis> 2.6.25.9-76.fc9 (on i686 architecture), use the following command:
 </para>
-
+	
 <para><command>stap -r 2.6.25.9-76.fc9.x86_64 simple.stp -m module</command></para>
 
 <para>This will create a module named <filename>simple.ko</filename>. To use the <emphasis>instrumentation module</emphasis> <filename>simple.ko</filename>, copy it to the <emphasis>target system</emphasis> and run the following command (on the <emphasis>target system</emphasis>):</para>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
index f9c9a819..1bde952e 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
@@ -136,18 +136,7 @@ As mentioned earlier in <xref linkend="using-setup"/>, <filename>kernel-debuginf
 <para>If you are currently using the kernel you wish to probe with SystemTap, you can immediately test whether the deployment was successful. If not, you will need to reboot and load the appropriate kernel.</para>
 </formalpara>
 
-<para>To start the test, create the following SystemTap script (ensure that you are using the filename extension <filename>.stp</filename>):</para>
-
-<formalpara id="simplesimplescript">
-	<title>simple.stp</title>
-<para>
-<programlisting>
-probe kernel.function("vfs_read") {exit()}

-</programlisting>
-</para>
-</formalpara>
-
-<para><xref linkend="simplesimplescript"/> is a SystemTap script that simply exits the first time it detects a virtual file system read. If the SystemTap deployment was successful, you should get the following verbose output:</para>
+<para>To start the test, run the command <command>stap -v -e 'probe vfs.read {exit()}</command>. This command simply instructs SystemTap to exit properly once a virtual file system read is detected. If the SystemTap deployment was successful, you should get the following verbose output:</para>
 
 <screen>
 Pass 1: parsed user script and 55 library script(s) in 340usr/10sys/380real ms.

@@ -159,7 +148,7 @@ Pass 5: run completed in 40usr/210sys/260real ms.
 </screen>
 
 <para>
-	The last two lines of the output (i.e. beginning with <computeroutput>Pass 5</computeroutput> indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, detect the event being probed (in the case of <xref linkend="simplesimplescript"/>, a virtual file system read), and close it with no errors.
+	The last two lines of the output (i.e. beginning with <computeroutput>Pass 5</computeroutput> indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, detect the event being probed (in this case, a virtual file system read), and close it with no errors.
 </para>	
 
 <!--</step>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index 2c69057b..f35bb058 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -530,7 +530,7 @@ probe timer.jiffies(100) { count_jiffies ++ }
 	
 
 
-<section>
+<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.
@@ -553,17 +553,22 @@ if (<replaceable>condition</replaceable>)
 <example id="simpleifelseexample">
 	<title>ifelse.stp</title>
 <programlisting>
-global foo

-probe begin { foo = 1 }

-probe timer.s(1) { 

-foo++

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

-else {printf("goodbye world\n")}

+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 prints <computeroutput>hello world</computeroutput> if less than 6 seconds has passed. If more than 6 seconds have passed, it prints <computeroutput>goodbye world</computeroutput> instead.</para>
+<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>	
 	
@@ -573,8 +578,22 @@ else {printf("goodbye world\n")}
 		<para>Format:</para>
 <programlisting>
 while (<replaceable>condition</replaceable>) {<replaceable>handler</replaceable>}
-</programlisting>	
-	</listitem>	
+</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>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml b/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml
index b69e00df..1a55010b 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml
@@ -13,7 +13,7 @@
 <!-- 	<xi:include href="Useful_Advanced_Scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
 	<xi:include href="Errors.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Tips_Tricks.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-	<xi:include href="References.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="References.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
 	<!-- 	
 		<xi:include href="" xmlns:xi="http://www.w3.org/2001/XInclude" /> 
 	-->
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml
index b1d3f846..331f49a6 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml
@@ -30,7 +30,7 @@ probe netdev.transmit
         execname[p] = execname()
         user[p] = uid()
         ifdevs[p, dev_name] = dev_name
-	ifxmit[p, dev_name] &lt;&lt;&lt; length
+        ifxmit[p, dev_name] &lt;&lt;&lt; length
         ifpid[p, dev_name] ++
 }
 
@@ -40,7 +40,7 @@ probe netdev.receive
         execname[p] = execname()
         user[p] = uid()
         ifdevs[p, dev_name] = dev_name
-	ifrecv[p, dev_name] &lt;&lt;&lt; length
+        ifrecv[p, dev_name] &lt;&lt;&lt; length
         ifpid[p, dev_name] ++
 }
 
@@ -100,28 +100,28 @@ probe timer.ms(5000)
 	<title><xref linkend="nettop"/> Sample Output</title>
 <screen>
 [...]
-  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        

-    0     0 eth0          0       5       0       0 swapper        

-11178     0 eth0          2       0       0       0 synergyc       

-

-  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        

- 2886     4 eth0         79       0       5       0 cups-polld     

-11362     0 eth0          0      61       0       5 firefox        

-    0     0 eth0          3      32       0       3 swapper        

- 2886     4 lo            4       4       0       0 cups-polld     

-11178     0 eth0          3       0       0       0 synergyc       

-

-  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        

-    0     0 eth0          0       6       0       0 swapper        

- 2886     4 lo            2       2       0       0 cups-polld     

-11178     0 eth0          3       0       0       0 synergyc       

- 3611     0 eth0          0       1       0       0 Xorg           

-

-  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        

-    0     0 eth0          3      42       0       2 swapper        

-11178     0 eth0         43       1       3       0 synergyc       

-11362     0 eth0          0       7       0       0 firefox        

- 3897     0 eth0          0       1       0       0 multiload-apple

+  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        
+    0     0 eth0          0       5       0       0 swapper        
+11178     0 eth0          2       0       0       0 synergyc       
+
+  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        
+ 2886     4 eth0         79       0       5       0 cups-polld     
+11362     0 eth0          0      61       0       5 firefox        
+    0     0 eth0          3      32       0       3 swapper        
+ 2886     4 lo            4       4       0       0 cups-polld     
+11178     0 eth0          3       0       0       0 synergyc       
+
+  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        
+    0     0 eth0          0       6       0       0 swapper        
+ 2886     4 lo            2       2       0       0 cups-polld     
+11178     0 eth0          3       0       0       0 synergyc       
+ 3611     0 eth0          0       1       0       0 Xorg           
+
+  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        
+    0     0 eth0          3      42       0       2 swapper        
+11178     0 eth0         43       1       3       0 synergyc       
+11362     0 eth0          0       7       0       0 firefox        
+ 3897     0 eth0          0       1       0       0 multiload-apple
 [...]
 </screen>
 </example>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
index 43105edf..447f3d62 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
@@ -117,6 +117,33 @@ echo "probe timer.s(1) {exit()}" | stap -
 	<para>The <command>stap</command> options <command>-v</command> and <command>-o</command> also work for <command>staprun</command>. For more information about <command>staprun</command>, refer to <command>man staprun</command>.</para>
 </note>	
 
+<formalpara>
+	<title>stapdev and stapusr</title>
+	<para>Running <command>stap</command> and <command>staprun</command> requires elevated privileges to the system. However, not all users can be granted root access just to run SystemTap. In some cases, for instance, you may want to allow a non-privileged user to run SystemTap instrumentation on his machine.</para>
+</formalpara>
+
+<para>To allow ordinary users to run SystemTap without root access, add them to one of these user groups:</para>
+
+<variablelist>
+	
+<varlistentry>
+	<term>stapdev</term>
+	<listitem>
+<para>
+	Members of this group can use <command>stap</command> to run SystemTap scripts, or <command>staprun</command> to run SystemTap instrumentation modules.
+</para>
+	</listitem>
+</varlistentry>
+
+<varlistentry>
+	<term>stapusr</term>
+	<listitem>
+<para>
+	Members of this group can only run <command>staprun</command> to run SystemTap instrumentation modules. In addition, they can only run those modules from <filename>/lib/modules/<replaceable>kernel_version</replaceable>/systemtap/</filename>. Note that this directory must be owned only by the root user, and must only be writable by the root user.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
 	</section>
 
 </chapter>