description of pass 2 for details.
.TP
.BI \-D " NAME=VALUE"
-Add the given C preprocessor directive to the module Makefile. These can
+Add the given C preprocessor directive to the module Makefile. These can
be used to override limit parameters described below.
.TP
.BI \-R " DIR"
Start the probes, run CMD, and exit when CMD finishes.
.TP
.BI \-x " PID"
-Sets target() to PID. This allows scripts to be written that filter on
+Sets target() to PID. This allows scripts to be written that filter on
a specific process.
.TP
.BI \-l " PROBE"
.BI \-F
Without -o option, load module and start probes, then detach from the module
leaving the probes running.
-With -o option, run staprun in background as a daemon and show it's pid.
+With -o option, run staprun in background as a daemon and show its pid.
.TP
.BI \-S " size[,N]"
Sets the maximum size of output file and the maximum number of output files.
.SH SCRIPT LANGUAGE
-The systemtap script language resembles
+The systemtap script language resembles
.IR awk .
There are two main outermost constructs: probes and functions. Within
these, statements and expressions use C-like operator syntax and
.SS PREPROCESSING
A simple conditional preprocessing stage is run as a part of parsing.
-The general form is similar to the
+The general form is similar to the
.RB cond " ? " exp1 " : " exp2
ternary operator:
.SAMPLE
option) compares to the given version string. The comparison is
performed by the glibc function
.BR strverscmp .
-As a special case, if the operator is for simple equality
+As a special case, if the operator is for simple equality
.RB ( == ),
or inequality
.RB ( != ),
.ESAMPLE
The following code might adapt to hypothetical kernel version drift:
.SAMPLE
-probe kernel.function (
- %( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
+probe kernel.function (
+ %( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
%( kernel_vr == "2.6.13*smp" %? "do_page_fault" %:
UNSUPPORTED %) %)
) { /* ... */ }
%( arch == "ia64" %?
- probe syscall.vliw = kernel.function("vliw_widget") {}
+ probe syscall.vliw = kernel.function("vliw_widget") {}
%)
.ESAMPLE
the value.
.TP
.BR { " STMT1 STMT2 ... " }
-Execute each statement in sequence in this block. Note that
+Execute each statement in sequence in this block. Note that
separators or terminators are generally not necessary between statements.
.TP
.BR ;
.BR foreach " (VAR " in " ARRAY [ "limit " EXP ]) STMT"
Loop over each element of the named global array, assigning current
key to VAR. The array may not be modified within the statement.
-By adding a single
+By adding a single
.BR + " or " \-
operator after the VAR or the ARRAY identifier, the iteration will
proceed in a sorted order, by ascending or descending index or value.
Using the optional
-.BR limit
+.BR limit
keyword limits the number of loop iterations to EXP times. EXP is
evaluted once at the beginning of the loop.
.TP
.B = .=
.TP
unary numeric operators
-.B + \- ! ~ ++ \-\-
+.B + \- ! ~ ++ \-\-
.TP
binary numeric or string comparison operators
.B < > <= >= == !=
event. For events associated with kernel code, this context may
include
.I variables
-defined in the
+defined in the
.I source code
at that spot. These "target variables" are presented to the script as
variables whose names are prefixed with "$". They may be accessed
New probe points may be defined using "aliases". Probe point aliases
look similar to probe definitions, but instead of activating a probe
at the given point, it just defines a new probe point name as an alias
-to an existing one. There are two types of alias, i.e. the prologue
+to an existing one. There are two types of alias, i.e. the prologue
style and the epilogue style which are identified by "=" and "+="
-respectively.
+respectively.
.PP
For prologue style alias, the statement block that follows an alias
definition is implicitly added as a prologue to any probe that refers
.IR printf
formatting directives similar to those of C, except that they are
fully type-checked by the translator:
-.RS
+.RS
.TP
-%b
+%b
Writes a binary blob of the value given, instead of ASCII text. The width specifier determines the number of bytes to write; valid specifiers are %b %1b %2b %4b %8b. Default (%b) is 8 bytes.
.TP
%c
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.
+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
Histograms are also available, but are more complicated because they
have a vector rather than scalar value.
.I @hist_linear(v,start,stop,interval)
-represents a linear histogram from "start" to "stop" by increments
+represents a linear histogram from "start" to "stop" by increments
of "interval". The interval must be positive. Similarly,
.I @hist_log(v)
represents a base-2 logarithmic histogram. Printing a histogram
probe foo {
x <<< $value
}
-probe end {
+probe end {
printf ("avg %d = sum %d / count %d\\n",
@avg(x), @sum(x), @count(x))
print (@hist_log(v))
be useful to add
.IR #include
instructions, and any auxiliary definitions for use by other embedded
-code.
+code.
.PP
The other place where embedded code is permitted is as a function body.
In this case, the script language body is replaced entirely by a piece
.IR 2.6/*.stp ,
and finally
.IR *.stp
-Stopping the translator after pass 1 causes it to print the parse trees.
+Stopping the translator after pass 1 causes it to print the parse trees.
.PP
In pass 2, the translator analyzes the input script to resolve symbols
until all symbols are resolved and a subset of tapset scripts is
selected.
.PP
-Next, all probe point descriptions are validated
+Next, all probe point descriptions are validated
against the wide variety supported by the translator. Probe points that
refer to code locations ("synchronous probe points") require the
appropriate kernel debugging information to be installed. In the
mismatches or invalid $target variables, it sometimes may be useful
to disable the optimizations with the
.BR \-u
-option.
+option.
.PP
Finally, all variable, function, parameter, array, and index types are
inferred from context (literals and operators). Stopping the
unloads the module, and cleans up.
.SH EXAMPLES
-See the
+See the
.IR stapex (3stap)
manual page for a collection of samples.
.I $SYSTEMTAP_DIR/cache
directory. The cache can be limited by having the file
.I cache_mb_limit
-placed in the cache directory (shown above) containing only an ASCII
+placed in the cache directory (shown above) containing only an ASCII
integer representing how many MiB the cache should not exceed. Note that
this is a 'soft' limit in that the cache will be cleaned after a new entry
-is added, so the total cache size may temporarily exceed this limit. In the
+is added, so the total cache size may temporarily exceed this limit. In the
absence of this file, a default will be created with the limit set to 64MiB.
.SH SAFETY AND SECURITY
.IR staprun
program. The latter is a part of the Systemtap package, dedicated to
module loading and unloading (but only in the white zone), and
-kernel-to-user data transfer. Since
+kernel-to-user data transfer. Since
.IR staprun
does not perform any additional security checks on the kernel objects
it is given, it would be unwise for a system administrator to add
-untrusted users to the
+untrusted users to the
.I stapdev
or
.I stapusr
The resource use limits are set by macros in the generated C code.
These may be overridden with the
.BR \-D
-flag. A selection of these is as follows:
+flag. A selection of these is as follows:
.TP
MAXNESTING
Maximum number of recursive function call levels, default 10.
guests connected to the host, unloading the host will be failed.
.PP
-In case something goes wrong with
+In case something goes wrong with
.IR stap " or " staprun
after a probe has already started running, one may safely kill both
user processes, and remove the active probe kernel module with
Temporary directory for systemtap files, including translated C code
and kernel object.
.TP
-@prefix@/share/systemtap/tapset
+@prefix@/share/systemtap/tapset
The automatic tapset search directory, unless overridden by
the
.I SYSTEMTAP_TAPSET
git://sourceware.org / systemtap.git / commitdiff