Edits to Scripts.xml and ScriptConstructs.xml.

2 files changed, 97 insertions, 45 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
index e0917280..a139015d 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
@@ -61,7 +61,8 @@
 	<secondary>SystemTap handler constructs</secondary>
 	<tertiary>handlers</tertiary>
 </indexterm>
-	<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>Variables can be used freely throughout a handler; simply choose a
+name, assign a value from a function or expression to it, and use it in an expression. SystemTap automatically identifies whether a variable should be typed as a string or integer, based on the type of the values assigned to it. 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> is typed as an number and can be printed in a <command>printf()</command> with the integer format specifier (<command>%d</command>).</para>
 
 <!-- next 2 indexterms for <command>global</command> -->
 
@@ -82,7 +83,7 @@
 <secondary>SystemTap handler constructs</secondary>
 <tertiary>handlers</tertiary>
 </indexterm>
-<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>
+<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 using <command>global</command> outside of the probes. Consider the following example:</para>
 
 <example id="timerjiffies">
 	<title>timer-jiffies.stp</title>
@@ -104,7 +105,7 @@ probe timer.ms(12345)
 <primary><command>CONFIG_HZ, computing for</command></primary>
 </indexterm>
 	
-<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>
+<para><xref linkend="timerjiffies"/> computes 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>
@@ -165,25 +166,38 @@ You can do this by using <emphasis>conditionals</emphasis> in handlers. SystemTa
 
 		<para>Format:</para>
 <programlisting>
-if (<replaceable>condition</replaceable>) 
-	{<replaceable>statement</replaceable>} else {<replaceable>statement</replaceable>}
+if (<replaceable>condition</replaceable>)
+  <replaceable>statement1</replaceable>
+else
+  <replaceable>statement2</replaceable>
 </programlisting>
 
+<para>
+The <command><replaceable>statement1</replaceable></command> is executed if the
+<command><replaceable>condition</replaceable></command> expression is
+non-zero. The <command><replaceable>statement2</replaceable></command> is
+executed if the <command><replaceable>condition</replaceable></command>
+expression is zero. The <command>else</command> is optional. Both
+<command><replaceable>statement1</replaceable></command> and
+<command><replaceable>statement2</replaceable></command> can be statement
+blocks.
+</para>
+
 <example id="simpleifelseexample">
 	<title>ifelse.stp</title>
 <programlisting>
 global countread, countnonread
 probe kernel.function("vfs_read"),kernel.function("vfs_write")
 {
-	if (probefunc()=="vfs_read") 
-		countread ++ 
-	else 
-		countnonread ++
+  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)
+  printf("VFS reads total %d\n VFS writes total %d\n", countread, countnonread)
 }
 </programlisting>
 </example>
@@ -217,8 +231,17 @@ probe end
 </indexterm>
 		<para>Format:</para>
 <programlisting>
-while (<replaceable>condition</replaceable>) {<replaceable>statement</replaceable>}
+while (<replaceable>condition</replaceable>)
+  <replaceable>statement</replaceable>
 </programlisting>
+<para>
+So long as <command><replaceable>condition</replaceable></command> is non-zero
+the block of statements in
+<command><replaceable>statement</replaceable></command> are executed. The
+<command><replaceable>statement</replaceable></command> is often a statement
+block and it must change a value so
+<command><replaceable>condition</replaceable></command> will eventually be zero.
+</para>
 <!--
 <example id="simplewhileexample">
 	<title>while.stp</title>
@@ -260,9 +283,20 @@ printf("goodbye world\n")
 </indexterm>		
 		<para>Format:</para>
 <programlisting>
-for (<replaceable>argument1</replaceable>; <replaceable>argument2</replaceable>; <replaceable>argument3</replaceable>) {<replaceable>statement</replaceable>}
-</programlisting>	
-	</listitem>	
+for (<replaceable>initialization</replaceable>; <replaceable>conditional</replaceable>; <replaceable>increment</replaceable>) <replaceable>statement</replaceable>
+</programlisting>
+<para>
+The <command>for</command> loop is simply shorthand for a while loop. The
+following is the equivalent <command>while</command> loop:
+</para>
+<programlisting>
+<replaceable>initialization</replaceable>
+while (<replaceable>conditional</replaceable>) {
+   <replaceable>statement</replaceable>
+   <replaceable>increment</replaceable>
+}
+</programlisting>
+	</listitem>
 </varlistentry>
 
 <!--<para>Each conditional statement must be enclosed in <command>{ }</command>.</para>-->
