new sample: varwatch

7 files changed, 77 insertions, 48 deletions

diff --git a/testsuite/systemtap.examples/general/varwatch.meta b/testsuite/systemtap.examples/general/varwatch.meta
new file mode 100644
index 00000000..3d876bb1
--- /dev/null
+++ b/testsuite/systemtap.examples/general/varwatch.meta
@@ -0,0 +1,6 @@
+title: Watch a variable changing value in a thread.
+name: varwatch.stp
+keywords: monitoring
+description: This script places a set of probes (specified by $1), each of which monitors the state of some context $variable expression (specified by $2).  Whenever the value changes, with respect to the active thread, the event is traced.
+test_check: stap -wp4 varwatch.stp 'kernel.statement("do_sys_open@fs/open.c:*")' '$$vars'
+test_installcheck: stap -w varwatch.stp 'kernel.statement("do_sys_open@fs/open.c:*")' '$$vars' -c "sleep 0.2"
diff --git a/testsuite/systemtap.examples/general/varwatch.stp b/testsuite/systemtap.examples/general/varwatch.stp
new file mode 100644
index 00000000..845ca166
--- /dev/null
+++ b/testsuite/systemtap.examples/general/varwatch.stp
@@ -0,0 +1,28 @@
+#! /usr/bin/env stap
+
+global var, varerr
+
+probe $1 {
+  t=tid() # or t=0 for thread-agnostic checking
+  if (@defined($2)) {
+     try {
+         newvar = $2;
+         if (var[t] != newvar) {
+            printf("%s %s changed in thread %d from %s to %s\n", pp(), @2, t, sprint(var[t]), sprint(newvar));
+            var[t] = newvar;
+         }
+     } catch { varerr ++ }  # error during $2 resolution or perhaps var[] assignment
+  }
+}
+
+probe kprocess.release { # if using per-thread checking
+  delete var[$p->pid] # thread
+}
+
+probe never {
+  var[0]=""  # assigns a type to var in case no probes match $1 above
+}
+
+probe error,end {
+  if (varerr) printf("%s %s access errors: %d", @1, @2, varerr);
+}
diff --git a/testsuite/systemtap.examples/index.html b/testsuite/systemtap.examples/index.html
index 1bcfff5e..e241f11f 100644
--- a/testsuite/systemtap.examples/index.html
+++ b/testsuite/systemtap.examples/index.html
@@ -58,6 +58,9 @@ keywords: <a href="keyword-index.html#SIMPLE">SIMPLE</a> <br>
 <li><a href="general/para-callgraph.stp">general/para-callgraph.stp</a> - Callgraph tracing with arguments<br>
 keywords: <a href="keyword-index.html#TRACE">TRACE</a> <a href="keyword-index.html#CALLGRAPH">CALLGRAPH</a> <br>
 <p>Print a timed per-thread callgraph, complete with function parameters and return values.  The first parameter names the function probe points to trace.  The optional second parameter names the probe points for trigger functions, which acts to enable tracing for only those functions that occur while the current thread is nested within the trigger.</p></li>
+<li><a href="general/varwatch.stp">general/varwatch.stp</a> - Watch a variable changing value in a thread.<br>
+keywords: <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
+<p>This script places a set of probes (specified by $1), each of which monitors the state of some context $variable expression (specified by $2).  Whenever the value changes, with respect to the active thread, the event is traced.</p></li>
 <li><a href="interrupt/interrupts-by-dev.stp">interrupt/interrupts-by-dev.stp</a> - Record interrupts on a per-device basis.<br>
 keywords: <a href="keyword-index.html#INTERRUPT">INTERRUPT</a> <br>
 <p>The interrupts-by-dev.stp script profiles interrupts received by each device per 100 ms.</p></li>
@@ -91,9 +94,6 @@ keywords: <a href="keyword-index.html#IO">IO</a> <br>
 <li><a href="io/mbrwatch.stp">io/mbrwatch.stp</a> - Monitor read/write of MBR (boot sector) area of block devices<br>
 keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
 <p> The mbrwatch.stp script reports any attempted reads/writes of the first few sectors of a raw block device.</p></li>
