Debian Codegraph @

man/stap.1.in

raw
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