| 1 |
.\" te -*- nroff -*- |
| 2 |
.TH STAP 1 |
| 3 |
.SH NAME |
| 4 |
stap \- systemtap script translator/driver |
| 5 |
|
| 6 |
.\" macros |
| 7 |
.\" do not nest SAMPLEs |
| 8 |
.de SAMPLE |
| 9 |
.br |
| 10 |
|
| 11 |
.nr oldin \\n(.i |
| 12 |
.RS |
| 13 |
.nf |
| 14 |
.nh |
| 15 |
.. |
| 16 |
.de ESAMPLE |
| 17 |
.hy |
| 18 |
.fi |
| 19 |
.RE |
| 20 |
.in \\n[oldin]u |
| 21 |
|
| 22 |
.. |
| 23 |
|
| 24 |
.SH SYNOPSIS |
| 25 |
|
| 26 |
.br |
| 27 |
.B stap |
| 28 |
[ |
| 29 |
.I OPTIONS |
| 30 |
] |
| 31 |
.I FILENAME |
| 32 |
[ |
| 33 |
.I ARGUMENTS |
| 34 |
] |
| 35 |
.br |
| 36 |
.B stap |
| 37 |
[ |
| 38 |
.I OPTIONS |
| 39 |
] |
| 40 |
.B \- |
| 41 |
[ |
| 42 |
.I ARGUMENTS |
| 43 |
] |
| 44 |
.br |
| 45 |
.B stap |
| 46 |
[ |
| 47 |
.I OPTIONS |
| 48 |
] |
| 49 |
.BI \-e " SCRIPT" |
| 50 |
[ |
| 51 |
.I ARGUMENTS |
| 52 |
] |
| 53 |
.br |
| 54 |
.B stap |
| 55 |
[ |
| 56 |
.I OPTIONS |
| 57 |
] |
| 58 |
.BI \-l " PROBE" |
| 59 |
[ |
| 60 |
.I ARGUMENTS |
| 61 |
] |
| 62 |
.br |
| 63 |
.B stap |
| 64 |
[ |
| 65 |
.I OPTIONS |
| 66 |
] |
| 67 |
.BI \-L " PROBE" |
| 68 |
[ |
| 69 |
.I ARGUMENTS |
| 70 |
] |
| 71 |
.br |
| 72 |
.B stap |
| 73 |
[ |
| 74 |
.I OPTIONS |
| 75 |
] |
| 76 |
.B \-\-dump-probe-types |
| 77 |
.br |
| 78 |
.B stap |
| 79 |
[ |
| 80 |
.I OPTIONS |
| 81 |
] |
| 82 |
.B \-\-dump-probe-aliases |
| 83 |
.br |
| 84 |
.B stap |
| 85 |
[ |
| 86 |
.I OPTIONS |
| 87 |
] |
| 88 |
.B \-\-dump-functions |
| 89 |
|
| 90 |
|
| 91 |
|
| 92 |
.SH DESCRIPTION |
| 93 |
|
| 94 |
The |
| 95 |
.IR stap |
| 96 |
program is the front-end to the Systemtap tool. It accepts probing |
| 97 |
instructions written in a simple domain-specific language, translates |
| 98 |
those instructions into C code, compiles this C code, and loads the |
| 99 |
resulting module into a running Linux kernel or a Dyninst user-space |
| 100 |
mutator, to perform the requested system trace/probe functions. You |
| 101 |
can supply the script in a named file (FILENAME), from standard input |
| 102 |
(use \- instead of FILENAME), or from the command line (using \-e |
| 103 |
SCRIPT). The program runs until it is interrupted by the user, or if |
| 104 |
the script voluntarily invokes the |
| 105 |
.I exit() |
| 106 |
function, or by sufficient number of soft errors. |
| 107 |
.PP |
| 108 |
The language, which is described the |
| 109 |
.IR "SCRIPT LANGUAGE" |
| 110 |
section below, is strictly typed, expressive, declaration free, procedural, |
| 111 |
prototyping-friendly, and inspired by |
| 112 |
.IR awk " and " C . |
| 113 |
It allows source code points or events in the system to be associated |
| 114 |
with handlers, which are subroutines that are executed synchronously. It is |
| 115 |
somewhat similar conceptually to "breakpoint command lists" in the |
| 116 |
.IR gdb |
| 117 |
debugger. |
| 118 |
|
| 119 |
.SH "DOCUMENTATION OVERVIEW" |
| 120 |
|
| 121 |
systemtap comes with a variety of educational, documentation and |
| 122 |
reference resources. They come online and/or packaged for offline |
| 123 |
use. Some systemtap diagnostic warning/error messages specially |
| 124 |
suggest reading a man page by including a string |
| 125 |
like \%[man\ error::pass5]. For online documentation, see the project web site, |
| 126 |
.nh |
| 127 |
https://sourceware.org/systemtap/ |
| 128 |
.hy |
| 129 |
. |
| 130 |
|
| 131 |
.TS |
| 132 |
tab(%) allbox; |
| 133 |
l l. |
| 134 |
\fBman pages\fP |
| 135 |
stap (this page)%language syntax, concepts, operation, options |
| 136 |
error::*%further explanation of error conditions |
| 137 |
warning::*%further explanation of warning conditions |
| 138 |
stapprobes%probe points and their $context variables |
| 139 |
stapref%quick reference to language syntax |
| 140 |
stappaths%T{ |
| 141 |
list of directories, including books & references |
| 142 |
T} |
| 143 |
stap-prep%T{ |
| 144 |
program to install auxiliary dependencies like kernel debuginfo |
| 145 |
T} |
| 146 |
tapset::*%generated list of tapsets |
| 147 |
probe::*%generated list of tapset probe aliases |
| 148 |
function::*%generated list of tapset functions |
| 149 |
macro::*%generated list of tapset macros |
| 150 |
stapvars%some of the tapset global variables |
| 151 |
staprun, stapdyn, stapbpf%programs for executing compiled systemtap scripts |
| 152 |
systemtap%initscript, boot-time probing |
| 153 |
stap-server%compilation server |
| 154 |
stapex%a few very basic script examples |
| 155 |
\fBbooks\fP% |
| 156 |
Beginner's Guide%tutorial book, language essentials, examples |
| 157 |
Tutorial%shorter tutorial, exercises |
| 158 |
Language Reference%detailed language manual, covers statistics/analysis |
| 159 |
Tapset Reference%the tapset man pages, reformatted into a book |
| 160 |
\fBreferences\fP% |
| 161 |
example scripts%T{ |
| 162 |
over a hundred directly usable sysadmin tools, toys, hacks to learn from |
| 163 |
T} |
| 164 |
.TE |
| 165 |
|
| 166 |
.SH OPTIONS |
| 167 |
The systemtap translator supports the following options. Any other option |
| 168 |
prints a list of supported options. Options may be given on the command line, |
| 169 |
as usual. If the file $SYSTEMTAP_DIR/rc exist, options are also loaded from |
| 170 |
there and interpreted first. ($SYSTEMTAP_DIR defaults to $HOME/.systemtap if unset.) |
| 171 |
|
| 172 |
.PP |
| 173 |
In some cases, the default value of an option depends on particular system |
| 174 |
configuration and thus can't be mentioned here directly. In some of those |
| 175 |
cases running "stap \-\-help" might display the default. |
| 176 |
|
| 177 |
.TP |
| 178 |
.B \- |
| 179 |
Use standard input instead of a given FILENAME as probe language input, |
| 180 |
unless \-e SCRIPT is given. |
| 181 |
.TP |
| 182 |
.B \-h \-\-help |
| 183 |
Show help message. |
| 184 |
.TP |
| 185 |
.B \-V \-\-version |
| 186 |
Show version message. |
| 187 |
.TP |
| 188 |
.BI \-p " NUM" |
| 189 |
Stop after pass NUM. The passes are numbered 1-5: parse, elaborate, |
| 190 |
translate, compile, run. See the |
| 191 |
.B PROCESSING |
| 192 |
section for details. |
| 193 |
.TP |
| 194 |
.B \-v |
| 195 |
Increase verbosity for all passes. Produce a larger volume of |
| 196 |
informative (?) output each time option repeated. |
| 197 |
.TP |
| 198 |
.B \-\-vp ABCDE |
| 199 |
Increase verbosity on a per-pass basis. For example, "\-\-vp\ 002" |
| 200 |
adds 2 units of verbosity to pass 3 only. The combination "\-v\ \-\-vp\ 00004" |
| 201 |
adds 1 unit of verbosity for all passes, and 4 more for pass 5. |
| 202 |
.TP |
| 203 |
.B \-k |
| 204 |
Keep the temporary directory after all processing. This may be useful |
| 205 |
in order to examine the generated C code, or to reuse the compiled |
| 206 |
kernel object. |
| 207 |
.TP |
| 208 |
.B \-g |
| 209 |
Guru mode. Enable parsing of unsafe expert-level constructs like |
| 210 |
embedded C. |
| 211 |
.TP |
| 212 |
.B \-P |
| 213 |
Prologue-searching mode. This is equivalent to \-\-prologue\-searching=always. |
| 214 |
Activate heuristics to work around incorrect debugging information for |
| 215 |
function parameter $context variables. |
| 216 |
.TP |
| 217 |
.B \-u |
| 218 |
Unoptimized mode. Disable unused code elision and many other optimizations |
| 219 |
during elaboration / translation. |
| 220 |
.TP |
| 221 |
.B \-w |
| 222 |
Suppressed warnings mode. Disables all warning messages. |
| 223 |
.TP |
| 224 |
.B \-W |
| 225 |
Treat all warnings as errors. |
| 226 |
.TP |
| 227 |
.BI \-b |
| 228 |
Use bulk mode (percpu files) for kernel-to-user data transfer. Use the |
| 229 |
.IR stap\-merge |
| 230 |
program to multiplex them back together later. |
| 231 |
.TP |
| 232 |
.B \-i \-\-interactive |
| 233 |
Interactive mode. Enable an interface to build the systemtap script |
| 234 |
incrementally and interactively. |
| 235 |
.TP |
| 236 |
.B \-t |
| 237 |
Collect timing information on the number of times probe executes |
| 238 |
and average amount of time spent in each probe-point. Also shows |
| 239 |
the derivation for each probe-point. |
| 240 |
.TP |
| 241 |
.BI \-s " NUM" |
| 242 |
Use NUM megabyte buffers for kernel-to-user data transfer per processor. |
| 243 |
The default is 16MB, or less on smaller memory machines. |
| 244 |
.TP |
| 245 |
.BI \-I " DIR" |
| 246 |
Add the given directory to the tapset search directory. See the |
| 247 |
description of pass 2 for details. |
| 248 |
.TP |
| 249 |
.BI \-D " NAME=VALUE" |
| 250 |
Add the given C preprocessor directive to the module Makefile. These can |
| 251 |
be used to override limit parameters described below. |
| 252 |
.TP |
| 253 |
.BI \-B " NAME=VALUE" |
| 254 |
In kernel-runtime mode, add the given make directive to the kernel module |
| 255 |
build's make invocation. These can be used to add or override kconfig options. |
| 256 |
For example, use |
| 257 |
.SAMPLE |
| 258 |
.B \-B CONFIG_DEBUG_INFO=y |
| 259 |
.ESAMPLE |
| 260 |
to add debugging information. |
| 261 |
.TP |
| 262 |
.BI \-B " FLAG" |
| 263 |
In dyninst-runtime mode, add the given parameter to the compiler CFLAGS used |
| 264 |
for building the dyninst shared library. For example, use |
| 265 |
.SAMPLE |
| 266 |
.B \-B \-g |
| 267 |
.ESAMPLE |
| 268 |
to add debugging information. |
| 269 |
.TP |
| 270 |
.BI \-a " ARCH" |
| 271 |
Use a cross-compilation mode for the given target architecture. This requires |
| 272 |
access to the cross-compiler and the kernel build tree, and goes along |
| 273 |
with the |
| 274 |
.SAMPLE |
| 275 |
.BR "\-B CROSS_COMPILE=arch\-tool\-prefix\-" |
| 276 |
and |
| 277 |
.BR "\-r /build/tree" |
| 278 |
.ESAMPLE |
| 279 |
options. |
| 280 |
.TP |
| 281 |
.BI \-\-modinfo " NAME=VALUE" |
| 282 |
Add the name/value pair as a MODULE_INFO macro call to the generated module. |
| 283 |
This may be useful to inform or override various module-related checks in |
| 284 |
the kernel. |
| 285 |
.TP |
| 286 |
.BI \-G " NAME=VALUE" |
| 287 |
Sets the value of global variable NAME to VALUE when staprun is invoked. |
| 288 |
This applies to scalar variables declared global in the script/tapset. |
| 289 |
.TP |
| 290 |
.BI \-R " DIR" |
| 291 |
Look for the systemtap runtime sources in the given directory. |
| 292 |
Your DIR default can be seen using "stap \-\-help". |
| 293 |
.TP |
| 294 |
.BI \-r " /DIR" |
| 295 |
Build for kernel in given build tree. Can also be set with the |
| 296 |
.I SYSTEMTAP_RELEASE |
| 297 |
environment variable. |
| 298 |
.TP |
| 299 |
.BI \-r " RELEASE" |
| 300 |
Build for kernel in build tree |
| 301 |
.BR /lib/modules/RELEASE/build . |
| 302 |
Can also be set with the |
| 303 |
.I SYSTEMTAP_RELEASE |
| 304 |
environment variable. |
| 305 |
.TP |
| 306 |
.BI \-m " MODULE" |
| 307 |
Use the given name for the generated kernel object module, instead |
| 308 |
of a unique randomized name. The generated kernel object module is |
| 309 |
copied to the current directory. |
| 310 |
.TP |
| 311 |
.BI \-d " MODULE" |
| 312 |
Add symbol/unwind information for the given module into the kernel object |
| 313 |
module. This may enable symbolic tracebacks from those modules/programs, |
| 314 |
even if they do not have an explicit probe placed into them. |
| 315 |
.TP |
| 316 |
.BI \-\-ldd |
| 317 |
Add symbol/unwind information for all user-space shared libraries suspected |
| 318 |
by ldd to be necessary for user-space binaries being probed or listed with |
| 319 |
the \-d option. Caution: this can make the probe modules considerably |
| 320 |
larger. Note that this option does not deal with kernel-space modules: |
| 321 |
see instead \-\-all\-modules below. |
| 322 |
.TP |
| 323 |
.BI \-\-all\-modules |
| 324 |
Equivalent to specifying "\-dkernel" and a "\-d" for each kernel module that is |
| 325 |
currently loaded. Caution: this can make the probe modules considerably |
| 326 |
larger. |
| 327 |
.TP |
| 328 |
.BI \-o " FILE" |
| 329 |
Send standard output to named file. In bulk mode, percpu files will |
| 330 |
start with FILE_ (FILE_cpu with \-F) followed by the cpu number. |
| 331 |
This supports strftime(3) formats for FILE. |
| 332 |
.TP |
| 333 |
.BI \-c " CMD" |
| 334 |
Start the probes, run CMD, and exit when CMD finishes. This also has |
| 335 |
the effect of setting target() to the pid of that process. Note that |
| 336 |
many probe types trigger independently of this setting. Consider |
| 337 |
including something like this to focus your script. |
| 338 |
.SAMPLE |
| 339 |
probe FOO { if (pid() != target()) next; .... } |
| 340 |
.ESAMPLE |
| 341 |
.TP |
| 342 |
.BI \-x " PID" |
| 343 |
Sets target() to PID. The script runs independently of the PID's lifespan. |
| 344 |
.TP |
| 345 |
.BI \-e " SCRIPT" |
| 346 |
Run the given SCRIPT specified on the command line. |
| 347 |
.TP |
| 348 |
.BI \-E " SCRIPT" |
| 349 |
Run the given SCRIPT specified. This SCRIPT is run in addition to the main |
| 350 |
script specified, through -e, or as a script file. This option can be repeated |
| 351 |
to run multiple scripts, and can be used in listing mode (\-l/\-L). |
| 352 |
.TP |
| 353 |
.BI \-l " PROBE" |
| 354 |
Instead of running a probe script, just list all available probe |
| 355 |
points matching the given single probe point. The pattern may include |
| 356 |
wildcards and aliases, but not comma-separated multiple probe points. |
| 357 |
The process result code will indicate failure if there are no matches. |
| 358 |
.SAMPLE |
| 359 |
% stap -e 'probe syscall.* { }' |
| 360 |
[...] |
| 361 |
% stap -l 'syscall.*' |
| 362 |
syscall.accept |
| 363 |
[...] |
| 364 |
syscall.writev |
| 365 |
.ESAMPLE |
| 366 |
.TP |
| 367 |
.BI \-L " PROBE" |
| 368 |
Similar to "\-l", but list matching probe points plus their available context variables. |
| 369 |
When -v is set with -L, the output includes duplicate probe points which are distinguished |
| 370 |
by their PC address. |
| 371 |
.SAMPLE |
| 372 |
% stap -L 'process("/lib64/libpython*.so.*").mark("*")' |
| 373 |
process("/usr/lib64/libpython2.7.so.1.0").mark("function__entry") $arg1:long $arg2:long $arg3:long |
| 374 |
process("/usr/lib64/libpython2.7.so.1.0").mark("function__return") $arg1:long $arg2:long $arg3:long |
| 375 |
process("/usr/lib64/libpython3.6m.so.1.0").mark("function__entry") $arg1:long $arg2:long $arg3:long |
| 376 |
process("/usr/lib64/libpython3.6m.so.1.0").mark("function__return") $arg1:long $arg2:long $arg3:long |
| 377 |
process("/usr/lib64/libpython3.6m.so.1.0").mark("gc__done") $arg1:long |
| 378 |
process("/usr/lib64/libpython3.6m.so.1.0").mark("gc__start") $arg1:long |
| 379 |
process("/usr/lib64/libpython3.6m.so.1.0").mark("line") $arg1:long $arg2:long $arg3:long |
| 380 |
.ESAMPLE |
| 381 |
.TP |
| 382 |
.BI \-F |
| 383 |
Without \-o option, load module and start probes, then detach from the module |
| 384 |
leaving the probes running. |
| 385 |
With \-o option, run staprun in background as a daemon and show its pid. |
| 386 |
.TP |
| 387 |
.BI \-S " size[,N]" |
| 388 |
Sets the maximum size of output file and the maximum number of output files. |
| 389 |
If the size of output file will exceed |
| 390 |
.B size |
| 391 |
megabytes, systemtap switches output file to the next file. And if the number of |
| 392 |
output files exceed |
| 393 |
.B N |
| 394 |
, systemtap removes the oldest output file. You can omit the second argument. |
| 395 |
.TP |
| 396 |
.BI \-T " TIMEOUT" |
| 397 |
Exit the script after TIMEOUT seconds. |
| 398 |
.TP |
| 399 |
.B \-\-skip\-badvars |
| 400 |
Ignore unresolvable or run-time-inaccessible context variables and |
| 401 |
substitute with 0, without errors. |
| 402 |
|
| 403 |
.TP |
| 404 |
\fB\-\-prologue\-searching\fR[=\fIWHEN\fR] |
| 405 |
Prologue-searching mode. Activate heuristics to work around incorrect debugging |
| 406 |
information for function parameter $context variables. WHEN can be either |
| 407 |
"never", "always", or "auto" (i.e. enabled by heuristic). If WHEN is missing, |
| 408 |
then "always" is assumed. If the option is missing, then "auto" is assumed. |
| 409 |
|
| 410 |
.TP |
| 411 |
.B \-\-suppress\-handler\-errors |
| 412 |
Wrap all probe handlers into something like this |
| 413 |
.SAMPLE |
| 414 |
try { ... } catch { next } |
| 415 |
.ESAMPLE |
| 416 |
block, which causes any runtime errors to be quietly suppressed. |
| 417 |
Suppressed errors do not count against |
| 418 |
.BR MAXERRORS |
| 419 |
limits. In this mode, the |
| 420 |
.BR MAXSKIPPED |
| 421 |
limits are also suppressed, so that many errors and skipped probes |
| 422 |
may be accumulated during a script's runtime. Any overall counts will |
| 423 |
still be reported at shutdown. |
| 424 |
|
| 425 |
.TP |
| 426 |
.BI \-\-compatible " VERSION" |
| 427 |
Suppress recent script language or tapset changes which are incompatible |
| 428 |
with given older version of systemtap. This may be useful if a much older |
| 429 |
systemtap script fails to run. See the DEPRECATION section for more |
| 430 |
details. |
| 431 |
|
| 432 |
.TP |
| 433 |
.BI \-\-check\-version |
| 434 |
This option is used to check if the active script has any constructs |
| 435 |
that may be systemtap version specific. See the DEPRECATION section |
| 436 |
for more details. |
| 437 |
|
| 438 |
.TP |
| 439 |
.BI \-\-clean\-cache |
| 440 |
This option prunes stale entries from the cache directory. This is normally |
| 441 |
done automatically after successful runs, but this option will trigger the |
| 442 |
cleanup manually and then exit. See the CACHING section for more details about |
| 443 |
cache limits. |
| 444 |
|
| 445 |
.TP |
| 446 |
\fB\-\-color\fR[=\fIWHEN\fR], \fB\-\-colour\fR[=\fIWHEN\fR] |
| 447 |
This option controls coloring of error messages. WHEN can be either "never", |
| 448 |
"always", or "auto" (i.e. enable only if at a terminal). If WHEN is missing, |
| 449 |
then "always" is assumed. If the option is missing, then "auto" is assumed. |
| 450 |
|
| 451 |
Colors can be modified using the SYSTEMTAP_COLORS environment variable. The |
| 452 |
format must be of the form |
| 453 |
.nh |
| 454 |
\fBkey1=val1:key2=val2:key3=val3\fR ...etc. |
| 455 |
.hy |
| 456 |
Valid keys are |
| 457 |
.nh |
| 458 |
"error", "warning", "source", "caret", and "token". |
| 459 |
.hy |
| 460 |
Values constitute Select Graphic Rendition (SGR) parameter(s). Consult the |
| 461 |
documentation of your terminal for the SGRs it supports. As an example, the |
| 462 |
default colors would be expressed as |
| 463 |
.nh |
| 464 |
\fBerror=01;31:warning=00;33:source=00;34:caret=01:token=01\fR. |
| 465 |
.hy |
| 466 |
If SYSTEMTAP_COLORS is absent, the default colors will be used. If it is empty |
| 467 |
or invalid, coloring is turned off. |
| 468 |
|
| 469 |
.TP |
| 470 |
.BI \-\-disable\-cache |
| 471 |
This option disables all use of the cache directory. No files will be either |
| 472 |
read from or written to the cache. |
| 473 |
|
| 474 |
.TP |
| 475 |
.BI \-\-poison\-cache |
| 476 |
This option treats files in the cache directory as invalid. No files will be |
| 477 |
read from the cache, but resulting files from this run will still be written to |
| 478 |
the cache. This is meant as a troubleshooting aid when stap's cached behavior |
| 479 |
seems to be misbehaving. If it helped, there is a probably a bug in systemtap |
| 480 |
that the developers would like you to report. |
| 481 |
|
| 482 |
.TP |
| 483 |
\fB\-\-privilege\fR[=\fIstapusr\fR | =\fIstapsys\fR | =\fIstapdev\fR] |
| 484 |
This option instructs \fIstap\fR to examine the script looking for constructs |
| 485 |
which are not allowed for the specified privilege level (see \fIUNPRIVILEGED USERS\fR). |
| 486 |
Compilation fails if any such |
| 487 |
constructs are used. |
| 488 |
If \fIstapusr\fR or \fIstapsys\fR are specified when using a compile server |
| 489 |
(see \fI\-\-use\-server\fR), |
| 490 |
the server will examine the script and, if compilation succeeds, the |
| 491 |
server will cryptographically sign the resulting kernel module, certifying |
| 492 |
that is it safe for use by users at the specified privilege level. |
| 493 |
|
| 494 |
If \fI\-\-privilege\fR has not been specified, |
| 495 |
\fI\-pN\fR has not been specified with N < 5, |
| 496 |
and the invoking user is not |
| 497 |
\fIroot\fR, and is not a member of the group \fIstapdev\fR, |
| 498 |
then \fIstap\fR will automatically |
| 499 |
add the appropriate \fI\-\-privilege\fR option to the options already specified. |
| 500 |
|
| 501 |
.TP |
| 502 |
.BI \-\-unprivileged |
| 503 |
This option is equivalent to \fI\-\-privilege=stapusr\fR. |
| 504 |
|
| 505 |
.TP |
| 506 |
\fB\-\-use\-server\fR[=\fIHOSTNAME\fR[\fI:PORT\fR] | =\fIIP_ADDRESS\fR[\fI:PORT\fR] | =\fICERT_SERIAL\fR] |
| 507 |
Specify compile\-server(s) to be used for compilation and/or in conjunction |
| 508 |
with |
| 509 |
.I \-\-list\-servers |
| 510 |
and |
| 511 |
.I \-\-trust\-servers |
| 512 |
(see below) for listing. If no argument is |
| 513 |
supplied, then the default in unprivileged mode (see |
| 514 |
.IR \-\-privilege ) |
| 515 |
is to select compatible servers which are trusted as SSL peers and as |
| 516 |
module signers and currently online. Otherwise the default is to select |
| 517 |
compatible servers which are trusted as SSL peers |
| 518 |
and currently online. |
| 519 |
.I \-\-use\-server |
| 520 |
may be |
| 521 |
specified more than once, in which case a list of servers is accumulated |
| 522 |
in the order specified. Servers may be specified by host name, ip address, or |
| 523 |
by certificate serial number (obtained using |
| 524 |
.IR \-\-list\-servers ). |
| 525 |
The latter is most commonly used when adding or revoking |
| 526 |
trust in a server (see |
| 527 |
.I \-\-trust\-servers |
| 528 |
below). If a server is specified by host name or ip address, then an optional |
| 529 |
port number may be specified. This is useful for accessing servers which are |
| 530 |
not on the local network or to specify a particular server. |
| 531 |
|
| 532 |
IP addresses may be IPv4 or IPv6 addresses. |
| 533 |
|
| 534 |
If a particular IPv6 address is link local and exists |
| 535 |
on more than one interface, the intended interface may be specified by appending the address with |
| 536 |
a percent sign (%) followed by the intended interface name. For example, |
| 537 |
"fe80::5eff:35ff:fe07:55ca%eth0". |
| 538 |
|
| 539 |
In order to specify a port number with an IPv6 address, it is necessary to enclose the IPv6 address |
| 540 |
in square brackets ([]) in order to separate the port number from the rest of the address. For |
| 541 |
example, "[fe80::5eff:35ff:fe07:55ca]:5000" or "[fe80::5eff:35ff:fe07:55ca%eth0]:5000". |
| 542 |
|
| 543 |
If \fI\-\-use\-server\fR has not been specified, |
| 544 |
\fI\-pN\fR has not been specified with N < 5, |
| 545 |
and the invoking user not \fIroot\fR, |
| 546 |
is not a member of the group \fIstapdev\fR, but is a member of the group |
| 547 |
\fIstapusr\fR, then \fIstap\fR will automatically |
| 548 |
add \fI\-\-use\-server\fR to the options already specified. |
| 549 |
|
| 550 |
.TP |
| 551 |
\fB\-\-use\-server\-on\-error\fR[=\fByes\fR|=\fBno\fR] |
| 552 |
Instructs stap to retry compilation of a script using a compile server if |
| 553 |
compilation on the local host fails in a manner which suggests that it might |
| 554 |
succeed using a server. |
| 555 |
If this option is not specified, the default is \fIno\fR. |
| 556 |
If no argument is provided, then the default |
| 557 |
is \fIyes\fR. Compilation will be retried for certain types of errors |
| 558 |
(e.g. insufficient data or resources) which may not occur during |
| 559 |
re\-compilation by a compile |
| 560 |
server. Compile servers will be selected automatically for the |
| 561 |
re\-compilation attempt as if \fI\-\-use\-server\fR was specified with no |
| 562 |
arguments. |
| 563 |
|
| 564 |
.TP |
| 565 |
.BI \-\-list\-servers "[=SERVERS]" |
| 566 |
Display the status of the requested |
| 567 |
.IR SERVERS , |
| 568 |
where |
| 569 |
.I SERVERS |
| 570 |
is a comma\-separated |
| 571 |
list of server attributes. The list of attributes is combined to filter the |
| 572 |
list of servers displayed. Supported attributes are: |
| 573 |
.RS |
| 574 |
.TP |
| 575 |
.BI all |
| 576 |
specifies all known servers (trusted SSL peers, trusted module signers, online |
| 577 |
servers). |
| 578 |
.TP |
| 579 |
.BI specified |
| 580 |
specifies servers specified using |
| 581 |
.IR \-\-use\-server . |
| 582 |
.TP |
| 583 |
.BI online |
| 584 |
filters the output by retaining information about servers which are currently |
| 585 |
online. |
| 586 |
.TP |
| 587 |
.BI trusted |
| 588 |
filters the output by retaining information about servers which are trusted as |
| 589 |
SSL peers. |
| 590 |
.TP |
| 591 |
.BI signer |
| 592 |
filters the output by retaining information about servers which are trusted as |
| 593 |
module signers (see |
| 594 |
.IR \-\-privilege ). |
| 595 |
.TP |
| 596 |
.BI compatible |
| 597 |
filters the output by retaining information about servers which are compatible |
| 598 |
with the current kernel release and architecture. |
| 599 |
.RE |
| 600 |
.IP |
| 601 |
If no argument is provided, then the default is |
| 602 |
.BR specified . |
| 603 |
If no servers were specified using |
| 604 |
.IR \-\-use\-server , |
| 605 |
then the default servers for |
| 606 |
.IR \-\-use\-server |
| 607 |
are listed. |
| 608 |
|
| 609 |
Note that |
| 610 |
.IR \-\-list\-servers |
| 611 |
uses the |
| 612 |
.IR avahi\-daemon |
| 613 |
service to detect online servers. If this service is not available, then |
| 614 |
.IR \-\-list\-servers |
| 615 |
will fail to detect any |
| 616 |
.IR online |
| 617 |
servers. In order for |
| 618 |
.IR \-\-list\-servers |
| 619 |
to detect servers listening on IPv6 addresses, the |
| 620 |
.IR avahi\-daemon |
| 621 |
configuration file |
| 622 |
.IR /etc/avahi/avahi-daemon.conf |
| 623 |
must contain an active "use-ipv6=yes" line. The service must be restarted after adding this line |
| 624 |
in order for IPv6 to be enabled. |
| 625 |
|
| 626 |
.TP |
| 627 |
.BI \-\-trust\-servers "[=TRUST_SPEC]" |
| 628 |
Grant or revoke trust in compile\-servers, specified using |
| 629 |
.IR \-\-use\-server |
| 630 |
as specified by TRUST_SPEC, |
| 631 |
where TRUST_SPEC is a comma\-separated list specifying the trust which is to |
| 632 |
be granted or revoked. Supported elements are: |
| 633 |
.RS |
| 634 |
.TP |
| 635 |
.BI ssl |
| 636 |
trust the specified servers as SSL peers. |
| 637 |
.TP |
| 638 |
.BI signer |
| 639 |
trust the specified servers as module signers (see |
| 640 |
.IR \-\-privilege ). |
| 641 |
Only root can specify |
| 642 |
.BR signer. |
| 643 |
.TP |
| 644 |
.BI all\-users |
| 645 |
grant trust as an ssl peer for all users on the local host. The default is |
| 646 |
to grant trust as an ssl peer for the current user only. Trust as a module |
| 647 |
signer is always granted for all users. Only root can specify |
| 648 |
.BR all\-users . |
| 649 |
.TP |
| 650 |
.BI revoke |
| 651 |
revoke the specified trust. The default is to grant it. |
| 652 |
.TP |
| 653 |
.BI no\-prompt |
| 654 |
do not prompt the user for confirmation before carrying out the requested |
| 655 |
action. The default is to prompt the user for confirmation. |
| 656 |
.RE |
| 657 |
.IP |
| 658 |
If no argument is provided, then the default is |
| 659 |
.BR ssl . |
| 660 |
If no servers were specified using |
| 661 |
.IR \-\-use\-server , |
| 662 |
then no trust will be granted or revoked. |
| 663 |
.IP |
| 664 |
Unless \fBno\-prompt\fR has been specified, |
| 665 |
the user will be prompted to confirm the trust to be granted or revoked before |
| 666 |
the operation is performed. |
| 667 |
|
| 668 |
.TP |
| 669 |
.BI \-\-sign-module |
| 670 |
Sign the module with a MOK (Machine Owner Key) on UEFI/SecureBoot systems. |
| 671 |
See the SECUREBOOT section for more details. |
| 672 |
|
| 673 |
.TP |
| 674 |
.BI \-\-dump-probe-types |
| 675 |
Dumps a list of supported probe types and exits. If |
| 676 |
.IR \-\-privilege=stapusr |
| 677 |
is also specified, the list will be limited to probe types available to unprivileged users. |
| 678 |
|
| 679 |
.TP |
| 680 |
.BI \-\-dump-probe-aliases |
| 681 |
Dumps a list of all probe aliases found in library files and exits. |
| 682 |
|
| 683 |
.TP |
| 684 |
.BI \-\-dump-functions |
| 685 |
Dumps a list of all the public functions found in library files and exits. Also includes |
| 686 |
their parameters and types. A function of type 'unknown' indicates a function |
| 687 |
that does not return a value. Note that not all function/parameter types may be |
| 688 |
resolved (these are also shown by 'unknown'). This features is very |
| 689 |
memory-intensive and thus may not work properly with \fI\-\-use-server\fR if the |
| 690 |
target server imposes an rlimit on process memory (i.e. through the |
| 691 |
\fI~stap-server/.systemtap/rc\fR configuration file, see \fIstap-server\fR(8)). |
| 692 |
|
| 693 |
.TP |
| 694 |
.BI \-\-remote " URL" |
| 695 |
Set the execution target to the given host. This option may be |
| 696 |
repeated to target multiple execution targets. Passes 1-4 are |
| 697 |
completed locally as normal to build the script, and then pass 5 will |
| 698 |
copy the module to the target and run it. Acceptable URL forms include: |
| 699 |
.RS |
| 700 |
.TP |
| 701 |
\fB[USER@]HOSTNAME\fR, \fBssh://[USER@]HOSTNAME\fR |
| 702 |
This mode uses ssh, optionally using a username not matching your own. If a |
| 703 |
custom ssh_config file is in use, add \fBSendEnv LANG\fR to retain |
| 704 |
internationalization functionality. |
| 705 |
.TP |
| 706 |
\fBlibvirt://DOMAIN\fR, \fBlibvirt://DOMAIN/LIBVIRT_URI\fR |
| 707 |
This mode uses \fIstapvirt\fR to execute the script on a domain managed by |
| 708 |
libvirt. Optionally, LIBVIRT_URI may be specified to connect to a specific |
| 709 |
driver and/or a remote host. For example, to connect to the local privileged |
| 710 |
QEMU driver, use: |
| 711 |
.SAMPLE |
| 712 |
\-\-remote libvirt://MyDomain/qemu:///system |
| 713 |
.ESAMPLE |
| 714 |
See the page at |
| 715 |
.nh |
| 716 |
<http://libvirt.org/uri.html> |
| 717 |
.hy |
| 718 |
for supported URIs. Also see \fIstapvirt\fR(1) for more information on how to |
| 719 |
prepare the domain for stap probing. |
| 720 |
.TP |
| 721 |
\fBunix:PATH\fR |
| 722 |
This mode connects to a UNIX socket. This can be used with a QEMU virtio-serial |
| 723 |
port for executing scripts inside a running virtual machine. |
| 724 |
.TP |
| 725 |
\fBdirect://\fR |
| 726 |
Special loopback mode to run on the local host. |
| 727 |
.RE |
| 728 |
.IP |
| 729 |
|
| 730 |
.TP |
| 731 |
.BI \-\-remote\-prefix |
| 732 |
Prefix each line of remote output with "N: ", where N is the index of the remote |
| 733 |
execution target from which the given line originated. |
| 734 |
|
| 735 |
.TP |
| 736 |
.BI \-\-download\-debuginfo "[=OPTION]" |
| 737 |
Enable, disable or set a timeout for the automatic debuginfo downloading feature |
| 738 |
offered by abrt as specified by OPTION, where OPTION is one of the following: |
| 739 |
.RS |
| 740 |
.TP |
| 741 |
.BI yes |
| 742 |
enable automatic downloading of debuginfo with no timeout. This is the same |
| 743 |
as not providing an OPTION value to |
| 744 |
.IR \-\-download\-debuginfo |
| 745 |
.TP |
| 746 |
.BI no |
| 747 |
explicitly disable automatic downloading of debuginfo. This is the same as |
| 748 |
not using the option at all. |
| 749 |
.TP |
| 750 |
.BI ask |
| 751 |
show abrt output, and ask before continuing download. No timeout will be set. |
| 752 |
.TP |
| 753 |
.BI <timeout> |
| 754 |
specify a timeout as a positive number to stop the download if it is taking |
| 755 |
longer than <timeout> seconds. |
| 756 |
.RE |
| 757 |
.IP |
| 758 |
|
| 759 |
.TP |
| 760 |
.BI \-\-rlimit-as "=NUM" |
| 761 |
Specify the maximum size of the process's virtual memory (address space), |
| 762 |
in bytes. |
| 763 |
|
| 764 |
.TP |
| 765 |
.BI \-\-rlimit-cpu "=NUM" |
| 766 |
Specify the CPU time limit, in seconds. |
| 767 |
|
| 768 |
.TP |
| 769 |
.BI \-\-rlimit-nproc "=NUM" |
| 770 |
Specify the maximum number of processes that can be created. |
| 771 |
|
| 772 |
.TP |
| 773 |
.BI \-\-rlimit-stack "=NUM" |
| 774 |
Specify the maximum size of the process stack, in bytes. |
| 775 |
|
| 776 |
.TP |
| 777 |
.BI \-\-rlimit-fsize "=NUM" |
| 778 |
Specify the maximum size of files that the process may create, in bytes. |
| 779 |
|
| 780 |
.TP |
| 781 |
.BI \-\-sysroot "=DIR" |
| 782 |
Specify sysroot directory where target files (executables, libraries, etc.) |
| 783 |
are located. With \fI\-r RELEASE\fR, the sysroot will be searched for the |
| 784 |
appropriate kernel build directory. With \fI\-r /DIR\fR, however, the sysroot |
| 785 |
will not be used to find the kernel build. |
| 786 |
|
| 787 |
.TP |
| 788 |
.BI \-\-sysenv "=VAR=VALUE" |
| 789 |
Provide an alternate value for an environment variable where the value on a |
| 790 |
remote system differs. Path variables (e.g. PATH, LD_LIBRARY_PATH) are assumed |
| 791 |
to be relative to the directory provided by \fI\-\-sysroot\fR, if provided. |
| 792 |
|
| 793 |
.TP |
| 794 |
.BI \-\-suppress\-time\-limits |
| 795 |
Disable \-DSTP_OVERLOAD related options as well as \-DMAXACTION and \-DMAXTRYLOCK. |
| 796 |
This option requires guru mode. |
| 797 |
|
| 798 |
.TP |
| 799 |
.BI \-\-runtime "=MODE" |
| 800 |
Set the pass-5 runtime mode. Valid options are \fIkernel\fR (default), |
| 801 |
\fIdyninst\fR and \fIbpf\fR. See |
| 802 |
.BR ALTERNATE\ RUNTIMES |
| 803 |
below for more information. |
| 804 |
|
| 805 |
.TP |
| 806 |
.BI \-\-dyninst |
| 807 |
Shorthand for \fI\-\-runtime=dyninst\fR. |
| 808 |
|
| 809 |
.TP |
| 810 |
.BI \-\-bpf |
| 811 |
Shorthand for \fI\-\-runtime=bpf\fR. |
| 812 |
|
| 813 |
.TP |
| 814 |
.BI \-\-save-uprobes |
| 815 |
On machines that require SystemTap to build its own uprobes module (kernels |
| 816 |
prior to version 3.5), this option instructs SystemTap to also save a copy of |
| 817 |
the module in the current directory (creating a new "uprobes" directory first). |
| 818 |
|
| 819 |
.TP |
| 820 |
.BI \-\-target-namespaces "=PID" |
| 821 |
Allow for a set of target namespaces to be set based on the namespaces the |
| 822 |
given PID is in. This is for namespace\-aware tapset functions. If the target |
| 823 |
namespaces was not set, the target defaults to the stap process' |
| 824 |
namespaces. |
| 825 |
|
| 826 |
.TP |
| 827 |
.BI \-\-monitor "=INTERVAL" |
| 828 |
Enables an interface to display status information about the module(uptime, |
| 829 |
module name, invoker uid, memory sizes, global variables, list of probes with |
| 830 |
their statistics). An optional argument INTERVAL can be supplied to set the |
| 831 |
refresh rate in seconds of the status window. The module can also be controlled by a list |
| 832 |
of commands using the following keys: |
| 833 |
.RS |
| 834 |
.TP |
| 835 |
.BI c |
| 836 |
Resets all global variables to their initial values or zeroes them if they |
| 837 |
did not have an initial value. |
| 838 |
.TP |
| 839 |
.BI s |
| 840 |
Rotates the attribute used to sort the list of probes. |
| 841 |
.TP |
| 842 |
.BI t |
| 843 |
Brings up a prompt to allow toggling(on/off) of probes by index. Probe points |
| 844 |
are still affected by their conditions. |
| 845 |
.TP |
| 846 |
.BI r |
| 847 |
Resumes the script by toggling on all probes. |
| 848 |
.TP |
| 849 |
.BI p |
| 850 |
Pauses the script by toggling off all probes. |
| 851 |
.TP |
| 852 |
.BI x |
| 853 |
Hides/shows the status window. This allows for more output to be seen. |
| 854 |
.TP |
| 855 |
.BI navigation-keys |
| 856 |
The navigation keys can be used to scroll up and down the windows. |
| 857 |
.TP |
| 858 |
.BI Tab |
| 859 |
Toggle scrolling between status and output windows. |
| 860 |
.RE |
| 861 |
|
| 862 |
.TP |
| 863 |
.BI \-\-example |
| 864 |
This option is used to run example scripts without having to enter the |
| 865 |
entire path to the script. Example scripts can be found in the directory |
| 866 |
specified in the |
| 867 |
.IR stappaths (7) |
| 868 |
manual page. |
| 869 |
|
| 870 |
.TP |
| 871 |
.BI \-\-no-global-var-display |
| 872 |
This option is used to disable the automatic logging of unused global |
| 873 |
variables at the end of a stap session. |
| 874 |
|
| 875 |
.TP |
| 876 |
.B \-\-language\-server |
| 877 |
Language server mode. Start a language server which will communicate via |
| 878 |
stdio. The language server will respect stap verbosity. |
| 879 |
|
| 880 |
.TP |
| 881 |
.B \-\-build\-as |
| 882 |
Execute passes 1-4 under specified user to increase safety. This approach |
| 883 |
may have limitations. Unprivileged users might not have access to kallsyms |
| 884 |
or /proc. At the RPM install time, the stapunpriv user is created, so stap |
| 885 |
can be invoked with --build-as=stapunpriv. |
| 886 |
|
| 887 |
.SH ARGUMENTS |
| 888 |
|
| 889 |
Any additional arguments on the command line are passed to the script |
| 890 |
parser for substitution. See below. |
| 891 |
|
| 892 |
.SH SCRIPT LANGUAGE |
| 893 |
|
| 894 |
The systemtap script language resembles |
| 895 |
.IR awk " and " C . |
| 896 |
There are two main outermost constructs: probes and functions. Within |
| 897 |
these, statements and expressions use C-like operator syntax and |
| 898 |
precedence. |
| 899 |
|
| 900 |
.SS GENERAL SYNTAX |
| 901 |
Whitespace is ignored. Three forms of comments are supported: |
| 902 |
.RS |
| 903 |
.br |
| 904 |
.BR # " ... shell style, to the end of line, except for $# and @#" |
| 905 |
.br |
| 906 |
.BR // " ... C++ style, to the end of line" |
| 907 |
.br |
| 908 |
.BR /* " ... C style ... " */ |
| 909 |
.RE |
| 910 |
Literals are either strings enclosed in double-quotes (passing through |
| 911 |
the usual C escape codes with backslashes, and with adjacent string |
| 912 |
literals glued together, also as in C), or integers (in decimal, |
| 913 |
hexadecimal, or octal, using the same notation as in C). All strings |
| 914 |
are limited in length to some reasonable value (a few hundred bytes). |
| 915 |
Integers are 64-bit signed quantities, although the parser also |
| 916 |
accepts (and wraps around) values above positive 2**63. |
| 917 |
.PP |
| 918 |
In addition, script arguments given at the end of the command line may |
| 919 |
be inserted. Use |
| 920 |
.B $1 ... $<NN> |
| 921 |
for insertion unquoted, |
| 922 |
.B @1 ... @<NN> |
| 923 |
for insertion as a string literal. The number of arguments may be accessed |
| 924 |
through |
| 925 |
.B $# |
| 926 |
(as an unquoted number) or through |
| 927 |
.B @# |
| 928 |
(as a quoted number). These may be used at any place a token may begin, |
| 929 |
including within the preprocessing stage. Reference to an argument |
| 930 |
number beyond what was actually given is an error. |
| 931 |
|
| 932 |
.SS PREPROCESSING |
| 933 |
A simple conditional preprocessing stage is run as a part of parsing. |
| 934 |
The general form is similar to the |
| 935 |
.RB cond " ? " exp1 " : " exp2 |
| 936 |
ternary operator: |
| 937 |
.SAMPLE |
| 938 |
.BR %( " CONDITION " %? " TRUE-TOKENS " %) |
| 939 |
.BR %( " CONDITION " %? " TRUE-TOKENS " %: " FALSE-TOKENS " %) |
| 940 |
.ESAMPLE |
| 941 |
The CONDITION is either an expression whose format is determined by its |
| 942 |
first keyword, or a string literals comparison or a numeric literals |
| 943 |
comparison. It can be also composed of many alternatives and conjunctions |
| 944 |
of CONDITIONs (meant as in previous sentence) using || and && respectively. |
| 945 |
However, parentheses are not supported yet, so remembering that conjunction |
| 946 |
takes precedence over alternative is important. |
| 947 |
.PP |
| 948 |
If the first part is the identifier |
| 949 |
.BR kernel_vr " or " kernel_v |
| 950 |
to refer to the kernel version number, with ("2.6.13\-1.322FC3smp") or |
| 951 |
without ("2.6.13") the release code suffix, then |
| 952 |
the second part is one of the six standard numeric comparison operators |
| 953 |
.BR < ", " <= ", " == ", " != ", " > ", and " >= , |
| 954 |
and the third part is a string literal that contains an RPM-style |
| 955 |
version-release value. The condition is deemed satisfied if the |
| 956 |
version of the target kernel (as optionally overridden by the |
| 957 |
.BR \-r |
| 958 |
option) compares to the given version string. The comparison is |
| 959 |
performed by the glibc function |
| 960 |
.BR strverscmp . |
| 961 |
As a special case, if the operator is for simple equality |
| 962 |
.RB ( == ), |
| 963 |
or inequality |
| 964 |
.RB ( != ), |
| 965 |
and the third part contains any wildcard characters |
| 966 |
.RB ( * " or " ? " or " [ ")," |
| 967 |
then the expression is treated as a wildcard (mis)match as evaluated |
| 968 |
by |
| 969 |
.BR fnmatch . |
| 970 |
.PP |
| 971 |
If, on the other hand, the first part is the identifier |
| 972 |
.BR arch |
| 973 |
to refer to the processor architecture (as named by the kernel |
| 974 |
build system ARCH/SUBARCH), then the second |
| 975 |
part is one of the two string comparison operators |
| 976 |
.BR == " or " != , |
| 977 |
and the third part is a string literal for matching it. This |
| 978 |
comparison is a wildcard (mis)match. |
| 979 |
.PP |
| 980 |
Similarly, if the first part is an identifier like |
| 981 |
.BR CONFIG_something |
| 982 |
to refer to a kernel configuration option, then the second part is |
| 983 |
.BR == " or " != , |
| 984 |
and the third part is a string literal for matching the value |
| 985 |
(commonly "y" or "m"). Nonexistent or unset kernel configuration |
| 986 |
options are represented by the empty string. This comparison is also |
| 987 |
a wildcard (mis)match. |
| 988 |
.PP |
| 989 |
If the first part is the identifier |
| 990 |
.BR systemtap_v , |
| 991 |
the test refers to the systemtap compatibility version, which may be |
| 992 |
overridden for old scripts with the |
| 993 |
.BI \-\-compatible |
| 994 |
flag. The comparison operator is as is for |
| 995 |
.BR kernel_v |
| 996 |
and the right operand is a version string. See also the DEPRECATION |
| 997 |
section below. |
| 998 |
.PP |
| 999 |
If the first part is the identifier |
| 1000 |
.BR systemtap_privilege , |
| 1001 |
the test refers to the privilege level that the systemtap script is |
| 1002 |
compiled with. Here the second part is |
| 1003 |
.BR == " or " != , |
| 1004 |
and the third part is a string literal, either "stapusr" or "stapsys" |
| 1005 |
or "stapdev". |
| 1006 |
.PP |
| 1007 |
If the first part is the identifier |
| 1008 |
.BR guru_mode , |
| 1009 |
the test refers to if the systemtap script is |
| 1010 |
compiled with guru_mode. Here the second part is |
| 1011 |
.BR == " or " != , |
| 1012 |
and the third part is a number, either 1 or 0. |
| 1013 |
.PP |
| 1014 |
If the first part is the identifier |
| 1015 |
.BR runtime , |
| 1016 |
the test refers to the systemtap runtime mode. See |
| 1017 |
.BR ALTERNATE\ RUNTIMES |
| 1018 |
below for more information on runtimes. |
| 1019 |
The second |
| 1020 |
part is one of the two string comparison operators |
| 1021 |
.BR == " or " != , |
| 1022 |
and the third part is a string literal for matching it. This |
| 1023 |
comparison is a wildcard (mis)match. |
| 1024 |
.PP |
| 1025 |
Otherwise, the CONDITION is expected to be a comparison between two string |
| 1026 |
literals or two numeric literals. In this case, the arguments are the only |
| 1027 |
variables usable. |
| 1028 |
.PP |
| 1029 |
The TRUE-TOKENS and FALSE-TOKENS are zero or more general parser |
| 1030 |
tokens (possibly including nested preprocessor conditionals), and are |
| 1031 |
passed into the input stream if the condition is true or false. For |
| 1032 |
example, the following code induces a parse error unless the target |
| 1033 |
kernel version is newer than 2.6.5: |
| 1034 |
.SAMPLE |
| 1035 |
%( kernel_v <= "2.6.5" %? **ERROR** %) # invalid token sequence |
| 1036 |
.ESAMPLE |
| 1037 |
The following code might adapt to hypothetical kernel version drift: |
| 1038 |
.SAMPLE |
| 1039 |
probe kernel.function ( |
| 1040 |
%( kernel_v <= "2.6.12" %? "__mm_do_fault" %: |
| 1041 |
%( kernel_vr == "2.6.13*smp" %? "do_page_fault" %: |
| 1042 |
UNSUPPORTED %) %) |
| 1043 |
) { /* ... */ } |
| 1044 |
|
| 1045 |
%( arch == "ia64" %? |
| 1046 |
probe syscall.vliw = kernel.function("vliw_widget") {} |
| 1047 |
%) |
| 1048 |
.ESAMPLE |
| 1049 |
|
| 1050 |
.SS PREPROCESSOR MACROS |
| 1051 |
The preprocessor also supports a simple macro facility, run as a |
| 1052 |
separate pass before conditional preprocessing. |
| 1053 |
.PP |
| 1054 |
Macros are defined using the following construct: |
| 1055 |
.SAMPLE |
| 1056 |
@define NAME %( BODY %) |
| 1057 |
@define NAME(PARAM_1, PARAM_2, ...) %( BODY %) |
| 1058 |
.ESAMPLE |
| 1059 |
Macros, and parameters inside a macro body, are both invoked by |
| 1060 |
prefixing the macro name with an @ symbol: |
| 1061 |
.SAMPLE |
| 1062 |
@define foo %( x %) |
| 1063 |
@define add(a,b) %( ((@a)+(@b)) %) |
| 1064 |
|
| 1065 |
@foo = @add(2,2) |
| 1066 |
.ESAMPLE |
| 1067 |
.PP |
| 1068 |
Macro expansion is currently performed in a separate pass before |
| 1069 |
conditional compilation. Therefore, both TRUE- and FALSE-tokens in |
| 1070 |
conditional expressions will be macroexpanded regardless of how the |
| 1071 |
condition is evaluated. This can sometimes lead to errors: |
| 1072 |
.SAMPLE |
| 1073 |
// The following results in a conflict: |
| 1074 |
%( CONFIG_UPROBE == "y" %? |
| 1075 |
@define foo %( process.syscall %) |
| 1076 |
%: |
| 1077 |
@define foo %( **ERROR** %) |
| 1078 |
%) |
| 1079 |
|
| 1080 |
// The following works properly as expected: |
| 1081 |
@define foo %( |
| 1082 |
%( CONFIG_UPROBE == "y" %? process.syscall %: **ERROR** %) |
| 1083 |
%) |
| 1084 |
.ESAMPLE |
| 1085 |
The first example is incorrect because both @defines are evaluated in |
| 1086 |
a pass prior to the conditional being evaluated. |
| 1087 |
|
| 1088 |
Normally, a macro definition is local to the file it occurs in. Thus, |
| 1089 |
defining a macro in a tapset does not make it available to the user of |
| 1090 |
the tapset. Publically available library macros can be defined by |
| 1091 |
including .stpm files on the tapset search path. These files may only |
| 1092 |
contain @define constructs, which become visible across all tapsets |
| 1093 |
and user scripts. Optionally, within the .stpm files, a public macro |
| 1094 |
definition can be surrounded by a preprocessor conditional as described |
| 1095 |
above. |
| 1096 |
|
| 1097 |
.SS CONSTANTS |
| 1098 |
Tapsets or guru-mode user scripts can access header file constant tokens, |
| 1099 |
typically macros, using built-in @const() operator. The respective header |
| 1100 |
file inclusion is possible either via the tapset library, or using a |
| 1101 |
top-level guru mode embedded-C construct. This results in appropriate |
| 1102 |
embedded C pragma comments setting. |
| 1103 |
.SAMPLE |
| 1104 |
@const("STP_SKIP_BADVARS") |
| 1105 |
.ESAMPLE |
| 1106 |
|
| 1107 |
.SS VARIABLES |
| 1108 |
Identifiers for variables and functions are an alphanumeric sequence, |
| 1109 |
and may include \fB_\fR and \fB$\fR characters. They may not start with a |
| 1110 |
plain digit, as in C. Each variable is by default local to the probe |
| 1111 |
or function statement block within which it is mentioned, and therefore |
| 1112 |
its scope and lifetime is limited to a particular probe or function |
| 1113 |
invocation. |
| 1114 |
.PP |
| 1115 |
Scalar variables are implicitly typed as either string or integer. |
| 1116 |
Associative arrays also have a string or integer value, and a |
| 1117 |
tuple of strings and/or integers serving as a key. Here are a |
| 1118 |
few basic expressions. |
| 1119 |
.SAMPLE |
| 1120 |
var1 = 5 |
| 1121 |
var2 = "bar" |
| 1122 |
array1 [pid()] = "name" # single numeric key |
| 1123 |
array2 ["foo",4,i++] += 5 # vector of string/num/num keys |
| 1124 |
if (["hello",5,4] in array2) println ("yes") # membership test |
| 1125 |
.ESAMPLE |
| 1126 |
.PP |
| 1127 |
The translator performs |
| 1128 |
.I type inference |
| 1129 |
on all identifiers, including array indexes and function parameters. |
| 1130 |
Inconsistent type-related use of identifiers signals an error. |
| 1131 |
.PP |
| 1132 |
Variables may be declared global, so that they are shared amongst all |
| 1133 |
probes and functions and live as long as the entire systemtap session. There is one |
| 1134 |
namespace for all global variables, regardless of which script file |
| 1135 |
they are found within. Concurrent access to global variables is |
| 1136 |
automatically protected with locks, see the |
| 1137 |
.B SAFETY AND SECURITY |
| 1138 |
section for more details. A global declaration may be written at the |
| 1139 |
outermost level anywhere, not within a block of code. Global |
| 1140 |
variables which are written but never read will be displayed |
| 1141 |
automatically at session shutdown. The translator will |
| 1142 |
infer for each its value type, and if it is used as an array, its key |
| 1143 |
types. Optionally, scalar globals may be initialized with a string |
| 1144 |
or number literal. The following declaration marks variables as global. |
| 1145 |
.SAMPLE |
| 1146 |
.BR global " var1" , " var2" , " var3=4" |
| 1147 |
.ESAMPLE |
| 1148 |
.PP |
| 1149 |
Global variables can also be set as module options. One can do this by either |
| 1150 |
using the \-G option, or the module must first be compiled using stap \-p4. |
| 1151 |
Global variables can then be set on the command line when calling staprun on |
| 1152 |
the module generated by stap \-p4. See |
| 1153 |
.IR staprun (8) |
| 1154 |
for more information. |
| 1155 |
.PP |
| 1156 |
The scope of a global variable may be limited to a tapset or |
| 1157 |
user script file using private keyword. The global keyword is optional when |
| 1158 |
defining a private global variable. Following declaration marks var1 and var2 |
| 1159 |
private globals. |
| 1160 |
.SAMPLE |
| 1161 |
.BR private " global" " var1=2" |
| 1162 |
.BR private " var2" |
| 1163 |
.ESAMPLE |
| 1164 |
.PP |
| 1165 |
Arrays are limited in size by the MAXMAPENTRIES variable -- see the |
| 1166 |
.B SAFETY AND SECURITY |
| 1167 |
section for details. Optionally, global arrays may be declared with a |
| 1168 |
maximum size in brackets, overriding MAXMAPENTRIES for that array only. |
| 1169 |
Note that this doesn't indicate the type of keys for the array, just the |
| 1170 |
size. |
| 1171 |
.SAMPLE |
| 1172 |
.BR global " tiny_array[10]" , " normal_array" , " big_array[50000]" |
| 1173 |
.ESAMPLE |
| 1174 |
.PP |
| 1175 |
Arrays may be configured for wrapping using the '%' suffix. This |
| 1176 |
causes older elements to be overwritten if more elements are inserted |
| 1177 |
than the array can hold. This works for both associative and statistics |
| 1178 |
typed arrays. |
| 1179 |
.SAMPLE |
| 1180 |
.BR global " wrapped_array1%[10]", " wrapped_array2%" |
| 1181 |
.ESAMPLE |
| 1182 |
|
| 1183 |
.PP |
| 1184 |
Many types of probe points provide context variables, which are |
| 1185 |
run-time values, safely extracted from the kernel or userspace program |
| 1186 |
being probed. These are prefixed with the \fB$\fR character. The |
| 1187 |
CONTEXT VARIABLES section in |
| 1188 |
.IR stapprobes (3stap) |
| 1189 |
lists what is available for each type of probe point. These context |
| 1190 |
variables become normal string or numeric scalars once they are stored |
| 1191 |
in normal script variables. See the TYPECASTING section below on how |
| 1192 |
to to turn them back into typed pointers for further processing as |
| 1193 |
context variables. There is some automation to help! |
| 1194 |
|
| 1195 |
.SS STATEMENTS |
| 1196 |
Statements enable procedural control flow. They may occur within |
| 1197 |
functions and probe handlers. The total number of statements executed |
| 1198 |
in response to any single probe event is limited to some number |
| 1199 |
defined by the MAXACTION macro in the translated C code, and is in the |
| 1200 |
neighbourhood of 1000. |
| 1201 |
.TP |
| 1202 |
EXP |
| 1203 |
Execute the string- or integer-valued expression and throw away |
| 1204 |
the value. |
| 1205 |
.TP |
| 1206 |
.BR { " STMT1 STMT2 ... " } |
| 1207 |
Execute each statement in sequence in this block. Note that |
| 1208 |
separators or terminators are generally not necessary between statements. |
| 1209 |
.TP |
| 1210 |
.BR ; |
| 1211 |
Null statement, do nothing. It is useful as an optional separator between |
| 1212 |
statements to improve syntax-error detection and to handle certain |
| 1213 |
grammar ambiguities. |
| 1214 |
.TP |
| 1215 |
.BR if " (EXP) STMT1 [ " else " STMT2 ]" |
| 1216 |
Compare integer-valued EXP to zero. Execute the first (non-zero) |
| 1217 |
or second STMT (zero). |
| 1218 |
.TP |
| 1219 |
.BR while " (EXP) STMT" |
| 1220 |
While integer-valued EXP evaluates to non-zero, execute STMT. |
| 1221 |
.TP |
| 1222 |
.BR for " (EXP1; EXP2; EXP3) STMT" |
| 1223 |
Execute EXP1 as initialization. While EXP2 is non-zero, execute |
| 1224 |
STMT, then the iteration expression EXP3. |
| 1225 |
.TP |
| 1226 |
.BR foreach " (VAR " in " ARRAY [ "limit " EXP ]) STMT" |
| 1227 |
Loop over each element of the named global array, assigning current |
| 1228 |
key to VAR. The array may not be modified within the statement. |
| 1229 |
By adding a single |
| 1230 |
.BR + " or " \- |
| 1231 |
operator after the VAR or the ARRAY identifier, the iteration will |
| 1232 |
proceed in a sorted order, by ascending or descending index or value. |
| 1233 |
If the array contains statistics aggregates, adding the desired |
| 1234 |
.BR @operator |
| 1235 |
between the ARRAY identifier and the |
| 1236 |
.BR + " or " \- |
| 1237 |
will specify the sorting aggregate function. See the STATISTICS |
| 1238 |
section below for the ones available. Default is |
| 1239 |
.BR @count . |
| 1240 |
Using the optional |
| 1241 |
.BR limit |
| 1242 |
keyword limits the number of loop iterations to EXP times. EXP is |
| 1243 |
evaluated once at the beginning of the loop. |
| 1244 |
.TP |
| 1245 |
.BR foreach " ([VAR1, VAR2, ...] " in " ARRAY [ "limit " EXP ]) STMT" |
| 1246 |
Same as above, used when the array is indexed with a tuple of keys. |
| 1247 |
A sorting suffix may be used on at most one VAR or ARRAY identifier. |
| 1248 |
.TP |
| 1249 |
.BR foreach " ([VAR1, VAR2, ...] " in " ARRAY [INDEX1, INDEX2, ...] [ "limit " EXP ]) STMT" |
| 1250 |
Same as above, where iterations are limited to elements in the array where |
| 1251 |
the keys match the index values specified. The symbol * can be used to specify |
| 1252 |
an index and will be treated as a wildcard. |
| 1253 |
.TP |
| 1254 |
.BR foreach " (VAR0 = VAR " in " ARRAY [ "limit " EXP ]) STMT" |
| 1255 |
This variant of foreach saves current value into VAR0 on each |
| 1256 |
iteration, so it is the same as ARRAY[VAR]. This also works with a |
| 1257 |
tuple of keys. Sorting suffixes on VAR0 have the same effect as on ARRAY. |
| 1258 |
.TP |
| 1259 |
.BR foreach " (VAR0 = VAR " in " ARRAY [INDEX1, INDEX2, ...] [ "limit " EXP ]) STMT" |
| 1260 |
Same as above, where iterations are limited to elements in the array where the |
| 1261 |
keys match the index values specified. The symbol * can be used to specify |
| 1262 |
an index and will be treated as a wildcard. |
| 1263 |
.TP |
| 1264 |
.BR break ", " continue |
| 1265 |
Exit or iterate the innermost nesting loop |
| 1266 |
.RB ( while " or " for " or " foreach ) |
| 1267 |
statement. |
| 1268 |
.TP |
| 1269 |
.BR return " EXP" |
| 1270 |
Return EXP value from enclosing function. If the function's value is |
| 1271 |
not taken anywhere, then a return statement is not needed, and the |
| 1272 |
function will have a special "unknown" type with no return value. |
| 1273 |
.TP |
| 1274 |
.BR next |
| 1275 |
Return now from enclosing probe handler. This is especially useful in |
| 1276 |
probe aliases that apply event filtering predicates. When used in functions, |
| 1277 |
the execution will be immediately transferred to the next overloaded function. |
| 1278 |
.TP |
| 1279 |
.BR try " { STMT1 } " catch " { STMT2 }" |
| 1280 |
Run the statements in the first block. Upon any run-time errors, abort |
| 1281 |
STMT1 and start executing STMT2. Any errors in STMT2 will propagate to |
| 1282 |
outer try/catch blocks, if any. |
| 1283 |
.TP |
| 1284 |
.BR try " { STMT1 } " catch "(VAR) { STMT2 }" |
| 1285 |
Same as above, plus assign the error message to the string scalar variable VAR. |
| 1286 |
.TP |
| 1287 |
.BR delete " ARRAY[INDEX1, INDEX2, ...]" |
| 1288 |
Remove from ARRAY the element specified by the index tuple. |
| 1289 |
If the index tuple contains a * in place of an index, the * is treated as a |
| 1290 |
wildcard and all elements with keys that match the index tuple will be removed |
| 1291 |
from ARRAY. |
| 1292 |
The value will no |
| 1293 |
longer be available, and subsequent iterations will not report the element. |
| 1294 |
It is not an error to delete an element that does not exist. |
| 1295 |
.TP |
| 1296 |
.BR delete " ARRAY" |
| 1297 |
Remove all elements from ARRAY. |
| 1298 |
.TP |
| 1299 |
.BR delete " SCALAR" |
| 1300 |
Removes the value of SCALAR. Integers and strings are cleared to 0 and "" |
| 1301 |
respectively, while statistics are reset to the initial empty state. |
| 1302 |
|
| 1303 |
.SS EXPRESSIONS |
| 1304 |
Systemtap supports a number of operators that have the same general syntax, |
| 1305 |
semantics, and precedence as in C and awk. Arithmetic is performed as per |
| 1306 |
typical C rules for signed integers. Division by zero or overflow is |
| 1307 |
detected and results in an error. |
| 1308 |
.TP |
| 1309 |
binary numeric operators |
| 1310 |
.B * / % + \- >> << & ^ | && || |
| 1311 |
.TP |
| 1312 |
binary string operators |
| 1313 |
.B . |
| 1314 |
(string concatenation) |
| 1315 |
.TP |
| 1316 |
numeric assignment operators |
| 1317 |
.B = *= /= %= += \-= >>= <<= &= ^= |= |
| 1318 |
.TP |
| 1319 |
string assignment operators |
| 1320 |
.B = .= |
| 1321 |
.TP |
| 1322 |
unary numeric operators |
| 1323 |
.B + \- ! ~ ++ \-\- |
| 1324 |
.TP |
| 1325 |
binary numeric, string comparison or regex matching operators |
| 1326 |
.B < > <= >= == != =~ !~ |
| 1327 |
.TP |
| 1328 |
ternary operator |
| 1329 |
.RB cond " ? " exp1 " : " exp2 |
| 1330 |
.TP |
| 1331 |
grouping operator |
| 1332 |
.BR ( " exp " ) |
| 1333 |
.TP |
| 1334 |
function call |
| 1335 |
.RB "fn " ( "[ arg1, arg2, ... ]" ) |
| 1336 |
.TP |
| 1337 |
array membership check |
| 1338 |
.RB exp " in " array |
| 1339 |
.br |
| 1340 |
.BR "[" exp1 ", " exp2 ", ... ] in " array |
| 1341 |
.br |
| 1342 |
.BR "[" * ", " * ", ... ] in " array |
| 1343 |
|
| 1344 |
.SS REGULAR EXPRESSION MATCHING |
| 1345 |
The scripting language supports regular expression matching. |
| 1346 |
The basic syntax is as follows: |
| 1347 |
.SAMPLE |
| 1348 |
.BR exp " =~ " regex |
| 1349 |
.BR exp " !~ " regex |
| 1350 |
.ESAMPLE |
| 1351 |
(The first operand must be an expression evaluating to a string; the |
| 1352 |
second operand must be a string literal containing a syntactically |
| 1353 |
valid regular expression.) |
| 1354 |
.PP |
| 1355 |
The regular expression syntax supports POSIX |
| 1356 |
Extended Regular Expression features as documented in |
| 1357 |
.IR grep (1) |
| 1358 |
except for subexpression reuse ("\\1") |
| 1359 |
functionality. |
| 1360 |
.PP |
| 1361 |
After a successful match, the contents of the matched |
| 1362 |
string and subexpressions can be extracted using the |
| 1363 |
matched() and ngroups() tapset functions as follows: |
| 1364 |
.SAMPLE |
| 1365 |
if ("an example string" =~ "str(ing)") { |
| 1366 |
matched(0) // -> returns "string", the matched substring |
| 1367 |
matched(1) // -> returns "ing", the 1st matched subexpression |
| 1368 |
ngroups() // -> returns 2, the number of matched groups |
| 1369 |
} |
| 1370 |
.ESAMPLE |
| 1371 |
.PP |
| 1372 |
|
| 1373 |
.SS PROBES |
| 1374 |
The main construct in the scripting language identifies probes. |
| 1375 |
Probes associate abstract events with a statement block ("probe |
| 1376 |
handler") that is to be executed when any of those events occur. The |
| 1377 |
general syntax is as follows: |
| 1378 |
.SAMPLE |
| 1379 |
.BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " } |
| 1380 |
.BR probe " PROBEPOINT [" , " PROBEPOINT] " "if (" CONDITION ") { " "[STMT ...]" " }" |
| 1381 |
.ESAMPLE |
| 1382 |
.PP |
| 1383 |
Events are specified in a special syntax called "probe points". There |
| 1384 |
are several varieties of probe points defined by the translator, and |
| 1385 |
tapset scripts may define further ones using aliases. Probe points |
| 1386 |
may be wildcarded, grouped, or listed in preference sequences, or |
| 1387 |
declared optional. More details on probe point syntax and semantics |
| 1388 |
are listed on the |
| 1389 |
.IR stapprobes (3stap) |
| 1390 |
manual page. |
| 1391 |
.PP |
| 1392 |
The probe handler is interpreted relative to the context of each |
| 1393 |
event. For events associated with kernel code, this context may |
| 1394 |
include |
| 1395 |
.I variables |
| 1396 |
defined in the |
| 1397 |
.I source code |
| 1398 |
at that spot. These "context variables" are presented to the script |
| 1399 |
as variables whose names are prefixed with "$". They may be accessed |
| 1400 |
only if the kernel's compiler preserved them despite optimization. |
| 1401 |
This is the same constraint that a debugger user faces when working |
| 1402 |
with optimized code. In addition, the objects must exist in paged-in |
| 1403 |
memory at the moment of the systemtap probe handler's execution, |
| 1404 |
because systemtap must not cause (suppresses) any additional paging. |
| 1405 |
Some probe types have very little context. |
| 1406 |
See the |
| 1407 |
.IR stapprobes (3stap) |
| 1408 |
man pages to see the kinds of context variables available at each kind |
| 1409 |
of probe point. As of systemtap version 4.3, functions called from |
| 1410 |
the handlers of some probe point types may also refer to context |
| 1411 |
variables. These are treated as if a clone of that function was inlined |
| 1412 |
into the calling probe handler and $variables evaluated in its context. |
| 1413 |
.PP |
| 1414 |
Probes may be decorated with an |
| 1415 |
.IR "arming condition" , |
| 1416 |
consisting of a simple boolean expression on read-only global script |
| 1417 |
variables. While disarmed (inactive, condition evaluates to false), some probe |
| 1418 |
types reduce or eliminate their run-time overheads. When an arming |
| 1419 |
condition evaluates to true, probes will be |
| 1420 |
.I soon |
| 1421 |
re-armed, and their probe handlers will start getting called as the |
| 1422 |
events fire. (Some events may be lost during the arming interval. If |
| 1423 |
this is unacceptable, do not use arming conditions for those probes.) |
| 1424 |
Example of the syntax: |
| 1425 |
.SAMPLE |
| 1426 |
probe timer.us(TIMER) if (enabled) { |
| 1427 |
... |
| 1428 |
} |
| 1429 |
.ESAMPLE |
| 1430 |
.PP |
| 1431 |
New probe points may be defined using "aliases". Probe point aliases |
| 1432 |
look similar to probe definitions, but instead of activating a probe |
| 1433 |
at the given point, it just defines a new probe point name as an alias |
| 1434 |
to an existing one. There are two types of alias, i.e. the prologue |
| 1435 |
style and the epilogue style which are identified by "=" and "+=" |
| 1436 |
respectively. |
| 1437 |
.PP |
| 1438 |
For prologue style alias, the statement block that follows an alias |
| 1439 |
definition is implicitly added as a prologue to any probe that refers |
| 1440 |
to the alias. While for the epilogue style alias, the statement block |
| 1441 |
that follows an alias definition is implicitly added as an epilogue to |
| 1442 |
any probe that refers to the alias. For example: |
| 1443 |
.SAMPLE |
| 1444 |
probe syscall.read = kernel.function("sys_read") { |
| 1445 |
fildes = $fd |
| 1446 |
if (execname() == "init") next # skip rest of probe |
| 1447 |
} |
| 1448 |
.ESAMPLE |
| 1449 |
defines a new probe point |
| 1450 |
.nh |
| 1451 |
.IR syscall.read , |
| 1452 |
.hy |
| 1453 |
which expands to |
| 1454 |
.nh |
| 1455 |
.IR kernel.function("sys_read") , |
| 1456 |
.hy |
| 1457 |
with the given statement as a prologue, which is useful to predefine |
| 1458 |
some variables for the alias user and/or to skip probe processing |
| 1459 |
entirely based on some conditions. And |
| 1460 |
.SAMPLE |
| 1461 |
probe syscall.read += kernel.function("sys_read") { |
| 1462 |
if (tracethis) println ($fd) |
| 1463 |
} |
| 1464 |
.ESAMPLE |
| 1465 |
defines a new probe point with the given statement as an epilogue, which |
| 1466 |
is useful to take actions based upon variables set or left over by the |
| 1467 |
the alias user. Please note that in each case, the statements in the |
| 1468 |
alias handler block are treated ordinarily, so that variables assigned |
| 1469 |
there constitute mere initialization, not a macro substitution. |
| 1470 |
|
| 1471 |
Aliases can also be defined to include both a prologue and an epilogue. |
| 1472 |
.SAMPLE |
| 1473 |
probe syscall.read = kernel.function("sys_read") { |
| 1474 |
fildes = $fd |
| 1475 |
if (execname() == "init") next |
| 1476 |
},{ |
| 1477 |
if (tracethis) println ($fd) |
| 1478 |
} |
| 1479 |
.ESAMPLE |
| 1480 |
|
| 1481 |
An alias is used just like a built-in probe type. |
| 1482 |
.SAMPLE |
| 1483 |
probe syscall.read { |
| 1484 |
printf("reading fd=%d\\n", fildes) |
| 1485 |
if (fildes > 10) tracethis = 1 |
| 1486 |
} |
| 1487 |
.ESAMPLE |
| 1488 |
|
| 1489 |
Probes with an alias can make use of the @probewrite predicate. This check |
| 1490 |
is used to detect whether a script variable or target variable has been |
| 1491 |
written to in the probe handler body. |
| 1492 |
.TP |
| 1493 |
@probewrite(var) |
| 1494 |
expands to 1 iff var has been written to in the probe handler body, otherwise it |
| 1495 |
expands to 0. |
| 1496 |
.ETP |
| 1497 |
.PP |
| 1498 |
In the following example, @probewrite(var) expands to 1 because var has been |
| 1499 |
written to in the probe handler body and consequently, the conditional statement |
| 1500 |
will run. |
| 1501 |
.SAMPLE |
| 1502 |
probe foo = begin { var = 0 }, { if (@probewrite(var)) println(var) } |
| 1503 |
|
| 1504 |
probe foo { |
| 1505 |
var = 1 |
| 1506 |
} |
| 1507 |
.ESAMPLE |
| 1508 |
|
| 1509 |
.SS FUNCTIONS |
| 1510 |
Systemtap scripts may define subroutines to factor out common work. |
| 1511 |
Functions take any number of scalar (integer or string) arguments, and |
| 1512 |
must return a single scalar (integer or string). An example function |
| 1513 |
declaration looks like this: |
| 1514 |
.SAMPLE |
| 1515 |
function thisfn (arg1, arg2) { |
| 1516 |
return arg1 + arg2 |
| 1517 |
} |
| 1518 |
.ESAMPLE |
| 1519 |
Note the general absence of type declarations, which are instead |
| 1520 |
inferred by the translator. However, if desired, a function |
| 1521 |
definition may include explicit type declarations for its return value |
| 1522 |
and/or its arguments. This is especially helpful for embedded-C |
| 1523 |
functions. In the following example, the type inference engine need |
| 1524 |
only infer type type of arg2 (a string). |
| 1525 |
.SAMPLE |
| 1526 |
function thatfn:string (arg1:long, arg2) { |
| 1527 |
return sprint(arg1) . arg2 |
| 1528 |
} |
| 1529 |
.ESAMPLE |
| 1530 |
Functions may call others or themselves |
| 1531 |
recursively, up to a fixed nesting limit. This limit is defined by |
| 1532 |
the MAXNESTING macro in the translated C code and is in the neighbourhood of 10. |
| 1533 |
|
| 1534 |
Functions may be marked private using the private keyword to limit their scope |
| 1535 |
to the tapset or user script file they are defined in. An example definition of |
| 1536 |
a private function follows: |
| 1537 |
.SAMPLE |
| 1538 |
private function three:long () { return 3 } |
| 1539 |
.ESAMPLE |
| 1540 |
|
| 1541 |
Functions terminating without reaching an explicit return statement will |
| 1542 |
return an implicit 0 or "", determined by type inference. |
| 1543 |
|
| 1544 |
Functions may be overloaded during both runtime and compile time. |
| 1545 |
|
| 1546 |
Runtime overloading allows the executed function to be selected while the |
| 1547 |
module is running based on runtime conditions and is achieved using the |
| 1548 |
"next" statement in script functions and STAP_NEXT macro for embedded-C |
| 1549 |
functions. For example, |
| 1550 |
|
| 1551 |
.SAMPLE |
| 1552 |
function f() { if (condition) next; print("first function") } |
| 1553 |
function f() %{ STAP_NEXT; print("second function") %} |
| 1554 |
function f() { print("third function") } |
| 1555 |
.ESAMPLE |
| 1556 |
|
| 1557 |
During a functioncall f(), the execution will transfer to the third function |
| 1558 |
if condition evaluates to true and print "third function". Note that the second |
| 1559 |
function is unconditionally nexted. |
| 1560 |
|
| 1561 |
Parameter overloading allows the function to be executed to be selected |
| 1562 |
at compile time based on the number of arguments provided to the |
| 1563 |
functioncall. For example, |
| 1564 |
|
| 1565 |
.SAMPLE |
| 1566 |
function g() { print("first function") } |
| 1567 |
function g(x) { print("second function") } |
| 1568 |
g() -> "first function" |
| 1569 |
g(1) -> "second function" |
| 1570 |
.ESAMPLE |
| 1571 |
|
| 1572 |
Note that runtime overloading does not occur in the above example, as exactly |
| 1573 |
one function will be resolved for the functioncall. The use of a next statement |
| 1574 |
inside a function while no more overloads remain will trigger a runtime exception |
| 1575 |
Runtime overloading will only occur if the functions have the same arity, |
| 1576 |
functions with the same name but different number of parameters are completely |
| 1577 |
unrelated. |
| 1578 |
|
| 1579 |
Execution order is determined by a priority value which may be specified. |
| 1580 |
If no explicit priority is specified, user script functions are given a |
| 1581 |
higher priority than library functions. User script functions and library |
| 1582 |
functions are assigned a default priority value of 0 and 1 respectively. |
| 1583 |
Functions with the same priority are executed in declaration order. For example, |
| 1584 |
|
| 1585 |
.SAMPLE |
| 1586 |
function f():3 { if (condition) next; print("first function") } |
| 1587 |
function f():1 { if (condition) next; print("second function") } |
| 1588 |
function f():2 { print("third function") } |
| 1589 |
.ESAMPLE |
| 1590 |
|
| 1591 |
Since the second function has highest priority, it is executed first. |
| 1592 |
The first function is never executed as there no "next" statements in |
| 1593 |
the third function to transfer execution. |
| 1594 |
|
| 1595 |
.SS PRINTING |
| 1596 |
|
| 1597 |
There are a set of function names that are specially treated by the translator. |
| 1598 |
They format values for printing to the standard systemtap output stream in a |
| 1599 |
more convenient way (note that data generated in the kernel module need to get |
| 1600 |
transferred to user-space in order to get printed). |
| 1601 |
|
| 1602 |
The |
| 1603 |
.IR sprint* |
| 1604 |
variants return the formatted string instead of printing it. |
| 1605 |
.TP |
| 1606 |
.BR print ", " sprint |
| 1607 |
Print one or more values of any type, concatenated directly together. |
| 1608 |
.TP |
| 1609 |
.BR println ", " sprintln |
| 1610 |
Print values like |
| 1611 |
.IR print " and " sprint , |
| 1612 |
but also append a newline. |
| 1613 |
.TP |
| 1614 |
.BR printd ", " sprintd |
| 1615 |
Take a string delimiter and two or more values of any type, and print the |
| 1616 |
values with the delimiter interposed. The delimiter must be a literal |
| 1617 |
string constant. |
| 1618 |
.TP |
| 1619 |
.BR printdln ", " sprintdln |
| 1620 |
Print values with a delimiter like |
| 1621 |
.IR printd " and " sprintd , |
| 1622 |
but also append a newline. |
| 1623 |
.TP |
| 1624 |
.BR printf ", " sprintf |
| 1625 |
Take a formatting string and a number of values of corresponding types, |
| 1626 |
and print them all. The format must be a literal string constant. |
| 1627 |
.PP |
| 1628 |
The |
| 1629 |
.IR printf |
| 1630 |
formatting directives similar to those of C, except that they are |
| 1631 |
fully type-checked by the translator: |
| 1632 |
.RS |
| 1633 |
.TP |
| 1634 |
%b |
| 1635 |
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. |
| 1636 |
.TP |
| 1637 |
%c |
| 1638 |
Character. |
| 1639 |
.TP |
| 1640 |
%d,%i |
| 1641 |
Signed decimal. |
| 1642 |
.TP |
| 1643 |
%m |
| 1644 |
Safely reads kernel (without #) or user (with #) memory at the given address, outputs its content. The optional precision specifier (not field width) determines the number of bytes to read - default is 1 byte. %10.4m prints 4 bytes of the memory in a 10-character-wide field. Note, on some architectures user memory can still be read without #. |
| 1645 |
.TP |
| 1646 |
%M |
| 1647 |
Same as %m, but outputs in hexadecimal. The minimal size of output is double the optional precision specifier - default is 1 byte (2 hex chars). %10.4M prints 4 bytes of the memory as 8 hexadecimal characters in a 10-character-wide field. %.*M hex-dumps a given number of bytes from a given buffer. |
| 1648 |
.TP |
| 1649 |
%o |
| 1650 |
Unsigned octal. |
| 1651 |
.TP |
| 1652 |
%p |
| 1653 |
Unsigned pointer address. |
| 1654 |
.TP |
| 1655 |
%s |
| 1656 |
String. |
| 1657 |
.TP |
| 1658 |
%u |
| 1659 |
Unsigned decimal. |
| 1660 |
.TP |
| 1661 |
%x |
| 1662 |
Unsigned hex value, in all lower-case. |
| 1663 |
.TP |
| 1664 |
%X |
| 1665 |
Unsigned hex value, in all upper-case. |
| 1666 |
.TP |
| 1667 |
%% |
| 1668 |
Writes a %. |
| 1669 |
.RE |
| 1670 |
.PP |
| 1671 |
The |
| 1672 |
.IR # |
| 1673 |
flag selects the alternate forms. For octal, this prefixes a 0. For hex, this |
| 1674 |
prefixes 0x or 0X, depending on case. For characters, this escapes |
| 1675 |
non-printing values with either C-like escapes or raw octal. In the case of %#m/%#M, |
| 1676 |
this safely accesses user space memory rather than kernel space memory. |
| 1677 |
.PP |
| 1678 |
Examples: |
| 1679 |
.SAMPLE |
| 1680 |
a = "alice", b = "bob", p = 0x1234abcd, i = 123, j = \-1, id[a] = 1234, id[b] = 4567 |
| 1681 |
print("hello") |
| 1682 |
Prints: hello |
| 1683 |
println(b) |
| 1684 |
Prints: bob\\n |
| 1685 |
println(a . " is " . sprint(16)) |
| 1686 |
Prints: alice is 16 |
| 1687 |
foreach (name in id) printdln("|", strlen(name), name, id[name]) |
| 1688 |
Prints: 5|alice|1234\\n3|bob|4567 |
| 1689 |
printf("%c is %s; %x or %X or %p; %d or %u\\n",97,a,p,p,p,j,j) |
| 1690 |
Prints: a is alice; 1234abcd or 1234ABCD or 0x1234abcd; \-1 or 18446744073709551615\\n |
| 1691 |
printf("2 bytes of kernel buffer at address %p: %2m", p, p) |
| 1692 |
Prints: 2 byte of kernel buffer at address 0x1234abcd: <binary data> |
| 1693 |
printf("%4b", p) |
| 1694 |
Prints (these values as binary data): 0x1234abcd |
| 1695 |
printf("%#o %#x %#X\\n", 1, 2, 3) |
| 1696 |
Prints: 01 0x2 0X3 |
| 1697 |
printf("%#c %#c %#c\\n", 0, 9, 42) |
| 1698 |
Prints: \\000 \\t * |
| 1699 |
.ESAMPLE |
| 1700 |
|
| 1701 |
.SS STATISTICS |
| 1702 |
It is often desirable to collect statistics in a way that avoids the |
| 1703 |
penalties of repeatedly exclusive locking the global variables those |
| 1704 |
numbers are being put into. Systemtap provides a solution using a |
| 1705 |
special operator to accumulate values, and several pseudo-functions to |
| 1706 |
extract the statistical aggregates. |
| 1707 |
.PP |
| 1708 |
The aggregation operator is |
| 1709 |
.IR <<< , |
| 1710 |
and resembles an assignment, or a C++ output-streaming operation. |
| 1711 |
The left operand specifies a scalar or array-index lvalue, which must |
| 1712 |
be declared global. The right operand is a numeric expression. The |
| 1713 |
meaning is intuitive: add the given number to the pile of numbers to |
| 1714 |
compute statistics of. (The specific list of statistics to gather |
| 1715 |
is given separately, by the extraction functions.) |
| 1716 |
.SAMPLE |
| 1717 |
foo <<< 1 |
| 1718 |
stats[pid()] <<< memsize |
| 1719 |
.ESAMPLE |
| 1720 |
.PP |
| 1721 |
The extraction functions are also special. For each appearance of a |
| 1722 |
distinct extraction function operating on a given identifier, the |
| 1723 |
translator arranges to compute a set of statistics that satisfy it. |
| 1724 |
The statistics system is thereby "on-demand". Each execution of |
| 1725 |
an extraction function causes the aggregation to be computed for |
| 1726 |
that moment across all processors. |
| 1727 |
.PP |
| 1728 |
Here is the set of extractor functions. The first argument of each is |
| 1729 |
the same style of lvalue used on the left hand side of the accumulate |
| 1730 |
operation. The |
| 1731 |
.IR @count(v) ", " @sum(v) ", " @min(v) ", " @max(v) ", " @avg(v) ", " |
| 1732 |
@variance(v[, b]) extractor functions compute the |
| 1733 |
number/total/minimum/maximum/average/variance |
| 1734 |
of all accumulated values. The resulting values are all simple |
| 1735 |
integers. Arrays containing aggregates may be sorted and iterated. |
| 1736 |
See the |
| 1737 |
.BR foreach |
| 1738 |
construct above. |
| 1739 |
.PP |
| 1740 |
|
| 1741 |
Variance uses Welford's online algorithm. The calculations are based |
| 1742 |
on integer arithmetic, and so may suffer from low precision and overflow. |
| 1743 |
To improve this, @variance(v[, b]) accepts an optional parameter b, the |
| 1744 |
bit-shift, ranging from 0 (default) to 62, for internal scaling. Only one |
| 1745 |
value of bit-shift may be used with given global variable. A larger bitshift |
| 1746 |
value increases precision, but increases the likelihood of overflow. |
| 1747 |
|
| 1748 |
.SAMPLE |
| 1749 |
$ stap -e \\ |
| 1750 |
> 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x)) }' |
| 1751 |
12 |
| 1752 |
$ stap -e \\ |
| 1753 |
> 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x,1)) }' |
| 1754 |
2 |
| 1755 |
$ python3 -c 'import statistics; print(statistics.variance([1, 2, 3, 4, 5]))' |
| 1756 |
2.5 |
| 1757 |
$ |
| 1758 |
.ESAMPLE |
| 1759 |
|
| 1760 |
Overflow (from internal multiplication of large numbers) may occur and |
| 1761 |
may cause a negative variance result. Consider normalizing your input |
| 1762 |
data. Adding or subtracting a fixed value from all variance inputs |
| 1763 |
preserves the original variance. Dividing the variance inputs by a fixed |
| 1764 |
value shrinks the original variance by that value squared. |
| 1765 |
|
| 1766 |
\" the following is a more mathy rendering, but gnu nroff can't show them properly :-( |
| 1767 |
.ig |
| 1768 |
|
| 1769 |
If |
| 1770 |
.EQ |
| 1771 |
variance( v sub 1 , v sub 2 , ... , v sub N ) = V |
| 1772 |
.EN |
| 1773 |
|
| 1774 |
Then |
| 1775 |
.EQ |
| 1776 |
variance ( {v sub 1} over X , {v sub 2} over X, ... , {v sub N} over X ) = V over {X sup 2} |
| 1777 |
.EN |
| 1778 |
|
| 1779 |
and |
| 1780 |
.EQ |
| 1781 |
variance ( v sub 1 - Y, v sub 2 - Y, ... , v sub N - Y ) = V |
| 1782 |
.EN |
| 1783 |
|
| 1784 |
.. |
| 1785 |
|
| 1786 |
Histograms are also available, but are more complicated because they |
| 1787 |
have a vector rather than scalar value. |
| 1788 |
.I @hist_linear(v,start,stop,interval) |
| 1789 |
represents a linear histogram from "start" to "stop" (inclusive) |
| 1790 |
by increments of "interval". The interval must be positive. Similarly, |
| 1791 |
.I @hist_log(v) |
| 1792 |
represents a base-2 logarithmic histogram. Printing a histogram |
| 1793 |
with the |
| 1794 |
.I print |
| 1795 |
family of functions renders a histogram object as a tabular |
| 1796 |
"ASCII art" bar chart. |
| 1797 |
|
| 1798 |
.SAMPLE |
| 1799 |
probe timer.profile { |
| 1800 |
x[1] <<< pid() |
| 1801 |
x[2] <<< uid() |
| 1802 |
y <<< tid() |
| 1803 |
} |
| 1804 |
global x // an array containing aggregates |
| 1805 |
global y // a scalar |
| 1806 |
probe end { |
| 1807 |
foreach ([i] in x @count+) { |
| 1808 |
printf ("x[%d]: avg %d = sum %d / count %d\\n", |
| 1809 |
i, @avg(x[i]), @sum(x[i]), @count(x[i])) |
| 1810 |
println (@hist_log(x[i])) |
| 1811 |
} |
| 1812 |
println ("y:") |
| 1813 |
println (@hist_log(y)) |
| 1814 |
} |
| 1815 |
.ESAMPLE |
| 1816 |
|
| 1817 |
The counts of each histogram bucket may be individually accessed via |
| 1818 |
the \fB[index]\fP operator. Each bucket is addressed from 1 through N |
| 1819 |
(for each natural bucket). In addition bucket #0 counts all the |
| 1820 |
samples beneath the start value, and bucket #N+1 counts all the |
| 1821 |
samples above the stop value. Histogram buckets (including the two |
| 1822 |
out-of-range buckets) may also be iterated with \fBforeach\fP. |
| 1823 |
|
| 1824 |
.SAMPLE |
| 1825 |
global x |
| 1826 |
probe oneshot { |
| 1827 |
x <<< -100 |
| 1828 |
x <<< 1 |
| 1829 |
x <<< 2 |
| 1830 |
x <<< 3 |
| 1831 |
x <<< 100 |
| 1832 |
foreach (bucket in @hist_linear(x,1,3,1)) |
| 1833 |
// expecting 1 out-of-range-low bucket |
| 1834 |
// 3 payload buckets |
| 1835 |
// 1 out-of-range-high bucket |
| 1836 |
printf("bucket %d count %d\\n", |
| 1837 |
bucket, @hist_linear(x,1,3,1)[bucket]) |
| 1838 |
} |
| 1839 |
.ESAMPLE |
| 1840 |
|
| 1841 |
.SS TYPECASTING |
| 1842 |
Once a pointer (see the CONTEXT VARIABLES section of |
| 1843 |
.IR stapprobes (3stap)) |
| 1844 |
has been saved into a script integer variable, the translator |
| 1845 |
\fBattempts to\fP keep the type information necessary to |
| 1846 |
access members from that pointer. |
| 1847 |
|
| 1848 |
The translator attempts to track DWARF typing associated with |
| 1849 |
script variables assigned from addresses of context $variables, |
| 1850 |
@cast or @var operators. Depending on the complexity of the |
| 1851 |
script code, this association may pass to related variables, |
| 1852 |
so that \fI->\fP and \fI[]\fP operators may be used on them, |
| 1853 |
just as on the original context variable. For example: |
| 1854 |
|
| 1855 |
.SAMPLE |
| 1856 |
foo = $param->foo; printf("x:%d y:%d\\n", foo->x, foo->y) |
| 1857 |
printf("my value is %d\\n", ($type == 42 ? $foo : $bar)->value) |
| 1858 |
printf("my parent pid is %d\\n", task_parent(task_current())->tgid) |
| 1859 |
.ESAMPLE |
| 1860 |
|
| 1861 |
However, if this association heuristic doesn't work for a script, |
| 1862 |
using the |
| 1863 |
.I @cast() |
| 1864 |
operator tells the translator how to interpret the number as a typed pointer. |
| 1865 |
.SAMPLE |
| 1866 |
@cast(p, "type_name"[, "module"])\->member |
| 1867 |
.ESAMPLE |
| 1868 |
.PP |
| 1869 |
This will interpret |
| 1870 |
.I p |
| 1871 |
as a pointer to a struct/union named |
| 1872 |
.I type_name |
| 1873 |
and dereference the |
| 1874 |
.I member |
| 1875 |
value. Further |
| 1876 |
.IR \->subfield |
| 1877 |
expressions may be appended to dereference more levels. Note that for direct |
| 1878 |
dereferencing of a pointer {kernel,user}_{char,int,...}($p) should be used. |
| 1879 |
(Refer to stapfuncs(5) for more details.) |
| 1880 |
.BR |
| 1881 |
NOTE: |
| 1882 |
the same dereferencing operator |
| 1883 |
.IR \-> |
| 1884 |
is used to refer to both direct containment or pointer indirection. |
| 1885 |
Systemtap automatically determines which. The optional |
| 1886 |
.I module |
| 1887 |
tells the translator where to look for information about that type. |
| 1888 |
Multiple modules may be specified as a list with |
| 1889 |
.IR : |
| 1890 |
separators. If the module is not specified, it will default either to |
| 1891 |
the probe module for dwarf probes, or to "kernel" for functions and all |
| 1892 |
other probes types. |
| 1893 |
.PP |
| 1894 |
Previously up to systemtap version 4.2, "kernel" was inferred if unspecified. |
| 1895 |
Use --compatible=4.2 to activate this default. |
| 1896 |
.PP |
| 1897 |
The translator can create its own module with type information from a header |
| 1898 |
surrounded by angle brackets, in case normal debuginfo is not available. For |
| 1899 |
kernel headers, prefix it with "kernel" to use the appropriate build system. |
| 1900 |
All other headers are built with default GCC parameters into a user module. |
| 1901 |
Multiple headers may be specified in sequence to resolve a codependency. |
| 1902 |
.PP |
| 1903 |
As of systemtap version 5.4, the kernel "<vmlinux.h>" header is tried before |
| 1904 |
any specified kernel headers or modules, which may make it unnecessary to list |
| 1905 |
any explicit module or header file names for kernel data structures. |
| 1906 |
.SAMPLE |
| 1907 |
@cast(tv, "timeval", "<sys/time.h>")\->tv_sec |
| 1908 |
@cast(task, "task_struct", "kernel<linux/sched.h>")\->tgid |
| 1909 |
@cast(task, "task_struct", |
| 1910 |
"kernel<linux/sched.h><linux/fs_struct.h>")\->fs\->umask |
| 1911 |
.ESAMPLE |
| 1912 |
Values acquired by |
| 1913 |
.BR @cast |
| 1914 |
may be pretty-printed by the |
| 1915 |
.BR $ " and " $$ |
| 1916 |
suffix operators, the same way as described in the CONTEXT VARIABLES |
| 1917 |
section of the |
| 1918 |
.IR stapprobes (3stap) |
| 1919 |
manual page. |
| 1920 |
|
| 1921 |
.PP |
| 1922 |
When in guru mode, the translator will also allow scripts to assign new |
| 1923 |
values to members of typecasted pointers. |
| 1924 |
.PP |
| 1925 |
Typecasting is also useful in the case of |
| 1926 |
.I void* |
| 1927 |
members whose type may be determinable at runtime. |
| 1928 |
.SAMPLE |
| 1929 |
probe foo { |
| 1930 |
if ($var\->type == 1) { |
| 1931 |
value = @cast($var\->data, "type1")\->bar |
| 1932 |
} else { |
| 1933 |
value = @cast($var\->data, "type2")\->baz |
| 1934 |
} |
| 1935 |
print(value) |
| 1936 |
} |
| 1937 |
.ESAMPLE |
| 1938 |
|
| 1939 |
.SS EMBEDDED C |
| 1940 |
When in guru mode, the translator accepts embedded C code in the |
| 1941 |
top level of the script. Such code is enclosed between |
| 1942 |
.IR %{ |
| 1943 |
and |
| 1944 |
.IR %} |
| 1945 |
markers, and is transcribed verbatim, without analysis, in some |
| 1946 |
sequence, into the top level of the generated C code. At the |
| 1947 |
outermost level, this may be useful to add |
| 1948 |
.IR #include |
| 1949 |
instructions, and any auxiliary definitions for use by other embedded |
| 1950 |
code. |
| 1951 |
.PP |
| 1952 |
Another place where embedded code is permitted is as a function body. |
| 1953 |
In this case, the script language body is replaced entirely by a piece |
| 1954 |
of C code enclosed again between |
| 1955 |
.IR %{ " and " %} |
| 1956 |
markers. |
| 1957 |
This C code may do anything reasonable and safe. There are a number |
| 1958 |
of undocumented but complex safety constraints on atomicity, |
| 1959 |
concurrency, resource consumption, and run time limits, so this |
| 1960 |
is an advanced technique. |
| 1961 |
.PP |
| 1962 |
The memory locations set aside for input and output values |
| 1963 |
are made available to it using macros |
| 1964 |
.IR STAP_ARG_* |
| 1965 |
and |
| 1966 |
.IR STAP_RETVALUE . |
| 1967 |
Errors may be signalled with STAP_ERROR. Output may be written with |
| 1968 |
STAP_PRINTF. The function may return early with STAP_RETURN. |
| 1969 |
Here are some examples: |
| 1970 |
.SAMPLE |
| 1971 |
function integer_ops (val) %{ |
| 1972 |
STAP_PRINTF("%d\\n", STAP_ARG_val); |
| 1973 |
STAP_RETVALUE = STAP_ARG_val + 1; |
| 1974 |
if (STAP_RETVALUE == 4) |
| 1975 |
STAP_ERROR("wrong guess: %d", (int) STAP_RETVALUE); |
| 1976 |
if (STAP_RETVALUE == 3) |
| 1977 |
STAP_RETURN(0); |
| 1978 |
STAP_RETVALUE ++; |
| 1979 |
%} |
| 1980 |
function string_ops (val) %{ |
| 1981 |
strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN); |
| 1982 |
strlcat (STAP_RETVALUE, "one", MAXSTRINGLEN); |
| 1983 |
if (strcmp (STAP_RETVALUE, "three-two-one")) |
| 1984 |
STAP_RETURN("parameter should be three-two-"); |
| 1985 |
%} |
| 1986 |
function no_ops () %{ |
| 1987 |
STAP_RETURN(); /* function inferred with no return value */ |
| 1988 |
%} |
| 1989 |
.ESAMPLE |
| 1990 |
The function argument and return value types have to be inferred by |
| 1991 |
the translator from the call sites in order for this to work. The |
| 1992 |
user should examine C code generated for ordinary script-language |
| 1993 |
functions in order to write compatible embedded-C ones. |
| 1994 |
.PP |
| 1995 |
The last place where embedded code is permitted is as an expression rvalue. |
| 1996 |
In this case, the C code enclosed between |
| 1997 |
.IR %{ " and " %} |
| 1998 |
markers is interpreted as an ordinary expression value. It is assumed |
| 1999 |
to be a normal 64-bit signed number, unless the marker |
| 2000 |
.I /* string */ |
| 2001 |
is included, in which case it's treated as a string. |
| 2002 |
.SAMPLE |
| 2003 |
function add_one (val) { |
| 2004 |
return val + %{ 1 %} |
| 2005 |
} |
| 2006 |
function add_string_two (val) { |
| 2007 |
return val . %{ /* string */ "two" %} |
| 2008 |
} |
| 2009 |
@define SOME_STAP_MACRO %( %{ SOME_C_MACRO %} %) |
| 2010 |
probe begin { |
| 2011 |
printf("SOME_C_MACRO has value: %d\\n", @SOME_STAP_MACRO); |
| 2012 |
} |
| 2013 |
.ESAMPLE |
| 2014 |
.PP |
| 2015 |
The embedded-C code may contain markers to assert optimization |
| 2016 |
and safety properties. |
| 2017 |
.TP |
| 2018 |
.I /* pure */ |
| 2019 |
means that the C code has no side effects and may be elided entirely if its |
| 2020 |
value is not used by script code. |
| 2021 |
.TP |
| 2022 |
.I /* stable */ |
| 2023 |
means that the C code always has the same value (in any given probe handler |
| 2024 |
invocation), so repeated calls may be automatically replaced by memoized |
| 2025 |
values. Such functions must take no parameters, and also be |
| 2026 |
.IR pure . |
| 2027 |
.TP |
| 2028 |
.I /* unprivileged */ |
| 2029 |
means that the C code is so safe that even unprivileged users are permitted |
| 2030 |
to use it. |
| 2031 |
.TP |
| 2032 |
.I /* myproc\-unprivileged */ |
| 2033 |
means that the C code is so safe that even unprivileged users are permitted |
| 2034 |
to use it, provided that the target of the current probe is within the user's |
| 2035 |
own process. |
| 2036 |
.TP |
| 2037 |
.I /* guru */ |
| 2038 |
means that the C code is so unsafe that a systemtap user must specify |
| 2039 |
.IR \-g |
| 2040 |
(guru mode) to use this. (Tapsets are permitted and presumed to call them safely.) |
| 2041 |
.TP |
| 2042 |
.I /* unmangled */ |
| 2043 |
in an embedded-C function, means that the legacy (pre-1.8) argument |
| 2044 |
access syntax should be made available inside the function. Hence, in |
| 2045 |
addition to |
| 2046 |
.I STAP_ARG_foo |
| 2047 |
and |
| 2048 |
.I STAP_RETVALUE |
| 2049 |
one can use |
| 2050 |
.I THIS->foo |
| 2051 |
and |
| 2052 |
.I THIS->__retvalue |
| 2053 |
respectively inside the function. This is useful for quickly migrating code written for SystemTap version 1.7 and earlier. |
| 2054 |
.TP |
| 2055 |
.I /* pragma:suffix */ |
| 2056 |
Emit the file-level containing C code near the end of the resulting kernel |
| 2057 |
module C source file. |
| 2058 |
.TP |
| 2059 |
.I /* unmodified-fnargs */ |
| 2060 |
in an embedded-C function, means that the function arguments are not modified |
| 2061 |
inside the function body. |
| 2062 |
.TP |
| 2063 |
.I /* string */ |
| 2064 |
in embedded-C expressions only, means that the expression has |
| 2065 |
.I const char * |
| 2066 |
type and should be treated as a string value, instead of |
| 2067 |
the default long numeric. |
| 2068 |
.PP |
| 2069 |
Script level global variables may be accessed in embedded-C functions and |
| 2070 |
blocks. To read or write the global variable |
| 2071 |
.I var |
| 2072 |
, the |
| 2073 |
.I /* pragma:read:var */ |
| 2074 |
or |
| 2075 |
.I /* pragma:write:var */ |
| 2076 |
marker must be first placed in the embedded-C function or block. This provides |
| 2077 |
the macros |
| 2078 |
.I STAP_GLOBAL_GET_* |
| 2079 |
and |
| 2080 |
.I STAP_GLOBAL_SET_* |
| 2081 |
macros to allow reading and writing, respectively. For example: |
| 2082 |
.SAMPLE |
| 2083 |
global var |
| 2084 |
global var2[100] |
| 2085 |
function increment() %{ |
| 2086 |
/* pragma:read:var */ /* pragma:write:var */ |
| 2087 |
/* pragma:read:var2 */ /* pragma:write:var2 */ |
| 2088 |
STAP_GLOBAL_SET_var(STAP_GLOBAL_GET_var()+1); //var++ |
| 2089 |
STAP_GLOBAL_SET_var2(1, 1, STAP_GLOBAL_GET_var2(1, 1)+1); //var2[1,1]++ |
| 2090 |
%} |
| 2091 |
.ESAMPLE |
| 2092 |
Variables may be read and set in both embedded-C functions and expressions. |
| 2093 |
Strings returned from embedded-C code are decayed to pointers. Variables must |
| 2094 |
also be assigned at script level to allow for type inference. Map assignment |
| 2095 |
does not return the value written, so chaining does not work. |
| 2096 |
|
| 2097 |
.SS BUILT-INS |
| 2098 |
A set of builtin probe point aliases are provided |
| 2099 |
by the scripts installed in the directory specified in the |
| 2100 |
.IR stappaths (7) |
| 2101 |
manual page. The functions are described in the |
| 2102 |
.IR stapprobes (3stap) |
| 2103 |
manual page. |
| 2104 |
|
| 2105 |
.SS DEREFERENCING |
| 2106 |
Integers can be dereferenced from pointers saved as a script integer |
| 2107 |
variables using the |
| 2108 |
.I @kderef() |
| 2109 |
or |
| 2110 |
.I @uderef() |
| 2111 |
operators. |
| 2112 |
.I @kderef() |
| 2113 |
is used for kernel space addresses and |
| 2114 |
.I @uderef() |
| 2115 |
is used for user space addresses. |
| 2116 |
.SAMPLE |
| 2117 |
@kderef(SIZE, addr) |
| 2118 |
@uderef(SIZE, addr) |
| 2119 |
.ESAMPLE |
| 2120 |
This will interpret |
| 2121 |
.I addr |
| 2122 |
as a kernel/user address and read |
| 2123 |
.I SIZE |
| 2124 |
bytes starting at that address. |
| 2125 |
.I SIZE |
| 2126 |
should be either 1, 2, 4 or 8 bytes. |
| 2127 |
|
| 2128 |
.SS REGISTERS |
| 2129 |
The value stored within a register can be accessed using the |
| 2130 |
.I @kregister() |
| 2131 |
or |
| 2132 |
.I @uregister() |
| 2133 |
operators. |
| 2134 |
.I @kregister() |
| 2135 |
is used for kernel space registers and |
| 2136 |
.I @uregister() |
| 2137 |
is used for user space registers. The register of interest is |
| 2138 |
specified using its DWARF number. |
| 2139 |
.SAMPLE |
| 2140 |
@kregister(0) |
| 2141 |
@uregister(5) |
| 2142 |
|
| 2143 |
.SH PROCESSING |
| 2144 |
The translator begins pass 1 by parsing the given input script, |
| 2145 |
and all scripts (files named |
| 2146 |
.IR *.stp ) |
| 2147 |
found in a tapset directory. The directories listed |
| 2148 |
with |
| 2149 |
.BR \-I |
| 2150 |
are processed in sequence, each processed in "guru mode". For each |
| 2151 |
directory, a number of subdirectories are also searched. These |
| 2152 |
subdirectories are derived from the selected kernel version (the |
| 2153 |
.BR \-R |
| 2154 |
option), |
| 2155 |
in order to allow more kernel-version-specific scripts to override less |
| 2156 |
specific ones. For example, for a kernel version |
| 2157 |
.IR 2.6.12\-23.FC3 |
| 2158 |
the following patterns would be searched, in sequence: |
| 2159 |
.IR 2.6.12\-23.FC3/*.stp , |
| 2160 |
.IR 2.6.12/*.stp , |
| 2161 |
.IR 2.6/*.stp , |
| 2162 |
and finally |
| 2163 |
.IR *.stp . |
| 2164 |
Stopping the translator after pass 1 causes it to print the parse trees. |
| 2165 |
|
| 2166 |
.PP |
| 2167 |
In pass 2, the translator analyzes the input script to resolve symbols |
| 2168 |
and types. References to variables, functions, and probe aliases that |
| 2169 |
are unresolved internally are satisfied by searching through the |
| 2170 |
parsed tapset script files. If any tapset script file is selected |
| 2171 |
because it defines an unresolved symbol, then the entirety of that |
| 2172 |
file is added to the translator's resolution queue. This process |
| 2173 |
iterates until all symbols are resolved and a subset of tapset script |
| 2174 |
files is selected. |
| 2175 |
.PP |
| 2176 |
Next, all probe point descriptions are validated |
| 2177 |
against the wide variety supported by the translator. Probe points that |
| 2178 |
refer to code locations ("synchronous probe points") require the |
| 2179 |
appropriate kernel debugging information to be installed. In the |
| 2180 |
associated probe handlers, target-side variables (whose names begin |
| 2181 |
with "$") are found and have their run-time locations decoded. |
| 2182 |
.PP |
| 2183 |
Next, all probes and functions are analyzed for optimization |
| 2184 |
opportunities, in order to remove variables, expressions, and |
| 2185 |
functions that have no useful value and no side-effect. Embedded-C |
| 2186 |
functions are assumed to have side-effects unless they include the |
| 2187 |
magic string |
| 2188 |
.BR /*\ pure\ */ . |
| 2189 |
Since this optimization can hide latent code errors such as type |
| 2190 |
mismatches or invalid $context variables, it sometimes may be useful |
| 2191 |
to disable the optimizations with the |
| 2192 |
.BR \-u |
| 2193 |
option. |
| 2194 |
.PP |
| 2195 |
Finally, all variable, function, parameter, array, and index types are |
| 2196 |
inferred from context (literals and operators). Stopping the |
| 2197 |
translator after pass 2 causes it to list all the probes, functions, |
| 2198 |
and variables, along with all inferred types. Any inconsistent or |
| 2199 |
unresolved types cause an error. |
| 2200 |
|
| 2201 |
.PP |
| 2202 |
In pass 3, the translator writes C code that represents the actions |
| 2203 |
of all selected script files, and creates a |
| 2204 |
.IR Makefile |
| 2205 |
to build that into a kernel object. These files are placed into a |
| 2206 |
temporary directory. Stopping the translator at this point causes |
| 2207 |
it to print the contents of the C file. |
| 2208 |
|
| 2209 |
.PP |
| 2210 |
In pass 4, the translator invokes the Linux kernel build system to |
| 2211 |
create the actual kernel object file. This involves running |
| 2212 |
.IR make |
| 2213 |
in the temporary directory, and requires a kernel module build |
| 2214 |
system (headers, config and Makefiles) to be installed in the usual |
| 2215 |
spot |
| 2216 |
.IR /lib/modules/VERSION/build . |
| 2217 |
Stopping the translator after pass 4 is the last chance before |
| 2218 |
running the kernel object. This may be useful if you want to |
| 2219 |
archive the file. |
| 2220 |
|
| 2221 |
.PP |
| 2222 |
In pass 5, the translator invokes the systemtap auxiliary program |
| 2223 |
.I staprun |
| 2224 |
program for the given kernel object. This program arranges to load |
| 2225 |
the module then communicates with it, copying trace data from the |
| 2226 |
kernel into temporary files, until the user sends an interrupt signal. |
| 2227 |
Any run-time error encountered by the probe handlers, such as running |
| 2228 |
out of memory, division by zero, exceeding nesting or runtime limits, |
| 2229 |
results in a soft error indication. Soft errors in excess of |
| 2230 |
MAXERRORS block of all subsequent probes (except error-handling |
| 2231 |
probes), and terminate the session. Finally, |
| 2232 |
.I staprun |
| 2233 |
unloads the module, and cleans up. |
| 2234 |
|
| 2235 |
.SS ABNORMAL TERMINATION |
| 2236 |
|
| 2237 |
One should avoid killing the stap process forcibly, for example with |
| 2238 |
SIGKILL, because the stapio process (a child process of the stap |
| 2239 |
process) and the loaded module may be left running on the system. If |
| 2240 |
this happens, send SIGTERM or SIGINT to any remaining stapio |
| 2241 |
processes, then use rmmod to unload the systemtap module. |
| 2242 |
|
| 2243 |
|
| 2244 |
.SH EXAMPLES |
| 2245 |
See the |
| 2246 |
.IR stapex (3stap) |
| 2247 |
manual page for a brief collection of samples, or a large set of |
| 2248 |
installed samples under the systemtap documentation/testsuite |
| 2249 |
directories. See |
| 2250 |
.IR stappaths (7stap) |
| 2251 |
for the likely location of these on the system. |
| 2252 |
|
| 2253 |
.SH CACHING |
| 2254 |
The systemtap translator caches the pass 3 output (the generated C |
| 2255 |
code) and the pass 4 output (the compiled kernel module) if pass 4 |
| 2256 |
completes successfully. This cached output is reused if the same |
| 2257 |
script is translated again assuming the same conditions exist (same kernel |
| 2258 |
version, same systemtap version, etc.). Cached files are stored in |
| 2259 |
the |
| 2260 |
.I $SYSTEMTAP_DIR/cache |
| 2261 |
directory. The cache can be limited by having the file |
| 2262 |
.I cache_mb_limit |
| 2263 |
placed in the cache directory (shown above) containing only an ASCII |
| 2264 |
integer representing how many MiB the cache should not exceed. In the |
| 2265 |
absence of this file, a default will be created with the limit set to 256MiB. |
| 2266 |
This is a 'soft' limit in that the cache will be cleaned after a new entry |
| 2267 |
is added if the cache clean interval is exceeded, so the total cache size may |
| 2268 |
temporarily exceed this limit. This interval can be specified by having the |
| 2269 |
file |
| 2270 |
.I cache_clean_interval_s |
| 2271 |
placed in the cache directory (shown above) containing only an ASCII integer |
| 2272 |
representing the interval in seconds. In the absence of this file, a default |
| 2273 |
will be created with the interval set to 300 s. |
| 2274 |
|
| 2275 |
.SH SAFETY AND SECURITY |
| 2276 |
|
| 2277 |
.PP |
| 2278 |
Systemtap may be used as a powerful administrative tool. It can |
| 2279 |
expose kernel internal data structures and potentially private user |
| 2280 |
information. (In |
| 2281 |
.BR dyninst |
| 2282 |
runtime mode, this is not the case, see the |
| 2283 |
.I ALTERNATE RUNTIMES |
| 2284 |
section below.) |
| 2285 |
|
| 2286 |
The translator asserts many safety constraints during compilation and |
| 2287 |
more during run-time. It aims to ensure that no handler routine can |
| 2288 |
run for very long, allocate boundless memory, perform unsafe |
| 2289 |
operations, or in unintentionally interfere with the system. Uses of |
| 2290 |
script global variables are automatically read/write locked as |
| 2291 |
appropriate, to protect against manipulation by concurrent probe |
| 2292 |
handlers. Locks are taken so as to run the global-variable |
| 2293 |
manipulation portion of probe handlers atomically (locks are taken |
| 2294 |
all-or-none). Deadlocks are detected with timeouts. Use the |
| 2295 |
.BR \-t |
| 2296 |
flag to receive reports of excessive lock contention. Experimenting |
| 2297 |
with scripts is therefore generally |
| 2298 |
.BR safe . |
| 2299 |
The guru-mode |
| 2300 |
.B \-g |
| 2301 |
option allows administrators to bypass most safety measures, which |
| 2302 |
permits invasive or state-changing operations, embedded-C code, and |
| 2303 |
increases the risk of upset. By default, overload prevention is |
| 2304 |
turned on for all modules. If you would like to disable overload |
| 2305 |
processing, use the |
| 2306 |
.BR \-\-suppress\-time\-limits |
| 2307 |
option. |
| 2308 |
|
| 2309 |
Errors that are caught at run time normally result in a clean script |
| 2310 |
shutdown and a pass-5 error message. |
| 2311 |
The |
| 2312 |
.BR \-\-suppress\-handler\-errors |
| 2313 |
option lets scripts tolerate soft errors without shutting down. |
| 2314 |
|
| 2315 |
|
| 2316 |
.SS PERMISSIONS |
| 2317 |
|
| 2318 |
For the normal linux-kernel-module runtime, to run the kernel objects systemtap |
| 2319 |
builds, a user must be one of the following: |
| 2320 |
.IP \(bu 4 |
| 2321 |
the root user; |
| 2322 |
.IP \(bu 4 |
| 2323 |
a member of the |
| 2324 |
.I stapdev |
| 2325 |
and |
| 2326 |
.I stapusr |
| 2327 |
groups; |
| 2328 |
.IP \(bu 4 |
| 2329 |
a member of the |
| 2330 |
.I stapsys |
| 2331 |
and |
| 2332 |
.I stapusr |
| 2333 |
groups; or |
| 2334 |
.IP \(bu 4 |
| 2335 |
a member of the |
| 2336 |
.I stapusr |
| 2337 |
group. |
| 2338 |
.PP |
| 2339 |
The root user or a user who is a member of both the |
| 2340 |
.I stapdev |
| 2341 |
and |
| 2342 |
.I stapusr |
| 2343 |
groups can build and run any systemtap script. |
| 2344 |
.PP |
| 2345 |
A user who is a member of both the |
| 2346 |
.I stapsys |
| 2347 |
and |
| 2348 |
.I stapusr |
| 2349 |
groups can only use pre\-built modules under the following conditions: |
| 2350 |
.IP \(bu 4 |
| 2351 |
The module has been signed by a trusted signer. Trusted signers are normally |
| 2352 |
systemtap compile\-servers which sign modules when the \fI\-\-privilege\fR option is |
| 2353 |
specified by the client. See the |
| 2354 |
.IR stap\-server (8) |
| 2355 |
manual page for more information. |
| 2356 |
.IP \(bu 4 |
| 2357 |
The module was built using the \fI\-\-privilege=stapsys\fR or the \fI\-\-privilege=stapusr\fR |
| 2358 |
options. |
| 2359 |
.PP |
| 2360 |
Members of only the |
| 2361 |
.I stapusr |
| 2362 |
group can only use pre\-built modules under the following conditions: |
| 2363 |
.IP \(bu 4 |
| 2364 |
The module is located in |
| 2365 |
the /lib/modules/VERSION/systemtap directory. This directory |
| 2366 |
must be owned by root and not be world writable. |
| 2367 |
.PP |
| 2368 |
or |
| 2369 |
.IP \(bu 4 |
| 2370 |
The module has been signed by a trusted signer. Trusted signers are normally |
| 2371 |
systemtap compile\-servers which sign modules when the \fI\-\-privilege\fR option is |
| 2372 |
specified by the client. See the |
| 2373 |
.IR stap\-server (8) |
| 2374 |
manual page for more information. |
| 2375 |
.IP \(bu 4 |
| 2376 |
The module was built using the \FI\-\-privilege=stapusr\fR option. |
| 2377 |
.PP |
| 2378 |
The kernel modules generated by |
| 2379 |
.I stap |
| 2380 |
program are run by the |
| 2381 |
.IR staprun |
| 2382 |
program. The latter is a part of the Systemtap package, dedicated to |
| 2383 |
module loading and unloading (but only in the white zone), and |
| 2384 |
kernel-to-user data transfer. Since |
| 2385 |
.IR staprun |
| 2386 |
does not perform any additional security checks on the kernel objects |
| 2387 |
it is given, it would be unwise for a system administrator to add |
| 2388 |
untrusted users to the |
| 2389 |
.I stapdev |
| 2390 |
or |
| 2391 |
.I stapusr |
| 2392 |
groups. |
| 2393 |
|
| 2394 |
.SS SECUREBOOT |
| 2395 |
|
| 2396 |
If the current system has SecureBoot turned on in the UEFI firmware, |
| 2397 |
all kernel modules must be signed. (Some kernels may allow disabling |
| 2398 |
SecureBoot long after booting with a key sequence such as SysRq-X, |
| 2399 |
making it unnecessary to sign modules.) There are two ways to sign a |
| 2400 |
systemtap module. The systemtap compile server |
| 2401 |
can sign modules with a MOK (Machine Owner Key) that it has in common |
| 2402 |
with a client system. For example: |
| 2403 |
.SAMPLE |
| 2404 |
stap \-\-use-server=HOSTNAME:PORT \-e 'SCRIPT' |
| 2405 |
# If there is no mok key in common with the server's systemtap mok key |
| 2406 |
# list and the client's mok database then the user is directed by stap |
| 2407 |
# to invoke: |
| 2408 |
sudo mokutil --import signing_key.x509 |
| 2409 |
# then after rebooting the system: |
| 2410 |
stap \-\-use-server=HOSTNAME:PORT \-e 'SCRIPT' |
| 2411 |
# will use the server to build and sign the module and the module will run |
| 2412 |
# on the client |
| 2413 |
.ESAMPLE |
| 2414 |
Another way to sign modules is to use the stap |
| 2415 |
\FI\-\-sign-module\FR option, which uses a MOK on the client system |
| 2416 |
without using a server. |
| 2417 |
For example: |
| 2418 |
.SAMPLE |
| 2419 |
stap \-\-sign-module \-e 'SCRIPT' |
| 2420 |
# If there is no systemtap mok key in the system mok database |
| 2421 |
# then the user is directed by stap to invoke: |
| 2422 |
sudo mokutil --import \ |
| 2423 |
/home/USER/.systemtap/ssl/server/moks/FINGERPRINT/signing_key.x509 |
| 2424 |
# then after rebooting the system: |
| 2425 |
stap \-\-sign-module \-e 'SCRIPT' |
| 2426 |
# will sign and run the module |
| 2427 |
.ESAMPLE |
| 2428 |
|
| 2429 |
See the following wiki page for more details: |
| 2430 |
.PP |
| 2431 |
.RS |
| 2432 |
.nh |
| 2433 |
.BR https://sourceware.org/systemtap/wiki/SecureBoot |
| 2434 |
.hy |
| 2435 |
.RE |
| 2436 |
|
| 2437 |
Some kernels do not let systemtap guess whether module module signing |
| 2438 |
is in effect. On such machines, set the SYSTEMTAP_SIGN environment |
| 2439 |
variable to any value while running stap. |
| 2440 |
|
| 2441 |
.SS RESOURCE LIMITS |
| 2442 |
Many resource use limits are set by macros in the generated C code. |
| 2443 |
These may be overridden with |
| 2444 |
.BR \-D |
| 2445 |
flags. A selection of these is as follows: |
| 2446 |
.TP |
| 2447 |
MAXNESTING |
| 2448 |
Maximum number of nested function calls. Default determined by |
| 2449 |
script analysis, with a bonus 10 slots added for recursive |
| 2450 |
scripts. |
| 2451 |
.TP |
| 2452 |
MAXSTRINGLEN |
| 2453 |
Maximum length of strings, default 128. |
| 2454 |
.TP |
| 2455 |
MAXTRYLOCK |
| 2456 |
Maximum number of iterations to wait for locks on global variables |
| 2457 |
before declaring possible deadlock and skipping the probe, default 1000. |
| 2458 |
.TP |
| 2459 |
MAXACTION |
| 2460 |
Maximum number of statements to execute during any single probe hit |
| 2461 |
(with interrupts disabled), |
| 2462 |
default 1000. |
| 2463 |
Note that for straight-through probe handlers lacking loops or recursion, |
| 2464 |
due to optimization, this parameter may be interpreted too conservatively. |
| 2465 |
.TP |
| 2466 |
MAXACTION_INTERRUPTIBLE |
| 2467 |
Maximum number of statements to execute during any single probe hit |
| 2468 |
which is executed with interrupts enabled (such as begin/end probes), |
| 2469 |
default (MAXACTION * 10). |
| 2470 |
.TP |
| 2471 |
MAXBACKTRACE |
| 2472 |
Maximum number of stack frames that will be be processed by the stap |
| 2473 |
runtime unwinder as produced by the backtrace functions in the |
| 2474 |
[u]context-unwind.stp tapsets, default 20. |
| 2475 |
.TP |
| 2476 |
MAXMAPENTRIES |
| 2477 |
Maximum number of rows in any single global array, default 2048. |
| 2478 |
Individual arrays may be declared with a larger or smaller limit instead: |
| 2479 |
.SAMPLE |
| 2480 |
global big[10000],little[5] |
| 2481 |
.ESAMPLE |
| 2482 |
or denoted with |
| 2483 |
.IR % |
| 2484 |
to make them wrap-around (replace old entries) automatically, as in |
| 2485 |
.SAMPLE |
| 2486 |
global big% |
| 2487 |
.ESAMPLE |
| 2488 |
or both. |
| 2489 |
.TP |
| 2490 |
MAPHASHBIAS |
| 2491 |
The number of powers-of-two to add or subtract from the natural size of the |
| 2492 |
hash table backing each global associative array. Default is 0. Try small |
| 2493 |
positive numbers to get extra performance at the cost of more memory |
| 2494 |
consumption, because that should reduce hash table collisions. |
| 2495 |
Try small negative numbers for the opposite tradeoff. |
| 2496 |
.TP |
| 2497 |
MAXERRORS |
| 2498 |
Maximum number of soft errors before an exit is triggered, default 0, which |
| 2499 |
means that the first error will exit the script. Note that with the |
| 2500 |
.B \-\-suppress\-handler\-errors |
| 2501 |
option, this limit is not enforced. |
| 2502 |
.TP |
| 2503 |
MAXSKIPPED |
| 2504 |
Maximum number of skipped probes before an exit is triggered, default 100. |
| 2505 |
Running systemtap with \-t (timing) mode gives more details about skipped |
| 2506 |
probes. With the default \-DINTERRUPTIBLE=1 setting, probes skipped due to |
| 2507 |
reentrancy are not accumulated against this limit. Note that with the |
| 2508 |
.B \-\-suppress\-handler\-errors |
| 2509 |
option, this limit is not enforced. |
| 2510 |
.TP |
| 2511 |
MINSTACKSPACE |
| 2512 |
Minimum number of free kernel stack bytes required in order to |
| 2513 |
run a probe handler, default 1024. This number should be large enough |
| 2514 |
for the probe handler's own needs, plus a safety margin. |
| 2515 |
.TP |
| 2516 |
MAXUPROBES |
| 2517 |
Maximum number of concurrently armed user-space probes (uprobes), default |
| 2518 |
somewhat larger than the number of user-space probe points named in the script. |
| 2519 |
This pool needs to be potentially large because individual uprobe objects (about |
| 2520 |
64 bytes each) are allocated for each process for each matching script-level probe. |
| 2521 |
.TP |
| 2522 |
STP_MAXMEMORY |
| 2523 |
Maximum amount of memory (in kilobytes) that the systemtap module |
| 2524 |
should use, default unlimited. The memory size includes the size of |
| 2525 |
the module itself, plus any additional allocations. This only tracks |
| 2526 |
direct allocations by the systemtap runtime. This does not track |
| 2527 |
indirect allocations (as done by kprobes/uprobes/etc. internals). |
| 2528 |
.TP |
| 2529 |
STP_OVERLOAD_THRESHOLD, STP_OVERLOAD_INTERVAL |
| 2530 |
Maximum number of machine cycles spent in probes on any cpu per given |
| 2531 |
interval, before an overload condition is declared and the script shut |
| 2532 |
down. The defaults are 500 million and 1 billion, so as to limit stap |
| 2533 |
script cpu consumption at around 50%. |
| 2534 |
.TP |
| 2535 |
STP_PROCFS_BUFSIZE |
| 2536 |
Size of procfs probe read buffers (in bytes). Defaults to |
| 2537 |
.IR MAXSTRINGLEN . |
| 2538 |
This value can be overridden on a per-procfs file basis using the |
| 2539 |
procfs read probe |
| 2540 |
.I .maxsize(MAXSIZE) |
| 2541 |
parameter. |
| 2542 |
.PP |
| 2543 |
With scripts that contain probes on any interrupt path, it is possible that |
| 2544 |
those interrupts may occur in the middle of another probe handler. The probe |
| 2545 |
in the interrupt handler would be skipped in this case to avoid reentrance. |
| 2546 |
To work around this issue, execute stap with the option |
| 2547 |
.BR \-DINTERRUPTIBLE=0 |
| 2548 |
to mask interrupts throughout the probe handler. This does add some extra |
| 2549 |
overhead to the probes, but it may prevent reentrance for common problem |
| 2550 |
cases. However, probes in NMI handlers and in the callpath of the stap |
| 2551 |
runtime may still be skipped due to reentrance. |
| 2552 |
|
| 2553 |
.PP |
| 2554 |
In case something goes wrong with |
| 2555 |
.IR stap " or " staprun |
| 2556 |
after a probe has already started running, one may safely kill both |
| 2557 |
user processes, and remove the active probe kernel module with |
| 2558 |
.IR rmmod . |
| 2559 |
Any pending trace messages may be lost. |
| 2560 |
|
| 2561 |
.SH UNPRIVILEGED USERS |
| 2562 |
|
| 2563 |
.PP |
| 2564 |
Systemtap exposes kernel internal data |
| 2565 |
structures and potentially private user information. Because of this, use of |
| 2566 |
systemtap's full capabilities are restricted to root and to users who are |
| 2567 |
members of the groups stapdev and stapusr. |
| 2568 |
|
| 2569 |
However, a restricted set of systemtap's features can be made available to |
| 2570 |
trusted, unprivileged users. These users are members of the group stapusr |
| 2571 |
only, or members of the groups stapusr and stapsys. |
| 2572 |
These users can load systemtap modules which have been compiled and |
| 2573 |
certified by a trusted systemtap compile\-server. See the descriptions of the |
| 2574 |
options \fI\-\-privilege\fR and \fI\-\-use\-server\fR. See |
| 2575 |
\fIREADME.unprivileged\fR in the systemtap source code for information about |
| 2576 |
setting up a trusted compile server. |
| 2577 |
|
| 2578 |
The restrictions enforced when \fI\-\-privilege=stapsys\fR is specified are designed |
| 2579 |
to prevent unprivileged users from: |
| 2580 |
.RS |
| 2581 |
.IP \(bu 4 |
| 2582 |
harming the system maliciously. |
| 2583 |
.RE |
| 2584 |
|
| 2585 |
The restrictions enforced when \fI\-\-privilege=stapusr\fR is specified are designed |
| 2586 |
to prevent unprivileged users from: |
| 2587 |
.RS |
| 2588 |
.IP \(bu 4 |
| 2589 |
harming the system maliciously. |
| 2590 |
.IP \(bu 4 |
| 2591 |
gaining access to information which would not normally be available to an |
| 2592 |
unprivileged user. |
| 2593 |
.IP \(bu 4 |
| 2594 |
disrupting the performance of processes owned by other users of the system. |
| 2595 |
Some overhead to the system in general is unavoidable since the |
| 2596 |
unprivileged user's probes |
| 2597 |
will be triggered at the appropriate times. What we would like to avoid is |
| 2598 |
targeted interruption of another user's processes which would not normally be |
| 2599 |
possible by an unprivileged user. |
| 2600 |
.RE |
| 2601 |
|
| 2602 |
.SS PROBE RESTRICTIONS |
| 2603 |
A member of the groups stapusr and stapsys may use all probe points. |
| 2604 |
.PP |
| 2605 |
A member of only the group stapusr may use only the following probes: |
| 2606 |
.RS |
| 2607 |
.IP \(bu 4 |
| 2608 |
begin, begin(n) |
| 2609 |
.IP \(bu 4 |
| 2610 |
end, end(n) |
| 2611 |
.IP \(bu 4 |
| 2612 |
error(n) |
| 2613 |
.IP \(bu 4 |
| 2614 |
never |
| 2615 |
.IP \(bu 4 |
| 2616 |
process.*, where the target process is owned by the user. |
| 2617 |
.IP \(bu 4 |
| 2618 |
timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)* |
| 2619 |
.IP \(bu 4 |
| 2620 |
timer.hz(n) |
| 2621 |
.RE |
| 2622 |
|
| 2623 |
.SS SCRIPT LANGUAGE RESTRICTIONS |
| 2624 |
The following scripting language features are unavailable to all unprivileged users: |
| 2625 |
|
| 2626 |
.RS |
| 2627 |
.IP \(bu 4 |
| 2628 |
any feature enabled by the Guru Mode (\-g) option. |
| 2629 |
.IP \(bu 4 |
| 2630 |
embedded C code. |
| 2631 |
.RE |
| 2632 |
|
| 2633 |
.SS RUNTIME RESTRICTIONS |
| 2634 |
The following runtime restrictions are placed upon all unprivileged users: |
| 2635 |
.RS |
| 2636 |
.IP \(bu 4 |
| 2637 |
Only the default runtime code (see \fI-R\fR) may be used. |
| 2638 |
.RE |
| 2639 |
|
| 2640 |
Additional restrictions are placed on members of only the group stapusr: |
| 2641 |
.RS |
| 2642 |
.IP \(bu 4 |
| 2643 |
Probing of processes owned by other users is not permitted. |
| 2644 |
.IP \(bu 4 |
| 2645 |
Access of kernel memory (read and write) is not permitted. |
| 2646 |
.RE |
| 2647 |
|
| 2648 |
.SS COMMAND LINE OPTION RESTRICTIONS |
| 2649 |
Some command line options provide access to features which must not be available |
| 2650 |
to all unprivileged users: |
| 2651 |
|
| 2652 |
.RS |
| 2653 |
.IP \(bu 4 |
| 2654 |
\-g may not be specified. |
| 2655 |
.IP \(bu 4 |
| 2656 |
The following options may not be used by the compile-server client: |
| 2657 |
.SAMPLE |
| 2658 |
\-a, \-B, \-D, \-I, \-r, \-R |
| 2659 |
.ESAMPLE |
| 2660 |
.RE |
| 2661 |
|
| 2662 |
.SS ENVIRONMENT RESTRICTIONS |
| 2663 |
The following environment variables must not be set for all unprivileged users: |
| 2664 |
.SAMPLE |
| 2665 |
SYSTEMTAP_RUNTIME |
| 2666 |
SYSTEMTAP_TAPSET |
| 2667 |
SYSTEMTAP_DEBUGINFO_PATH |
| 2668 |
.ESAMPLE |
| 2669 |
|
| 2670 |
.SS TAPSET RESTRICTIONS |
| 2671 |
In general, tapset functions are only available for members of the |
| 2672 |
group stapusr when they do not gather information that an ordinary |
| 2673 |
program running with that user's privileges would be denied access to. |
| 2674 |
|
| 2675 |
There are two categories of unprivileged tapset functions. The first |
| 2676 |
category consists of utility functions that are unconditionally |
| 2677 |
available to all users; these include such things as: |
| 2678 |
.SAMPLE |
| 2679 |
cpu:long () |
| 2680 |
exit () |
| 2681 |
str_replace:string (prnt_str:string, srch_str:string, rplc_str:string) |
| 2682 |
.ESAMPLE |
| 2683 |
|
| 2684 |
The second category consists of so-called |
| 2685 |
.I myproc-unprivileged |
| 2686 |
functions that can only gather information within their own |
| 2687 |
processes. Scripts that wish to use these functions must test the |
| 2688 |
result of the tapset function \fIis_myproc\fR and only call these |
| 2689 |
functions if the result is 1. The script will exit immediately if any |
| 2690 |
of these functions are called by an unprivileged user within a probe |
| 2691 |
within a process which is not owned by that user. Examples of |
| 2692 |
.I myproc-unprivileged |
| 2693 |
functions include: |
| 2694 |
.SAMPLE |
| 2695 |
print_usyms (stk:string) |
| 2696 |
user_int:long (addr:long) |
| 2697 |
usymname:string (addr:long) |
| 2698 |
.ESAMPLE |
| 2699 |
|
| 2700 |
A compile error is triggered when any function not in either of the |
| 2701 |
above categories is used by members of only the group stapusr. |
| 2702 |
|
| 2703 |
No other built-in tapset functions may be used by members of only the |
| 2704 |
group stapusr. |
| 2705 |
|
| 2706 |
.SH ALTERNATE RUNTIMES |
| 2707 |
|
| 2708 |
.PP |
| 2709 |
As described above, systemtap's default runtime mode involves building and |
| 2710 |
loading kernel modules, with various security tradeoffs presented. Systemtap |
| 2711 |
now includes two new prototype backends: \fI\-\-runtime=dyninst\fR and |
| 2712 |
\fI\-\-runtime=bpf\fR. |
| 2713 |
|
| 2714 |
\fI\-\-runtime=dyninst\fR uses Dyninst to instrument a user's own processes |
| 2715 |
at runtime. This backend does not use kernel modules, and does not require |
| 2716 |
root privileges, but is restricted with respect to the kinds of probes and |
| 2717 |
other constructs that a script may use. \fIdyninst\fR runtime operates in |
| 2718 |
target-attach mode, so it does require a \fI\-c COMMAND\fR or \fI\-x PID\fR |
| 2719 |
process. For example: |
| 2720 |
.SAMPLE |
| 2721 |
stap \-\-runtime=dyninst \-c 'stap \-V' \\ |
| 2722 |
\-e 'probe process.function("main") |
| 2723 |
{ println("hi from dyninst!") }' |
| 2724 |
.ESAMPLE |
| 2725 |
|
| 2726 |
It may be necessary to disable a conflicting selinux check with |
| 2727 |
.SAMPLE |
| 2728 |
# setsebool allow_execstack 1 |
| 2729 |
.ESAMPLE |
| 2730 |
|
| 2731 |
\fI\-\-runtime=bpf\fR compiles the user script into extended Berkeley Packet |
| 2732 |
Filter (eBPF) programs instead of a kernel module. eBPF programs are verified |
| 2733 |
by the kernel for safety and are executed by an in-kernel virtual machine. |
| 2734 |
This runtime is in an early stage of development and currently lacks support |
| 2735 |
for a number of features available in the default runtime. Please see the |
| 2736 |
\fIstapbpf\fR(8) man page for more information. |
| 2737 |
|
| 2738 |
.SH EXIT STATUS |
| 2739 |
|
| 2740 |
The systemtap translator generally returns with a success code of 0 if |
| 2741 |
the requested script was processed and executed successfully through |
| 2742 |
the requested pass. Otherwise, errors may be printed to stderr and |
| 2743 |
a failure code is returned. Use |
| 2744 |
.I \-v |
| 2745 |
or |
| 2746 |
.I \-vp N |
| 2747 |
to increase (global or per-pass) verbosity to identify the source of the |
| 2748 |
trouble. |
| 2749 |
|
| 2750 |
In listings mode |
| 2751 |
.RI ( \-l " and " \-L ), |
| 2752 |
error messages are normally suppressed. A success code of 0 is returned |
| 2753 |
if at least one matching probe was found. |
| 2754 |
|
| 2755 |
A script executing in pass 5 that is interrupted with ^C / SIGINT is |
| 2756 |
considered to be successful. |
| 2757 |
|
| 2758 |
.SH DEPRECATION |
| 2759 |
|
| 2760 |
Over time, some features of the script language and the tapset library |
| 2761 |
may undergo incompatible changes, so that a script written against |
| 2762 |
an old version of systemtap may no longer run. In these cases, it may |
| 2763 |
help to run systemtap with the |
| 2764 |
.I \-\-compatible VERSION |
| 2765 |
flag, specifying the last known working version. Running |
| 2766 |
systemtap with the |
| 2767 |
.I \-\-check\-version |
| 2768 |
flag will output a warning if any possible incompatible elements have |
| 2769 |
been parsed. Deprecation historical details may be found in the NEWS file. |
| 2770 |
|
| 2771 |
The purpose of deprecation facility is to improve the experience of |
| 2772 |
scripts written for newer versions of systemtap (by adding better |
| 2773 |
alternatives and removing conflicting or messy older alternatives), |
| 2774 |
while at the same time permitting scripts written for older versions |
| 2775 |
of systemtap to continue running. Deprecation is thus intended a |
| 2776 |
.I service to users |
| 2777 |
(and an inconvenience to systemtap's developers), rather than the |
| 2778 |
other way around. |
| 2779 |
|
| 2780 |
Please note that underscore-prefixed identifiers in the tapset |
| 2781 |
sometimes undergo such changes that are difficult to preserve |
| 2782 |
compatibility for, even with the deprecation mechanisms. Avoid |
| 2783 |
relying on these in your scripts; instead propose them for promotion |
| 2784 |
to non-underscored status. |
| 2785 |
|
| 2786 |
|
| 2787 |
.SH FILES |
| 2788 |
.TP |
| 2789 |
Important files and their corresponding paths can be located in the |
| 2790 |
stappaths (7) manual page. |
| 2791 |
|
| 2792 |
.SH SEE ALSO |
| 2793 |
.nh |
| 2794 |
.nf |
| 2795 |
.IR stapprobes (3stap), |
| 2796 |
.IR function::* (3stap), |
| 2797 |
.IR probe::* (3stap), |
| 2798 |
.IR tapset::* (3stap), |
| 2799 |
.IR stappaths (7), |
| 2800 |
.IR staprun (8), |
| 2801 |
.IR stapdyn (8), |
| 2802 |
.IR systemtap (8), |
| 2803 |
.IR stapvars (3stap), |
| 2804 |
.IR stapex (3stap), |
| 2805 |
.IR stap\-server (8), |
| 2806 |
.IR stap\-prep (1), |
| 2807 |
.IR stapref (1), |
| 2808 |
.IR awk (1), |
| 2809 |
.IR gdb (1) |
| 2810 |
|
| 2811 |
.SH BUGS |
| 2812 |
Use the Bugzilla link of the project web page or our mailing list. |
| 2813 |
.nh |
| 2814 |
.BR http://sourceware.org/systemtap/ ", " <[email protected]> . |
| 2815 |
.hy |
| 2816 |
.PP |
| 2817 |
.IR error::reporting (7stap), |
| 2818 |
.nh |
| 2819 |
.BR https://sourceware.org/systemtap/wiki/HowToReportBugs |
| 2820 |
.hy |