@@ -350,7 +384,9 @@ for (<replaceable>argument1</replaceable>; <replaceable>argument2</replaceable>;
 <secondary>SystemTap handler constructs</secondary>
 <tertiary>handlers</tertiary>
 </indexterm>	
-	<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>
+	<para>You can also allow a SystemTap script to accept simple command-line arguments using a  <command>$</command> or <command>@</command> immediately
+followed by the number of the argument on the command line. 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>
 <!-- </formalpara> -->
 
 
@@ -381,7 +417,6 @@ probe kernel.function(@1).return { }
 <secondary>SystemTap handler constructs</secondary>
 <tertiary>handlers</tertiary>
 </indexterm>
-<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	 -->
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index e6ffc4ef..a0fc7d52 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -159,18 +159,16 @@ probe	<replaceable>event</replaceable> {<replaceable>statements</replaceable>}
 </indexterm>
   <para>
 	Each probe has a corresponding <firstterm>statement block</firstterm>. This statement block is 
-	enclosed in braces (<command>{ }</command>) and contains the handlers to be executed per event. 
-	SystemTap executes these handlers (i.e. "statements") in sequence; special separators or 
-	terminators are generally not necessary between multiple handlers.
+	enclosed in braces (<command>{ }</command>) and contains the statements to be executed per event. 
+	SystemTap executes these statements in sequence; special separators or 
+	terminators are generally not necessary between multiple statements.
   </para>
 
 <note>
 	<title>Note</title>
 	<para>
 		Statement blocks in SystemTap scripts follow the same syntax and semantics as the C 
-		programming language. A statement block can also nest another statement block, although 
-		for the most part this is used only to organize code in the script for the benefit of the 
-		administrator.
+		programming language. A statement block can be nested within another statement block.
   	</para>
 </note>	
 <indexterm>
@@ -247,7 +245,7 @@ probe <replaceable>event</replaceable> {<replaceable>function_name</replaceable>
 </indexterm>
       <para>
 	A <firstterm>synchronous</firstterm> event occurs when any process
-	executes an instruction that references a particular location in kernel
+	executes an instruction at a particular location in kernel
 	code. This gives other events a reference point from which more
 	contextual data may be available.
       </para>
@@ -351,7 +349,7 @@ probe <replaceable>event</replaceable> {<replaceable>function_name</replaceable>
 	<primary>events wildcards</primary>
 </indexterm>
 	  <para>
-	    When defining functions, you can use asterisk (<literal>*</literal>)
+	    When defining probe events, 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>
@@ -364,14 +362,15 @@ probe kernel.function("*@net/socket.c").return { }
 </programlisting>	
 </example>
 
-	  <remark>Wild cards also work for other things, e.g. syscall.*</remark>
+	  <remark>Wild cards also work for other types of events, e.g. syscall.*</remark>
 
 	  <para>
 	    In the previous example, the first probe's event specifies the entry
 	    of ALL functions in the kernel source file
 	    <filename>net/socket.c</filename>. The second probe specifies the
-	    exit of all those functions. Note that in this example, no handler
-	    was specified; as such, no information will be displayed.
+	    exit of all those functions. Note that in this example, 
+	    there are no statements in the handler;
+	    as such, no information will be collected or displayed.
 	  </para>
 	</listitem>
 
@@ -399,11 +398,19 @@ probe module("ext3").function("*").return { }
 </example>
 		
 		<para>
-			The first probe in <xref linkend="eventsmodules"/> points to the entry of <emphasis>all</emphasis> functions for the <filename>ext3</filename> module. The second probe points to the exits of all entries for that same module; the use of the <command>.return</command> suffix is similar to <command>kernel.function()</command>. Note that the probes in <xref linkend="eventsmodules"/> also do not contain probe bodies, and as such will not print any useful data (as in <xref linkend="wildcards"/>). 
-		</para>	
+			The first probe in <xref linkend="eventsmodules"/>
+		points to the entry of <emphasis>all</emphasis> functions for
+		the <filename>ext3</filename> module. The second probe points to
+		the exits of all functions for that same module; the use of the
+		<command>.return</command> suffix is similar to
+		<command>kernel.function()</command>. Note that the probes in
+		<xref linkend="eventsmodules"/> do not contain statements
+		in the probe handlers, and as such will not print any useful
+		data (as in <xref linkend="wildcards"/>).
+	        </para>
 		
 		<para>
-			A system's loaded modules are typically located in <filename>/lib/modules/<replaceable>kernel version</replaceable></filename>, where <replaceable>kernel version</replaceable> refers to the currently loaded kernel. Modules use the filename extension <filename>.ko</filename>. 
+			A system's kernel modules are typically located in <filename>/lib/modules/<replaceable>kernel_version</replaceable></filename>, where <replaceable>kernel_version</replaceable> refers to the currently loaded kernel version. Modules use the filename extension <filename>.ko</filename>. 
 		</para>	
 		
 	</listitem>
@@ -482,8 +489,8 @@ probe module("ext3").function("*").return { }
 </indexterm>
 
 	  <para>
-	    An event that specifies a handler to be executed every specified
-	    period of time. For example:
+	    An event that specifies a handler to be executed periodically.
+	    For example:
 	  </para>
 		
 <example id="timer"><title>timer-s.stp</title>
@@ -601,7 +608,7 @@ probe begin
 
 
 <programlisting>
-printf ("<replaceable>format string</replaceable>\n", <replaceable>argument</replaceable>)
+printf ("<replaceable>format string</replaceable>\n", <replaceable>arguments</replaceable>)
 </programlisting>
 <indexterm>
 <primary><command>printf()</command></primary>
@@ -614,7 +621,7 @@ printf ("<replaceable>format string</replaceable>\n", <replaceable>argument</rep
 </indexterm>
     <para>
 	The <replaceable>format string</replaceable> specifies how
-	<replaceable>argument</replaceable> should be printed. The format string
+	<replaceable>arguments</replaceable> should be printed. The format string
 	of <xref linkend="helloworld"/> simply instructs SystemTap to print
 	<command>hello world</command>, and contains no format specifiers.
     </para>
@@ -672,8 +679,8 @@ probe syscall.open
     <para>
       <xref linkend="syscall-open"/> instructs SystemTap to probe all entries to
       the system call <command>open</command>; for each event, it prints the
-      current <command>execname()</command> (which is a string) and
-      <command>pid()</command> (which is a number), followed by the word
+      current <command>execname()</command> (a string with the executable name) and
+      <command>pid()</command> (the current process ID number), followed by the word
       <command>open</command>. A snippet of this probe's output would look like:
     </para>
 
@@ -827,6 +834,15 @@ hald(2360) open
 		<para>The number of seconds since UNIX epoch (January 1, 1970).</para>
 	</listitem>	
 </varlistentry>
+
+<varlistentry>
+	<term>ctime()</term>
+	<listitem>
+		<para>
+	Convert number of seconds since UNIX epoch to date.</para>
+	</listitem>	
+</varlistentry>
+
 <!--
 <varlistentry>
 	<term>get_cycles()</term>
@@ -890,18 +906,19 @@ hald(2360) open
 </indexterm>
 	<para>
 	    This particular function is quite useful, providing you with a way
-	    to better organize your print results. When used with an indentation
-	    parameter (for example, <command>-1</command>), it allows the probe
-	    to internally store an "indentation counter" for each thread
-	    (identified by ID, as in <command>tid</command>). It then returns a
+	    to better organize your print results. The function takes one
+	    argument, an indentation delta, which indicates how many
+	    spaces to add or remove from a thread's "indentation counter".
+	    It then returns a
 	    string with some generic trace data along with an appropriate number
 	    of indentation spaces.
 	  </para>
 		
 	  <para>
 	    The generic data included in the returned string includes a
-	    timestamp (number of microseconds since the most recent initial
-	    indentation), a process name, and the thread ID. This allows you to
+	    timestamp (number of microseconds since the 
+	    first call to <command>thread_indent()</command> by the thread),
+	    a process name, and the thread ID. This allows you to
 	    identify what functions were called, who called them, and the
 	    duration of each function call.
 	  </para>	
@@ -960,9 +977,9 @@ probe kernel.function("*@net/socket.c").return
 <para>This sample output contains the following information:</para>
 
 <itemizedlist>
-	<listitem><para>The time delta (in microseconds) since the previous entry; i.e. the number of microseconds since the last traced function call.</para></listitem>
+	<listitem><para>The time (in microseconds) since the initial <command>thread_ident()</command> call for the thread (included in the string from <command>thread_ident()</command>).</para></listitem>
 	
-	<listitem><para>The process name (and its corresponding ID) that made the function call.</para></listitem>
+	<listitem><para>The process name (and its corresponding ID) that made the function call (included in the string from <command>thread_ident()</command>).</para></listitem>
 	
 	<listitem><para>An arrow signifying whether the call was an entry (<computeroutput>&lt;-</computeroutput>) or an exit (<computeroutput>-></computeroutput>); the indentations help you match specific function call entries with their corresponding exits.</para></listitem>
 	
@@ -995,7 +1012,7 @@ that thread_indent is defined in tapsets as a special function of sorts</remark>
 <secondary>Handlers</secondary>
 <tertiary>handler functions</tertiary>
 </indexterm>
-	  <para>Identifies the name of a specific system call. This function can
+	  <para>Identifies the name of a specific system call. This variable can
 	  only be used in probes that use the event
 	  <command>syscall.<replaceable>system_call</replaceable></command>.
 	  </para>