2005-12-02 Frank Ch. Eigler <fche@elastic.org>

	* configure.ac: Bump version number.
	* stap.1.in: Document some of the new print/stats stuff.
	* configure: Regenerated.
	* systemtap.spec.in: Enable ia64 and ppc builds.

5 files changed, 123 insertions, 12 deletions

diff --git a/ChangeLog b/ChangeLog
index 096f61c9..bbbead3d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2005-12-02  Frank Ch. Eigler  <fche@elastic.org>
+
+	* configure.ac: Bump version number.
+	* stap.1.in: Document some of the new print/stats stuff.
+	* configure: Regenerated.
+	* systemtap.spec.in: Enable ia64 and ppc builds.
+
 2005-12-01  Frank Ch. Eigler  <fche@elastic.org>
 
 	PR 1944 improved hack.
diff --git a/configure b/configure
index 9137b1a3..0fc16037 100755
--- a/configure
+++ b/configure
@@ -1,6 +1,6 @@
 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.59 for systemtap 0.4.2.
+# Generated by GNU Autoconf 2.59 for systemtap 0.5.
 #
 # Report bugs to <systemtap@sources.redhat.com>.
 #
@@ -269,8 +269,8 @@ SHELL=${CONFIG_SHELL-/bin/sh}
 # Identity of this package.
 PACKAGE_NAME='systemtap'
 PACKAGE_TARNAME='systemtap'
-PACKAGE_VERSION='0.4.2'
-PACKAGE_STRING='systemtap 0.4.2'
+PACKAGE_VERSION='0.5'
+PACKAGE_STRING='systemtap 0.5'
 PACKAGE_BUGREPORT='systemtap@sources.redhat.com'
 
 # Factoring default headers for most tests.
