Merge branch 'master' of ssh://sources.redhat.com/git/systemtap

* 'master' of ssh://sources.redhat.com/git/systemtap:
  added Handlers description, more cleanup
  Ensure that "stap -l ..." only prints probe names, not variables.

5 files changed, 189 insertions, 13 deletions

diff --git a/ChangeLog b/ChangeLog
index ae88d653..2329f1c0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2008-09-10  Josh Stone  <joshua.i.stone@intel.com>
+
+	* main.cxx (printscript): Ensure no variables are printed in probe lists
+	unless -L was specified.
+
 2008-09-10  Frank Ch. Eigler  <fche@elastic.org>
 
 	* parse.cxx, parse.h: Rewrite scanner lookahead data structure
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index 24ab8a83..d61ec1cf 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -32,7 +32,7 @@
 		SystemTap scripts use the file extension <filename>.stp</filename>, and are written in the following format:
 	</para>
 </formalpara>	
-<screen>
+<programlisting>
 probe	<replaceable>[event]</replaceable>,
 <replaceable>[another event]</replaceable>
 
@@ -41,7 +41,7 @@ probe	<replaceable>[event]</replaceable>,
 
 	exit()
 }
-</screen>		
+</programlisting>		
 	<para>The <replaceable>exit()</replaceable> condition is optional, but it is recommended since it safely terminates the session once the script successfully traps the required information.</para>	
 	
 <important>
@@ -108,17 +108,164 @@ probe kernel.function("*@net/socket.c").return { }
 	
 </variablelist>
 
-
+<important>
+	<title>Important</title>
+	<para>
+	SystemTap supports the use of a large collection of probe events. For more information about supported events, refer to <command>man stapprobes</command>. The <citetitle>SEE ALSO</citetitle> section of <command>man stapprobes</command> also contains links to other <command>man</command> pages that discuss supported events for specific subsystems and components.
+	</para>	
+</important>
 	</section>
 	
 	<section id="systemtapscript-handlers">
 		<title>Handlers</title>
 
 <para>
-	SystemTap supports a wide variety of functions that can trap data when triggered by events. One way to display these functions is to use the <command>print()</command>   
+Consider the following sample script:
+</para>
+
+<example id="helloworld"><title>Hello World</title>
+<programlisting>
+probe begin
+{
+  printf ("hello world\n")
+  exit ()
+}
+</programlisting>	
+</example>
+
+<para>
+	In <xref linkend="helloworld"/>, the event <command>begin</command> (i.e. the start of the session) triggers the handler enclosed in <command>{ }</command>, which simply prints <command>hello world</command>, then exits.
+</para>	
+
+<formalpara id="printf">
+	<title>printf ( ) Statements</title>
+<para>
+	The <command>printf ()</command> statement is one of the simplest handler tools for printing data. <command>printf ()</command> can also be used to trap data using a wide variety of SystemTap handler functions using the following format:
+</para>
+</formalpara>
+
+<programlisting>
+printf ("<replaceable>[format string]</replaceable>\n", <replaceable>[argument]</replaceable>)
+</programlisting>
+
+<para>
+	The <replaceable>[format string]</replaceable> region specifies how <replaceable>[argument]</replaceable> should be displayed. The format string of <xref linkend="helloworld"/> simply instructs SystemTap to print <command>hello world</command>, and contains no arguments. 
+</para>
+
+<para>
+	You can use the variables <command>%s</command> (for strings) and <command>%d</command> (for numbers) in format strings, depending on your list of arguments. Format strings can have multiple variables, each matching a corresponding argument; multiple arguments are delimited by a comma (<command>,</command>) and space.
+</para>
+
+<para>
+	To illustrate this, consider the following probe example:
+</para>
+
+<example id="syscall-open">
+	<title>Using Variables In printf ( ) Statements</title>
+<programlisting>
+# This probe will need to be manually terminated with Ctrl-C
+probe syscall.open

+{

+  printf ("%s(%d) open\n", execname(), pid())

+}
	