-<li><a href="io/nfs_func_log.stp">io/nfs_func_log.stp</a> - Print Log of NFS Functions Used<br>
-keywords: <a href="keyword-index.html#IO">IO</a> <br>
-<p>The nfs_func_log.stp script logs the uses of NFS functions in the kernel.  The output is a trace. Each line contains the time stamp, the process name, and the process number followed by the function name.</p></li>
 <li><a href="io/nfs_func_users.stp">io/nfs_func_users.stp</a> - Tally the Number of NFS Functions Used by Each Process<br>
 keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#PROFILING">PROFILING</a> <br>
 <p>The nfs_func_users.stp script counts the uses of NFS functions in the kernel on a per process bases.  The output is sorted from the process with the greatest number of NFS functions called to the least. The output contains the executable name, the process number, and the total number of NFS functions called by the process.</p></li>
@@ -104,7 +104,7 @@ keywords: <a href="keyword-index.html#IO">IO</a> <br>
 keywords: <a href="keyword-index.html#IO">IO</a> <br>
 <p>Print out the executable name and process number as reads and writes to the specified device occur.</p></li>
 <li><a href="io/ttyspy.stp">io/ttyspy.stp</a> - Monitor tty typing.<br>
-keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITOR">MONITOR</a> <br>
+keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
 <p>The ttyspy.stp script uses tty_audit hooks to monitor recent typing activity on the system, printing a scrolling record of recent keystrokes, on a per-tty basis.</p></li>
 <li><a href="locks/bkl.stp">locks/bkl.stp</a> - Tracing Contention on Big Kernel Lock (BKL)<br>
 keywords: <a href="keyword-index.html#LOCKING">LOCKING</a> <br>
diff --git a/testsuite/systemtap.examples/index.txt b/testsuite/systemtap.examples/index.txt
index a0cdc9c3..d0fd5926 100644
--- a/testsuite/systemtap.examples/index.txt
+++ b/testsuite/systemtap.examples/index.txt
@@ -50,6 +50,15 @@ keywords: trace callgraph
   the trigger.
 
 
+general/varwatch.stp - Watch a variable changing value in a thread.
+keywords: monitoring
+
+  This script places a set of probes (specified by $1), each of which
+  monitors the state of some context $variable expression (specified by
+  $2).	Whenever the value changes, with respect to the active thread,
+  the event is traced.
+
+
 interrupt/interrupts-by-dev.stp - Record interrupts on a per-device basis.
 keywords: interrupt
 
@@ -156,15 +165,6 @@ keywords: io monitoring
   first few sectors of a raw block device.
 
 
-io/nfs_func_log.stp - Print Log of NFS Functions Used
-keywords: io
-
-  The nfs_func_log.stp script logs the uses of NFS functions in the
-  kernel.  The output is a trace. Each line contains the time stamp,
-  the process name, and the process number followed by the function
-  name.
-
-
 io/nfs_func_users.stp - Tally the Number of NFS Functions Used by Each Process
 keywords: io profiling
 
@@ -190,7 +190,7 @@ keywords: io
 
 
 io/ttyspy.stp - Monitor tty typing.
-keywords: io tty per-process monitor
+keywords: io tty per-process monitoring
 
   The ttyspy.stp script uses tty_audit hooks to monitor recent typing
   activity on the system, printing a scrolling record of recent
diff --git a/testsuite/systemtap.examples/io/ttyspy.meta b/testsuite/systemtap.examples/io/ttyspy.meta
index ea1c9040..b171fad4 100644
--- a/testsuite/systemtap.examples/io/ttyspy.meta
+++ b/testsuite/systemtap.examples/io/ttyspy.meta
@@ -1,6 +1,6 @@
 title: Monitor tty typing.
 name: ttyspy.stp
-keywords: io tty per-process monitor
+keywords: io tty per-process monitoring
 description: The ttyspy.stp script uses tty_audit hooks to monitor recent typing activity on the system, printing a scrolling record of recent keystrokes, on a per-tty basis.
 test_support: stap -l 'kernel.function("tty_audit_add_data")'
 test_check: stap -gp4 ttyspy.stp
diff --git a/testsuite/systemtap.examples/keyword-index.html b/testsuite/systemtap.examples/keyword-index.html
index 40f2f1d6..a1f5a3c3 100644
--- a/testsuite/systemtap.examples/keyword-index.html
+++ b/testsuite/systemtap.examples/keyword-index.html
@@ -39,7 +39,7 @@
          	</ul>
 
 <h2>Examples by Keyword</h2>