@@ -787,7 +787,7 @@ if test "$ac_init_help" = "long"; then
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures systemtap 0.4.2 to adapt to many kinds of systems.
+\`configure' configures systemtap 0.5 to adapt to many kinds of systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
@@ -849,7 +849,7 @@ fi
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of systemtap 0.4.2:";;
+     short | recursive ) echo "Configuration of systemtap 0.5:";;
    esac
   cat <<\_ACEOF
 
@@ -971,7 +971,7 @@ fi
 test -n "$ac_init_help" && exit 0
 if $ac_init_version; then
   cat <<\_ACEOF
-systemtap configure 0.4.2
+systemtap configure 0.5
 generated by GNU Autoconf 2.59
 
 Copyright (C) 2003 Free Software Foundation, Inc.
@@ -985,7 +985,7 @@ cat >&5 <<_ACEOF
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by systemtap $as_me 0.4.2, which was
+It was created by systemtap $as_me 0.5, which was
 generated by GNU Autoconf 2.59.  Invocation command line was
 
   $ $0 $@
@@ -1630,7 +1630,7 @@ fi
 
 # Define the identity of the package.
  PACKAGE='systemtap'
- VERSION='0.4.2'
+ VERSION='0.5'
 
 
 cat >>confdefs.h <<_ACEOF
@@ -5567,7 +5567,7 @@ _ASBOX
 } >&5
 cat >&5 <<_CSEOF
 
-This file was extended by systemtap $as_me 0.4.2, which was
+This file was extended by systemtap $as_me 0.5, which was
 generated by GNU Autoconf 2.59.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
@@ -5630,7 +5630,7 @@ _ACEOF
 
 cat >>$CONFIG_STATUS <<_ACEOF
 ac_cs_version="\\
-systemtap config.status 0.4.2
+systemtap config.status 0.5
 configured by $0, generated by GNU Autoconf 2.59,
   with options \\"`echo "$ac_configure_args" | sed 's/[\\""\`\$]/\\\\&/g'`\\"
 
diff --git a/configure.ac b/configure.ac
index 88e68f06..50c5c710 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,7 +1,7 @@
 dnl configure.ac --- autoconf input file for systemtap
 dnl Process this file with autoconf to produce a configure script.
 
-AC_INIT([systemtap], 0.4.2, systemtap@sources.redhat.com, systemtap)
+AC_INIT([systemtap], 0.5, systemtap@sources.redhat.com, systemtap)
 
 AC_PREREQ(2.59)
 AM_INIT_AUTOMAKE
diff --git a/stap.1.in b/stap.1.in
index 407f8842..e90bb09e 100644
--- a/stap.1.in
+++ b/stap.1.in
@@ -410,6 +410,110 @@ Functions may call others or themselves
 recursively, up to a fixed nesting limit.  This limit is defined by
 a macro in the translated C code and is in the neighbourhood of 10.
 
+.SS PRINTING
+The function names
+.IR print ", " printf ", " sprint ", and " sprintf
+are specially treated by the translator.  They format values for
+printing to the standard systemtap log stream in a more convenient
+way.
+.PP
+.TP
+print
+takes a single value of any type, and prints it
+.TP
+sprint
+operates like
+.IR print ,
+but returns the formatted string instead of logging it.
+.TP
+printf
+takes a formatting string, and a number of values of corresponding types,
+and prints them all.
+.TP
+sprintf
+operates like
+.IR printf ,
+but like
+.IR sprint ,
+returns the formatted string instead of logging it.
+.PP
+The
+.IR printf
+formatting directives similar to those of C, except that they are
+fully type-checked by the translator.
+.SAMPLE
+	x = sprintf("take %d steps forward, %d steps back\\n", 3, 2)
+	printf("take %d steps forward, %d steps back\\n", 3+1, 2*2)
+	bob = "bob"
+	alice = "alice"
+	print(bob)
+	print("hello")
+	print(10)
+	printf("%s phoned %s %.4x times\\n", bob, alice . bob, 3456)
+	printf("%s except after %s\\n", 
+		sprintf("%s before %s", 
+			sprint(1), sprint(3)), 
+		sprint("C"))
+.ESAMPLE
+
+.SS STATISTICS
+It is often desirable to collect statistics in a way that avoids the
+penalties of repeatedly locking the global variables those numbers are
+being put into.  Systemtap provides a solution using a special
+operator to accumulate values, and several pseudo-functions to extract
+the statistical aggregates.
+.PP
+The aggregation operator is
+.IR <<< ,
+and resembles an assignment, or a C++ output-streaming operation.
+The left operand specifies a scalar or array-index lvalue, which must
+be declared global.  The right operand is a numeric expression.  The
+meaning is intuitive: add the given number to the pile of numbers to
+compute statistics of.  (The specific list of statistics to gather
+is given separately, by the extraction functions.)
+.SAMPLE
+    foo <<< 1
+    stats[pid()] <<< memsize
+.ESAMPLE
+.PP
+The extraction functions are also special.  For each appearance of a
+distinct extraction function operating on a given identifier, the
+translator arranges to compute a set of statistics that satisfy it.
+The statistics system is thereby "on-demand".  Each execution of
+an extraction function causes the aggregation to be computed for
+that moment across all processors. 
+.PP
+Here is the set of extractor functions.  The first argument of each is
+the same style of lvalue used on the left hand side of the accumulate
+operation.  The
+.IR @count(v) ", " @sum(v) ", " @min(v) ", " @max(v) ", " @avg(v)
+extractor functions compute the number/total/minimum/maximum/average
+of all accumulated values.  The resulting values are all simple
+integers.
+.PP
+Histograms are also available, but are more complicated because they
+have a vector rather than scalar value.
+.I @hist_linear(v,L,H,W)
+represents a linear histogram whose low/high/width parameters are
+given by the following three literal numbers.  Similarly,
+.I @hist_log(v,N)
+represents a base-2 logarithmic histogram with the given number of
+buckets.  N may be omitted, and defaults to 64.  Printing a histogram
+with the
+.I print
+family of functions renders a histogram object as a tabular
+"ASCII art" bar chart.
+.SAMPLE
+probe foo {
+  x <<< $value
+}
+probe end {  
+  printf ("avg %d = sum %d / count %d\\n",
+          @avg(x), @sum(x), @count(x))
+  print (@hist_log(v))
+}
+.ESAMPLE
+
 .SS EMBEDDED C
 When in guru mode, the translator accepts embedded code in the
 script.  Such code is enclosed between
diff --git a/systemtap.spec.in b/systemtap.spec.in
index 3248b119..9ab83ede 100644
--- a/systemtap.spec.in
+++ b/systemtap.spec.in
@@ -10,7 +10,7 @@ License: GPL
 URL: http://sourceware.org/systemtap/
 Source: ftp://sourceware.org/pub/%{name}/%{name}-%{version}.tar.gz
 
-ExclusiveArch: %{ix86} x86_64
+ExclusiveArch: %{ix86} x86_64 ppc ia64
 
 BuildRoot: %{_tmppath}/%{name}-root