man pages: elaborate more on probe syntax/semantics in stapprobes.3stap

diff --git a/stap.1 b/stap.1
index b9d1dccb26d3c31d2e8b6df18d45a33c202c4600..f792a6456ec77d0ef2c4986db509d731edc61017 100644 (file)
--- a/stap.1
+++ b/stap.1
@@ -1007,11 +1007,12 @@ general syntax is as follows:
 .PP
 Events are specified in a special syntax called "probe points".  There
 are several varieties of probe points defined by the translator, and
-tapset scripts may define further ones using aliases.  Probe points may
-be grouped, or listed in preference sequences, or declared optional.
-More details on probe point syntax and semantics are listed in the
+tapset scripts may define further ones using aliases.  Probe points
+may be wildcarded, grouped, or listed in preference sequences, or
+declared optional.  More details on probe point syntax and semantics
+are listed on the
 .IR stapprobes (3stap)
-manual pages.
+manual page.
 .PP
 The probe handler is interpreted relative to the context of each
 event.  For events associated with kernel code, this context may

diff --git a/stapprobes.3stap b/stapprobes.3stap
index 543cd08f3c639d638ee32c88274035b446c10451..5505a0437d51a509f13eeee96b6db7b4cd341083 100644 (file)
--- a/stapprobes.3stap
+++ b/stapprobes.3stap
@@ -24,19 +24,30 @@ standard tapset scripts.  Many are individually documented in the
 manual section, with the
 .IR probe::
 prefix.
+
+.SH SYNTAX
+
+.PP
+.SAMPLE
+.BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " }
+.ESAMPLE
+.PP
+A probe declaration may list multiple comma-separated probe points in
+order to attach a handler to all of the named events.  Normally, the
+handler statements are run whenever any of events occur.
 .PP
-The general probe point syntax is a dotted-symbol sequence.  This
-allows a breakdown of the event namespace into parts, somewhat like
-the Domain Name System does on the Internet.  Each component
-identifier may be parametrized by a string or number literal, with a
-syntax like a function call.  A component may include a "*" character,
-to expand to a set of matching probe points.  It may also include "**"
-to match multiple sequential components at once.  Probe aliases likewise
-expand to other probe points.
+The syntax of a single probe point is a general dotted-symbol
+sequence.  This allows a breakdown of the event namespace into parts,
+somewhat like the Domain Name System does on the Internet.  Each
+component identifier may be parametrized by a string or number
+literal, with a syntax like a function call.  A component may include
+a "*" character, to expand to a set of matching probe points.  It may
+also include "**" to match multiple sequential components at once.
+Probe aliases likewise expand to other probe points.
 .PP
-Probe aliases can be given on their own,
-or with a suffix. The suffix attaches to the underlying probe point
-that the alias is expanded to. For example,
+Probe aliases can be given on their own, or with a suffix. The suffix
+attaches to the underlying probe point that the alias is expanded
+to. For example,
 .SAMPLE
 syscall.read.return.maxactive(10)
 .ESAMPLE
@@ -48,10 +59,10 @@ with the component
 .IR maxactive(10)
 being recognized as a suffix.
 .PP
-Each and every probe point resulting from expansion is
-normally resolved to some low-level system instrumentation facility
-(e.g., a kprobe address, marker, or a timer configuration), otherwise
-the elaboration phase will fail.
+Normally, each and every probe point resulting from wildcard- and
+alias-expansion must be resolved to some low-level system
+instrumentation facility (e.g., a kprobe address, marker, or a timer
+configuration), otherwise the elaboration phase will fail.
 .PP
 However, a probe point may be followed by a "?" character, to indicate
 that it is optional, and that no error should result if it fails to
@@ -68,8 +79,9 @@ order to enable/disable the probe point on-the-fly. With the "if" statement,
 if the "expr" is false when the probe point is hit, the whole probe body
 including alias's body is skipped. The condition is stacked up through
 all levels of alias/wildcard expansion. So the final condition becomes
-the logical-and of conditions of all expanded alias/wildcard.
-
+the logical-and of conditions of all expanded alias/wildcard.  The expressions
+are necessarily restricted to global variables.
+.PP
 These are all
 .B syntactically
 valid probe points.  (They are generally