-<p><tt><a href="#ALLOCATOR">ALLOCATOR</a> <a href="#AUTOFS">AUTOFS</a> <a href="#BACKTRACE">BACKTRACE</a> <a href="#BUFFER">BUFFER</a> <a href="#CALLGRAPH">CALLGRAPH</a> <a href="#CPU">CPU</a> <a href="#DEVICE">DEVICE</a> <a href="#DISK">DISK</a> <a href="#FILES">FILES</a> <a href="#FILESYSTEM">FILESYSTEM</a> <a href="#FORMAT">FORMAT</a> <a href="#FREE">FREE</a> <a href="#FUNCTIONS">FUNCTIONS</a> <a href="#FUTEX">FUTEX</a> <a href="#GRAPH">GRAPH</a> <a href="#HACK">HACK</a> <a href="#INTERRUPT">INTERRUPT</a> <a href="#IO">IO</a> <a href="#LOCKING">LOCKING</a> <a href="#MEMORY">MEMORY</a> <a href="#MONITOR">MONITOR</a> <a href="#MONITORING">MONITORING</a> <a href="#NETWORK">NETWORK</a> <a href="#NFS">NFS</a> <a href="#NUMA">NUMA</a> <a href="#PER-PROCESS">PER-PROCESS</a> <a href="#PROCESS">PROCESS</a> <a href="#PROFILING">PROFILING</a> <a href="#READ">READ</a> <a href="#SCHEDULER">SCHEDULER</a> <a href="#SCSI">SCSI</a> <a href="#SIGNALS">SIGNALS</a> <a href="#SIMPLE">SIMPLE</a> <a href="#SLAB">SLAB</a> <a href="#SLEEP">SLEEP</a> <a href="#SOCKET">SOCKET</a> <a href="#STATISTICS">STATISTICS</a> <a href="#SYSCALL">SYSCALL</a> <a href="#TCP">TCP</a> <a href="#TIME">TIME</a> <a href="#TRACE">TRACE</a> <a href="#TRACEPOINT">TRACEPOINT</a> <a href="#TRAFFIC">TRAFFIC</a> <a href="#TTY">TTY</a> <a href="#USE">USE</a> <a href="#WAIT4">WAIT4</a> <a href="#WRITE">WRITE</a> </tt></p>
+<p><tt><a href="#ALLOCATOR">ALLOCATOR</a> <a href="#AUTOFS">AUTOFS</a> <a href="#BACKTRACE">BACKTRACE</a> <a href="#BUFFER">BUFFER</a> <a href="#CALLGRAPH">CALLGRAPH</a> <a href="#CPU">CPU</a> <a href="#DEVICE">DEVICE</a> <a href="#DISK">DISK</a> <a href="#FILES">FILES</a> <a href="#FILESYSTEM">FILESYSTEM</a> <a href="#FORMAT">FORMAT</a> <a href="#FREE">FREE</a> <a href="#FUNCTIONS">FUNCTIONS</a> <a href="#FUTEX">FUTEX</a> <a href="#GRAPH">GRAPH</a> <a href="#HACK">HACK</a> <a href="#INTERRUPT">INTERRUPT</a> <a href="#IO">IO</a> <a href="#LOCKING">LOCKING</a> <a href="#MEMORY">MEMORY</a> <a href="#MONITORING">MONITORING</a> <a href="#NETWORK">NETWORK</a> <a href="#NFS">NFS</a> <a href="#NUMA">NUMA</a> <a href="#PER-PROCESS">PER-PROCESS</a> <a href="#PROCESS">PROCESS</a> <a href="#PROFILING">PROFILING</a> <a href="#READ">READ</a> <a href="#SCHEDULER">SCHEDULER</a> <a href="#SCSI">SCSI</a> <a href="#SIGNALS">SIGNALS</a> <a href="#SIMPLE">SIMPLE</a> <a href="#SLAB">SLAB</a> <a href="#SLEEP">SLEEP</a> <a href="#SOCKET">SOCKET</a> <a href="#STATISTICS">STATISTICS</a> <a href="#SYSCALL">SYSCALL</a> <a href="#TCP">TCP</a> <a href="#TIME">TIME</a> <a href="#TRACE">TRACE</a> <a href="#TRACEPOINT">TRACEPOINT</a> <a href="#TRAFFIC">TRAFFIC</a> <a href="#TTY">TTY</a> <a href="#USE">USE</a> <a href="#WAIT4">WAIT4</a> <a href="#WRITE">WRITE</a> </tt></p>
 <h3><a name="ALLOCATOR">ALLOCATOR</a></h3>
 <ul>
 <li><a href="memory/vm.tracepoints.stp">memory/vm.tracepoints.stp</a> - Collect slab allocation statistics<br>
@@ -189,9 +189,6 @@ keywords: <a href="keyword-index.html#IO">IO</a> <br>
 <li><a href="io/mbrwatch.stp">io/mbrwatch.stp</a> - Monitor read/write of MBR (boot sector) area of block devices<br>
 keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
 <p> The mbrwatch.stp script reports any attempted reads/writes of the first few sectors of a raw block device.</p></li>
