From 67d1ed18977fd602465f45ea42e85c1e6de8f1e9 Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Sat, 13 Oct 2012 10:48:30 -0400 Subject: [PATCH] man pages: elaborate more on probe syntax/semantics in stapprobes.3stap --- stap.1 | 9 +++++---- stapprobes.3stap | 46 +++++++++++++++++++++++++++++----------------- 2 files changed, 34 insertions(+), 21 deletions(-) diff --git a/stap.1 b/stap.1 index b9d1dccb2..f792a6456 100644 --- 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 543cd08f3..5505a0437 100644 --- 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 -- 2.43.5