+</programlisting>	
+</example>
+
+<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 <command>open</command>. A snippet of this probe's output would look like:
+</para>
+
+<screen>
+vmware-guestd(2206) open
+hald(2360) open
+hald(2360) open
+hald(2360) open
+df(3433) open
+df(3433) open
+df(3433) open
+hald(2360) open
+</screen>
+
+<formalpara>
+	<title>Handler Functions</title>
+	<para>SystemTap supports a wide variety of handler functions that can be used as <command>printf ()</command> arguments. <xref linkend="syscall-open"/> uses the handler functions <command>execname()</command> (current process name) and <command>pid()</command> (current process ID).</para>
+</formalpara>		
+	<para>The following is a list of commonly-used handler functions:</para>
+	
+<variablelist>
+
+<varlistentry>
+	<term>tid()</term>
+	<listitem>
+		<para>The ID of the current thread.</para>
+	</listitem>	
+</varlistentry>	
+
+<varlistentry>
+	<term>uid()</term>
+	<listitem>
+		<para>The ID of the current user.</para>
+	</listitem>	
+</varlistentry>
+
+<varlistentry>
+	<term>cpu()</term>
+	<listitem>
+		<para>The current CPU number.</para>
+	</listitem>	
+</varlistentry>
+
+<varlistentry>
+	<term>gettimeofday_s()</term>
+	<listitem>
+		<para>The number of seconds since UNIX epoch (January 1, 1970).</para>
+	</listitem>	
+</varlistentry>
+
+<varlistentry>
+	<term>get_cycles()</term>
+	<listitem>
+		<para>A snapshot of the hardware cycle counter.</para>
+	</listitem>	
+</varlistentry>
+
+<varlistentry>
+	<term>pp()</term>
+	<listitem>
+		<para>A string describing the probe point currently being handled.</para>
+	</listitem>	
+</varlistentry>
+
+<varlistentry>
+	<term>probefunc()</term>
+	<listitem>
+		<para>If known, the name of the function in which the probe was placed.</para>
+	</listitem>	
+</varlistentry>
+<!--	
+<varlistentry>
+	<term></term>
+	<listitem>
+		<para></para>
+	</listitem>	
+</varlistentry>
+-->	
+</variablelist>		
+
+<para>For more information about supported handler functions, refer to <command>man stapfuncs</command>.</para>
+
+
+<!--	
+<para>
+	<replaceable>[variable]</replaceable> can be either <command>%s</command> for strings, or <command>%d</command> for numbers, depending on the <replaceable>[handler function]</replaceable> used. Each <command>printf ()</command> statement can contain multiple <replaceable>[variable]</replaceable>s, with each one corresponding to a matching <replaceable>[handler function]</replaceable>. Multiple <replaceable>[handler function]</replaceable>s are delimited by comma (<command>,</command>). 
 </para>	
+
+	<command>printf ()</command> is a SystemTap-supported C statement, and can also trap data using a wide variety
+	
+	SystemTap supports a wide variety of handler functions that can trap data when triggered by events. One way to display these functions is to use the <command>print()</command>   
+</para>	
+		
 		
-<!--		
 <para>
 	<xref linkend="wildcards"/> illustrates an example of a SystemTap script that contains no handlers. SystemTap will still be able to run the script, but no information will be displayed. 	
 </para>
diff --git a/main.cxx b/main.cxx
index 634feb03..563e4b01 100644
--- a/main.cxx
+++ b/main.cxx
@@ -182,14 +182,15 @@ printscript(systemtap_session& s, ostream& o)
           if (seen.find (pp) == seen.end())
             {
               o << pp;
-              // This list will be empty unless s.unoptimized = true -- i.e., -L mode
-              for (unsigned j=0; j<p->locals.size(); j++)
-	            {
-      		      o << " ";
-                      vardecl* v = p->locals[j];
-		      v->printsig (o);
-		    }
-	      o << endl;
+              // Print the locals for -L mode only
+              if (s.unoptimized)
+                for (unsigned j=0; j<p->locals.size(); j++)
+                  {
+                    o << " ";
+                    vardecl* v = p->locals[j];
+                    v->printsig (o);
+                  }
+              o << endl;
               seen.insert (pp);
             }
         }
diff --git a/testsuite/ChangeLog b/testsuite/ChangeLog
index 3effc92f..288705b1 100644
--- a/testsuite/ChangeLog
+++ b/testsuite/ChangeLog
@@ -1,3 +1,7 @@
+2008-09-10  Josh Stone  <joshua.i.stone@intel.com>
+
+	* systemtap.base/probe_list.exp: New test for correct probe listing.
+
 2008-09-09  Frank Ch. Eigler  <fche@elastic.org>
 
 	* systemtap.base/uprobes.*: Tweak regexps for read-only src tree
diff --git a/testsuite/systemtap.base/probe_list.exp b/testsuite/systemtap.base/probe_list.exp
new file mode 100644
index 00000000..b3e6884b
--- /dev/null
+++ b/testsuite/systemtap.base/probe_list.exp
@@ -0,0 +1,19 @@
+# This test ensures that "-l" lists only include probe names, and not any of
+# the local variables.  There was a bug that "-l" would print variables that
+# couldn't be optimized away, due to an incorrect assumption in the
+# implementation.
+
+# NB: This is a bit abusively formed.  Currently -l internally writes "probe"
+# and "{}" around its argument.  For this test we want to introduce a variable
+# that can't be optimized away.  The trailing comment mark lets the auto "{}"
+# get ignored.
+spawn stap -l "begin { if (a) next }#"
+
+expect {
+    # the output should not include anything else, like the 'a' local.
+    -re "^begin\r\n$" {
+        pass "probe list is correct"
+        return
+    }
+}
+fail "probe list is incorrect"