-<li><a href="io/nfs_func_log.stp">io/nfs_func_log.stp</a> - Print Log of NFS Functions Used<br>
-keywords: <a href="keyword-index.html#IO">IO</a> <br>
-<p>The nfs_func_log.stp script logs the uses of NFS functions in the kernel.  The output is a trace. Each line contains the time stamp, the process name, and the process number followed by the function name.</p></li>
 <li><a href="io/nfs_func_users.stp">io/nfs_func_users.stp</a> - Tally the Number of NFS Functions Used by Each Process<br>
 keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#PROFILING">PROFILING</a> <br>
 <p>The nfs_func_users.stp script counts the uses of NFS functions in the kernel on a per process bases.  The output is sorted from the process with the greatest number of NFS functions called to the least. The output contains the executable name, the process number, and the total number of NFS functions called by the process.</p></li>
@@ -202,7 +199,7 @@ keywords: <a href="keyword-index.html#IO">IO</a> <br>
 keywords: <a href="keyword-index.html#IO">IO</a> <br>
 <p>Print out the executable name and process number as reads and writes to the specified device occur.</p></li>
 <li><a href="io/ttyspy.stp">io/ttyspy.stp</a> - Monitor tty typing.<br>
-keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITOR">MONITOR</a> <br>
+keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
 <p>The ttyspy.stp script uses tty_audit hooks to monitor recent typing activity on the system, printing a scrolling record of recent keystrokes, on a per-tty basis.</p></li>
 <li><a href="process/sleepingBeauties.stp">process/sleepingBeauties.stp</a> - Generating Backtraces of Threads Waiting for IO Operations<br>
 keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#SCHEDULER">SCHEDULER</a> <a href="keyword-index.html#BACKTRACE">BACKTRACE</a> <br>
@@ -253,17 +250,17 @@ keywords: <a href="keyword-index.html#MEMORY">MEMORY</a> <a href="keyword-index.
 keywords: <a href="keyword-index.html#NETWORK">NETWORK</a> <a href="keyword-index.html#TCP">TCP</a> <a href="keyword-index.html#BUFFER">BUFFER</a> <a href="keyword-index.html#MEMORY">MEMORY</a> <br>
 <p>The sk_stream-wait_memory.stp prints a time stamp, executable, and pid each time a process blocks due to the send buffer being full. A similar entry is printed each time a process continues because there is room in the buffer.</p></li>
 </ul>
-<h3><a name="MONITOR">MONITOR</a></h3>
-<ul>
-<li><a href="io/ttyspy.stp">io/ttyspy.stp</a> - Monitor tty typing.<br>
-keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITOR">MONITOR</a> <br>
-<p>The ttyspy.stp script uses tty_audit hooks to monitor recent typing activity on the system, printing a scrolling record of recent keystrokes, on a per-tty basis.</p></li>
-</ul>
 <h3><a name="MONITORING">MONITORING</a></h3>
 <ul>
+<li><a href="general/varwatch.stp">general/varwatch.stp</a> - Watch a variable changing value in a thread.<br>
+keywords: <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
+<p>This script places a set of probes (specified by $1), each of which monitors the state of some context $variable expression (specified by $2).  Whenever the value changes, with respect to the active thread, the event is traced.</p></li>
 <li><a href="io/mbrwatch.stp">io/mbrwatch.stp</a> - Monitor read/write of MBR (boot sector) area of block devices<br>
 keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
 <p> The mbrwatch.stp script reports any attempted reads/writes of the first few sectors of a raw block device.</p></li>
+<li><a href="io/ttyspy.stp">io/ttyspy.stp</a> - Monitor tty typing.<br>
+keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
+<p>The ttyspy.stp script uses tty_audit hooks to monitor recent typing activity on the system, printing a scrolling record of recent keystrokes, on a per-tty basis.</p></li>
 </ul>
 <h3><a name="NETWORK">NETWORK</a></h3>
 <ul>
@@ -313,7 +310,7 @@ keywords: <a href="keyword-index.html#MEMORY">MEMORY</a> <a href="keyword-index.
 <h3><a name="PER-PROCESS">PER-PROCESS</a></h3>
 <ul>
 <li><a href="io/ttyspy.stp">io/ttyspy.stp</a> - Monitor tty typing.<br>
-keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITOR">MONITOR</a> <br>
+keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
 <p>The ttyspy.stp script uses tty_audit hooks to monitor recent typing activity on the system, printing a scrolling record of recent keystrokes, on a per-tty basis.</p></li>
 <li><a href="network/nettop.stp">network/nettop.stp</a> - Periodic Listing of Processes Using Network Interfaces<br>
 keywords: <a href="keyword-index.html#NETWORK">NETWORK</a> <a href="keyword-index.html#TRAFFIC">TRAFFIC</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <br>
@@ -529,7 +526,7 @@ keywords: <a href="keyword-index.html#NETWORK">NETWORK</a> <a href="keyword-inde
 <h3><a name="TTY">TTY</a></h3>
 <ul>
 <li><a href="io/ttyspy.stp">io/ttyspy.stp</a> - Monitor tty typing.<br>
-keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITOR">MONITOR</a> <br>
+keywords: <a href="keyword-index.html#IO">IO</a> <a href="keyword-index.html#TTY">TTY</a> <a href="keyword-index.html#PER-PROCESS">PER-PROCESS</a> <a href="keyword-index.html#MONITORING">MONITORING</a> <br>
 <p>The ttyspy.stp script uses tty_audit hooks to monitor recent typing activity on the system, printing a scrolling record of recent keystrokes, on a per-tty basis.</p></li>
 </ul>
 <h3><a name="USE">USE</a></h3>
diff --git a/testsuite/systemtap.examples/keyword-index.txt b/testsuite/systemtap.examples/keyword-index.txt
index cf69893d..4e1d31cd 100644
--- a/testsuite/systemtap.examples/keyword-index.txt
+++ b/testsuite/systemtap.examples/keyword-index.txt
@@ -321,15 +321,6 @@ keywords: io monitoring
   first few sectors of a raw block device.
 
 
-io/nfs_func_log.stp - Print Log of NFS Functions Used
-keywords: io
-
-  The nfs_func_log.stp script logs the uses of NFS functions in the
-  kernel.  The output is a trace. Each line contains the time stamp,
-  the process name, and the process number followed by the function
-  name.
-
-
 io/nfs_func_users.stp - Tally the Number of NFS Functions Used by Each Process
 keywords: io profiling
 
@@ -355,7 +346,7 @@ keywords: io
 
 
 io/ttyspy.stp - Monitor tty typing.
-keywords: io tty per-process monitor
+keywords: io tty per-process monitoring
 
   The ttyspy.stp script uses tty_audit hooks to monitor recent typing
   activity on the system, printing a scrolling record of recent
@@ -516,17 +507,16 @@ keywords: network tcp buffer memory
   is room in the buffer.
 
 
-= MONITOR =
-
-io/ttyspy.stp - Monitor tty typing.
-keywords: io tty per-process monitor
+= MONITORING =
 
-  The ttyspy.stp script uses tty_audit hooks to monitor recent typing
-  activity on the system, printing a scrolling record of recent
-  keystrokes, on a per-tty basis.
+general/varwatch.stp - Watch a variable changing value in a thread.
+keywords: monitoring
 
+  This script places a set of probes (specified by $1), each of which
+  monitors the state of some context $variable expression (specified by
+  $2).	Whenever the value changes, with respect to the active thread,
+  the event is traced.
 
-= MONITORING =
 
 io/mbrwatch.stp - Monitor read/write of MBR (boot sector) area of block devices
 keywords: io monitoring
@@ -535,6 +525,14 @@ keywords: io monitoring
   first few sectors of a raw block device.
 
 
+io/ttyspy.stp - Monitor tty typing.
+keywords: io tty per-process monitoring
+
+  The ttyspy.stp script uses tty_audit hooks to monitor recent typing
+  activity on the system, printing a scrolling record of recent
+  keystrokes, on a per-tty basis.
+
+
 = NETWORK =
 
 network/autofs4.stp - Watch autofs4 operations
@@ -647,7 +645,7 @@ keywords: memory numa
 = PER-PROCESS =
 
 io/ttyspy.stp - Monitor tty typing.
-keywords: io tty per-process monitor
+keywords: io tty per-process monitoring
 
   The ttyspy.stp script uses tty_audit hooks to monitor recent typing
   activity on the system, printing a scrolling record of recent
@@ -1202,7 +1200,7 @@ keywords: network traffic
 = TTY =
 
 io/ttyspy.stp - Monitor tty typing.
-keywords: io tty per-process monitor
+keywords: io tty per-process monitoring
 
   The ttyspy.stp script uses tty_audit hooks to monitor recent typing
   activity on the system, printing a scrolling record of recent