-
Notifications
You must be signed in to change notification settings - Fork 20
/
stap.1
2111 lines (2011 loc) · 69.4 KB
/
stap.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" -*- nroff -*-
.TH STAP 1
.SH NAME
stap \- systemtap script translator/driver
.\" macros
.de SAMPLE
.br
.RS
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..
.SH SYNOPSIS
.br
.B stap
[
.I OPTIONS
]
.I FILENAME
[
.I ARGUMENTS
]
.br
.B stap
[
.I OPTIONS
]
.B \-
[
.I ARGUMENTS
]
.br
.B stap
[
.I OPTIONS
]
.BI \-e " SCRIPT"
[
.I ARGUMENTS
]
.br
.B stap
[
.I OPTIONS
]
.BI \-l " PROBE"
[
.I ARGUMENTS
]
.br
.B stap
[
.I OPTIONS
]
.BI \-L " PROBE"
[
.I ARGUMENTS
]
.SH DESCRIPTION
The
.IR stap
program is the front-end to the Systemtap tool. It accepts probing
instructions (written in a simple scripting language), translates
those instructions into C code, compiles this C code, and loads the
resulting kernel module into a running Linux kernel to perform the
requested system trace/probe functions. You can supply the script in
a named file (FILENAME) from standard input (use \- instead of FILENAME),
or from the command line (using \-e SCRIPT). The program runs until it
is interrupted by the user, or if the script voluntarily invokes the
.I exit()
function, or by sufficient number of soft errors.
.PP
The language, which is described in a later section, is strictly typed,
declaration free, procedural, and inspired by
.IR awk .
It allows source code points or events in the kernel to be associated
with handlers, which are subroutines that are executed synchronously. It is
somewhat similar conceptually to "breakpoint command lists" in the
.IR gdb
debugger.
.SH OPTIONS
The systemtap translator supports the following options. Any other option
prints a list of supported options. Options may be given on the command line,
as usual. If the file $SYSTEMTAP_DIR/rc exist, options are also loaded from
there and interpreted first. ($SYSTEMTAP_DIR defaults to $HOME/.systemtap if unset.)
.TP
.B \-
Use standard input instead of a given FILENAME as probe language input,
unless -e SCRIPT is given.
.TP
.B \-h \-\-help
Show help message.
.TP
.B \-V \-\-version
Show version message.
.TP
.BI \-p " NUM"
Stop after pass NUM. The passes are numbered 1-5: parse, elaborate,
translate, compile, run. See the
.B PROCESSING
section for details.
.TP
.B \-v
Increase verbosity for all passes. Produce a larger volume of
informative (?) output each time option repeated.
.TP
.B \-\-vp ABCDE
Increase verbosity on a per-pass basis. For example, "\-\-vp\ 002"
adds 2 units of verbosity to pass 3 only. The combination "\-v\ \-\-vp\ 00004"
adds 1 unit of verbosity for all passes, and 4 more for pass 5.
.TP
.B \-k
Keep the temporary directory after all processing. This may be useful
in order to examine the generated C code, or to reuse the compiled
kernel object.
.TP
.B \-g
Guru mode. Enable parsing of unsafe expert-level constructs like
embedded C.
.TP
.B \-P
Prologue-searching mode. Activate heuristics to work around incorrect
debugging information for $target variables.
.TP
.B \-u
Unoptimized mode. Disable unused code elision during elaboration.
.TP
.B \-w
Suppressed warnings mode. Disables all warning messages.
.TP
.BI \-b
Use bulk mode (percpu files) for kernel-to-user data transfer.
.TP
.B \-t
Collect timing information on the number of times probe executes
and average amount of time spent in each probe-point. Also shows
the derivation for each probe-point.
.TP
.BI \-s NUM
Use NUM megabyte buffers for kernel-to-user data transfer. On a
multiprocessor in bulk mode, this is a per-processor amount.
.TP
.BI \-I " DIR"
Add the given directory to the tapset search directory. See the
description of pass 2 for details.
.TP
.BI \-D " NAME=VALUE"
Add the given C preprocessor directive to the module Makefile. These can
be used to override limit parameters described below.
.TP
.BI \-B " NAME=VALUE"
Add the given make directive to the kernel module build's make invocation.
These can be used to add or override kconfig options.
.TP
.BI \-\-modinfo " NAME=VALUE"
Add the name/value pair as a MODULE_INFO macro call to the generated module.
This may be useful to inform or override various module-related checks in
the kernel.
.TP
.BI \-G " NAME=VALUE"
Sets the value of global variable NAME to VALUE when staprun is invoked.
This applies to scalar variables declared global in the script/tapset.
.TP
.BI \-R " DIR"
Look for the systemtap runtime sources in the given directory.
.TP
.BI \-r " /DIR"
Build for kernel in given build tree. Can also be set with the
.I SYSTEMTAP_RELEASE
environment variable.
.TP
.BI \-r " RELEASE"
Build for kernel in build tree
.BR /lib/modules/RELEASE/build .
Can also be set with the
.I SYSTEMTAP_RELEASE
environment variable.
.TP
.BI \-m " MODULE"
Use the given name for the generated kernel object module, instead
of a unique randomized name. The generated kernel object module is
copied to the current directory.
.TP
.BI \-d " MODULE"
Add symbol/unwind information for the given module into the kernel object
module. This may enable symbolic tracebacks from those modules/programs,
even if they do not have an explicit probe placed into them.
.TP
.BI \-\-ldd
Add symbol/unwind information for all shared libraries suspected by
ldd to be necessary for user-space binaries being probe or listed with
the \-d option. Caution: this can make the probe modules considerably
larger.
.TP
.BI \-\-all\-modules
Equivalent to specifying "\-dkernel" and a "\-d" for each kernel module that is
currently loaded. Caution: this can make the probe modules considerably
larger.
.TP
.BI \-o " FILE"
Send standard output to named file. In bulk mode, percpu files will
start with FILE_ (FILE_cpu with \-F) followed by the cpu number.
This supports strftime(3) formats for FILE.
.TP
.BI \-c " CMD"
Start the probes, run CMD, and exit when CMD finishes. This also has the
effect of setting target() to the pid of the command ran.
.TP
.BI \-x " PID"
Sets target() to PID. This allows scripts to be written that filter on
a specific process.
.TP
.BI \-e " SCRIPT"
Run the given SCRIPT specified on the command line.
.TP
.BI \-l " PROBE"
Instead of running a probe script, just list all available probe
points matching the given single probe point. The pattern may include
wildcards and aliases, but not comma-separated multiple probe points.
The process result code will indicate failure if there are no matches.
.TP
.BI \-L " PROBE"
Similar to "\-l", but list probe points and script-level local variables.
.TP
.BI \-F
Without \-o option, load module and start probes, then detach from the module
leaving the probes running.
With \-o option, run staprun in background as a daemon and show its pid.
.TP
.BI \-S " size[,N]"
Sets the maximum size of output file and the maximum number of output files.
If the size of output file will exceed
.B size
, systemtap switches output file to the next file. And if the number of
output files exceed
.B N
, systemtap removes the oldest output file. You can omit the second argument.
.\" PR6864: disable temporarily
.\".TP
.\".B \-\-kelf
.\"For names and addresses of functions to probe,
.\"consult the symbol tables in the kernel and modules.
.\"This can be useful if your kernel and/or modules were compiled
.\"without debugging information, or the function you want to probe
.\"is in an assembly-language file built without debugging information.
.\"See the
.\".B "MAKING DO WITH SYMBOL TABLES"
.\"section for more information.
.\".TP
.\".BI \-\-kmap [=FILE]
.\"For names and addresses of kernel functions to probe,
.\"consult the symbol table in the indicated text file.
.\"The default is /boot/System.map\-VERSION.
.\"The contents of this file should be in the form of the default output from
.\".IR nm (1).
.\"Only symbols of type T or t are used.
.\"If you specify /proc/kallsyms or some other file in that format,
.\"where lines for module symbols contain a fourth column,
.\"reading of the symbol table stops with the first module symbol
.\"(which should be right after the last kernel symbol).
.\"As with
.\".BR \-\-kelf ,
.\"the symbol table in each module's .ko file will also be consulted.
.\"See the
.\".B "MAKING DO WITH SYMBOL TABLES"
.\"section for more information.
.\" \-\-ignore\-{vmlinux,dwarf} shouldn't be visible
.TP
.B \-\-skip\-badvars
Ignore unresolvable or run-time-inaccessible context variables and
substitute with 0, without errors.
.TP
.B \-\-suppress\-handler\-errors
Wrap all probe handlers into something like this
.SAMPLE
try { ... } catch { next }
.ESAMPLE
block, which causes any runtime errors to be quietly suppressed.
Suppressed errors do not count against
.BR MAXERRORS
limits. In this mode, the
.BR MAXSKIPPED
limits are also suppressed, so that many errors and skipped probes
may be accumulated during a script's runtime. Any overall counts will
still be reported at shutdown.
.TP
.BI \-\-compatible " VERSION"
Suppress recent script language or tapset changes which are incompatible
with given older version of systemtap. This may be useful if a much older
systemtap script fails to run. See the DEPRECATION section for more
details.
.TP
.BI \-\-check\-version
This option is used to check if the active script has any constructors
that may be systemtap version specific. See the DEPRECATION section
for more details.
.TP
.BI \-\-clean\-cache
This option prunes stale entries from the cache directory. This is normally
done automatically after successful runs, but this option will trigger the
cleanup manually and then exit. See the CACHING section for more details about
cache limits.
.TP
.BI \-\-disable\-cache
This option disables all use of the cache directory. No files will be either
read from or written to the cache.
.TP
.BI \-\-poison\-cache
This option treats files in the cache directory as invalid. No files will be
read from the cache, but resulting files from this run will still be written to
the cache. This is meant as a troubleshooting aid when stap's cached behavior
seems to be misbehaving.
.TP
\fB\-\-privilege\fR[=\fIstapusr\fR | =\fIstapsys\fR | =\fIstapdev\fR]
This option instructs \fIstap\fR to examine the script looking for constructs
which are not allowed for the specified privilege level (see \fIUNPRIVILEGED USERS\fR).
Compilation fails if any such
constructs are used.
If \fIstapusr\fR or \fIstapsys\fR are specified when using a compile server
(see \fI\-\-use\-server\fR),
the server will examine the script and, if compilation succeeds, the
server will cryptographically sign the resulting kernel module, certifying
that is it safe for use by users at the specified privilege level.
If \fI\-\-privilege\fR has not been specified,
\fI\-pN\fR has not been specified with N < 5,
and the invoking user is not
\fIroot\fR, and is not a member of the group \fIstapdev\fR,
then \fIstap\fR will automatically
add the appropriate \fI\-\-privilege\fR option to the options already specified.
.TP
.BI \-\-unprivileged
This option is equivalent to \fI\-\-privilege=stapusr\fR.
.TP
\fB\-\-use\-server\fR[=\fIHOSTNAME\fR[\fI:PORT\fR] | =\fIIP_ADDRESS\fR[\fI:PORT\fR] | =\fICERT_SERIAL\fR]
Specify compile\-server(s) to be used for compilation and/or in conjunction
with
.I \-\-list\-servers
and
.I \-\-trust\-servers
(see below). If no argument is
supplied, then the default in unprivileged mode (see
.IR \-\-privilege )
is to select compatible servers which are trusted as SSL peers and as
module signers and currently online. Otherwise the default is to select
compatible servers which are trusted as SSL peers
and currently online.
.I \-\-use\-server
may be
specified more than once, in which case a list of servers is accumulated
in the order specified. Servers may be specified by host name, ip address, or
by certificate serial number (obtained using
.IR \-\-list\-servers ).
The latter is most commonly used when adding or revoking
trust in a server (see
.I \-\-trust\-servers
below). If a server is specified by host name or ip address, then an optional
port number may be specified. This is useful for accessing servers which are
not on the local network or to specify a particular server.
IP addresses may be IPv4 or IPv6 addresses.
If a particular IPv6 address is link local and exists
on more than one interface, the intended interface may be specified by appending the address with
a percent sign (%) followed by the intended interface name. For example,
"fe80::5eff:35ff:fe07:55ca%eth0".
In order to specify a port number with an IPv6 address, it is necessary to enclose the IPv6 address
in square brackets ([]) in order to separate the port number from the rest of the address. For
example, "[fe80::5eff:35ff:fe07:55ca]:5000" or "[fe80::5eff:35ff:fe07:55ca%eth0]:5000".
If \fI\-\-use\-server\fR has not been specified,
\fI\-pN\fR has not been specified with N < 5,
and the invoking user not \fIroot\fR,
is not a member of the group \fIstapdev\fR, but is a member of the group
\fIstapusr\fR, then \fIstap\fR will automatically
add \fI\-\-use\-server\fR to the options already specified.
.TP
\fB\-\-use\-server\-on\-error\fR[=\fByes\fR|=\fBno\fR]
Instructs stap to retry compilation of a script using a compile server if
compilation on the local host fails in a manner which suggests that it might
succeed using a server.
If this option is not specified, the default is \fIno\fR.
If no argument is provided, then the default
is \fIyes\fR. Compilation will be retried for certain types of errors
(e.g. insufficient data or resources) which may not occur during
re\-compilation by a compile
server. Compile servers will be selected automatically for the
re\-compilation attempt as if \fI\-\-use\-server\fR was specified with no
arguments.
.TP
.BI \-\-list\-servers "[=SERVERS]"
Display the status of the requested
.IR SERVERS ,
where
.I SERVERS
is a comma\-separated
list of server attributes. The list of attributes is combined to filter the
list of servers displayed. Supported attributes are:
.RS
.TP
.BI all
specifies all known servers (trusted SSL peers, trusted module signers, online
servers).
.TP
.BI specified
specifies servers specified using
.IR \-\-use\-server .
.TP
.BI online
filters the output by retaining information about servers which are currently
online.
.TP
.BI trusted
filters the output by retaining information about servers which are trusted as
SSL peers.
.TP
.BI signer
filters the output by retaining information about servers which are trusted as
module signers (see
.IR \-\-privilege ).
.TP
.BI compatible
filters the output by retaining information about servers which are compatible
with the current kernel release and architecture.
.RE
.IP
If no argument is provided, then the default is
.BR specified .
If no servers were specified using
.IR \-\-use\-server ,
then the default servers for
.IR \-\-use\-server
are listed.
Note that
.IR \-\-list\-servers
uses the
.IR avahi\-daemon
service to detect online servers. If this service is not avaiable, then
.IR \-\-list\-servers
will fail to detect any
.IR online
servers. In order for
.IR \-\-list\-servers
to detect servers listening on IPv6 addresses, the
.IR avahi\-daemon
configuration file
.IR /etc/avahi/avahi-daemon.conf
must contain an active "use-ipv6=yes" line. The service must be restarted after adding this line
in order for IPv6 to be enabled.
.TP
.BI \-\-trust\-servers "[=TRUST_SPEC]"
Grant or revoke trust in compile\-servers, specified using
.IR \-\-use\-server
as specified by TRUST_SPEC,
where TRUST_SPEC is a comma\-separated list specifying the trust which is to
be granted or revoked. Supported elements are:
.RS
.TP
.BI ssl
trust the specified servers as SSL peers.
.TP
.BI signer
trust the specified servers as module signers (see
.IR \-\-privilege ).
Only root can specify
.BR signer.
.TP
.BI all\-users
grant trust as an ssl peer for all users on the local host. The default is
to grant trust as an ssl peer for the current user only. Trust as a module
signer is always granted for all users. Only root can specify
.BR all\-users .
.TP
.BI revoke
revoke the specified trust. The default is to grant it.
.TP
.BI no\-prompt
do not prompt the user for confirmation before carrying out the requested
action. The default is to prompt the user for confirmation.
.RE
.IP
If no argument is provided, then the default is
.BR ssl .
If no servers were specified using
.IR \-\-use\-server ,
then no trust will be granted or revoked.
.IP
Unless \fBno\-prompt\fR has been specified,
the user will be prompted to confirm the trust to be granted or revoked before
the operation is performed.
.TP
.BI \-\-dump-probe-types
Dumps a list of supported probe types. If
.IR \-\-privilege=stapusr
is also specified, the list will be limited to probe types available to unprivileged users.
.TP
.BI \-\-remote " URL"
Set the execution target to the given host. This option may be
repeated to target multiple execution targets. Passes 1-4 are
completed locally as normal to build the script, and then pass 5 will
copy the module to the target and run it. Acceptable URL forms include:
.B [USER@]HOSTNAME
and
.B ssh://[USER@]HOSTNAME/
This mode uses ssh, optionally using a username not matching your own.
If a custom ssh_config file is in use, add
.B SendEnv LANG
to retain internationalization functionality.
The
.B direct://
URL is available as a special loopback mode to run on the local host.
.TP
.BI \-\-remote\-prefix
Prefix each line of remote output with "N:", where N is the index of the remote
execution target from which the given line originated.
.TP
.BI \-\-download\-debuginfo "[=OPTION]"
Enable, disable or set a timeout for the automatic debuginfo downloading feature
offered by abrt as specified by OPTION, where OPTION is one of the following:
.RS
.TP
.BI yes
enable automatic downloading of debuginfo with no timeout. This is the same
as not providing an OPTION value to
.IR \-\-download\-debuginfo
.TP
.BI no
explicitly disable automatic dowloading of debuginfo. This is the same as
not using the option at all.
.TP
.BI ask
show abrt output, and ask before continuing download. No timeout will be set.
.TP
.BI <timeout>
specify a timeout as a positive number to stop the download if it is taking
too long.
.RE
.IP
.TP
.BI \-\-rlimit-as "=NUM"
Specify the maximum size of the process's virtual memory (address space),
in bytes. If nothing is specified, no limits are imposed.
.TP
.BI \-\-rlimit-cpu "=NUM"
Specify the CPU time limit, in seconds. If nothing is specified, no limits are
imposed.
.TP
.BI \-\-rlimit-nproc "=NUM"
Specify the maximum number of processes that can be created. If nothing is
specified, no limits are imposed.
.TP
.BI \-\-rlimit-stack "=NUM"
Specify the maximum size of the process stack, in bytes. If nothing is specified,
no limits are imposed.
.TP
.BI \-\-rlimit-fsize "=NUM"
Specify the maximum size of files that the process may create, in bytes. If nothing is specified, no limits are
imposed.
.TP
.BI \-\-sysroot "=DIR"
Specify sysroot directory where target files (executables, libraries, etc.)
are located. With \fI\-r RELEASE\fR, the sysroot will be searched for the
appropriate kernel build directory. With \fI\-r /DIR\fR, however, the sysroot
will not be used to find the kernel build.
.TP
.BI \-\-sysenv "=VAR=VALUE"
Provide an alternate value for an environment variable where the value on a
remote system differs. Path variables (e.g. PATH, LD_LIBRARY_PATH) are assumed
to be relative to the directory provided by \fI\-\-sysroot\fR, if provided.
.SH ARGUMENTS
Any additional arguments on the command line are passed to the script
parser for substitution. See below.
.SH SCRIPT LANGUAGE
The systemtap script language resembles
.IR awk .
There are two main outermost constructs: probes and functions. Within
these, statements and expressions use C-like operator syntax and
precedence.
.SS GENERAL SYNTAX
Whitespace is ignored. Three forms of comments are supported:
.RS
.br
.BR # " ... shell style, to the end of line, except for $# and @#"
.br
.BR // " ... C++ style, to the end of line"
.br
.BR /* " ... C style ... " */
.RE
Literals are either strings enclosed in double-quotes (passing through
the usual C escape codes with backslashes), or integers (in decimal,
hexadecimal, or octal, using the same notation as in C). All strings
are limited in length to some reasonable value (a few hundred bytes).
Integers are 64-bit signed quantities, although the parser also accepts
(and wraps around) values above positive 2**63.
.PP
In addition, script arguments given at the end of the command line may
be inserted. Use
.B $1 ... $<NN>
for insertion unquoted,
.B @1 ... @<NN>
for insertion as a string literal. The number of arguments may be accessed
through
.B $#
(as an unquoted number) or through
.B @#
(as a quoted number). These may be used at any place a token may begin,
including within the preprocessing stage. Reference to an argument
number beyond what was actually given is an error.
.SS PREPROCESSING
A simple conditional preprocessing stage is run as a part of parsing.
The general form is similar to the
.RB cond " ? " exp1 " : " exp2
ternary operator:
.SAMPLE
.BR %( " CONDITION " %? " TRUE-TOKENS " %)
.BR %( " CONDITION " %? " TRUE-TOKENS " %: " FALSE-TOKENS " %)
.ESAMPLE
The CONDITION is either an expression whose format is determined by its
first keyword, or a string literals comparison or a numeric literals
comparison. It can be also composed of many alternatives and conjunctions
of CONDITIONs (meant as in previous sentence) using || and && respectively.
However, parentheses are not supported yet, so remembering that conjunction
takes precedence over alternative is important.
.PP
If the first part is the identifier
.BR kernel_vr " or " kernel_v
to refer to the kernel version number, with ("2.6.13\-1.322FC3smp") or
without ("2.6.13") the release code suffix, then
the second part is one of the six standard numeric comparison operators
.BR < ", " <= ", " == ", " != ", " > ", and " >= ,
and the third part is a string literal that contains an RPM-style
version-release value. The condition is deemed satisfied if the
version of the target kernel (as optionally overridden by the
.BR \-r
option) compares to the given version string. The comparison is
performed by the glibc function
.BR strverscmp .
As a special case, if the operator is for simple equality
.RB ( == ),
or inequality
.RB ( != ),
and the third part contains any wildcard characters
.RB ( * " or " ? " or " [ "),"
then the expression is treated as a wildcard (mis)match as evaluated
by
.BR fnmatch .
.PP
If, on the other hand, the first part is the identifier
.BR arch
to refer to the processor architecture (as named by the kernel
build system ARCH/SUBARCH), then the second
part is one of the two string comparison operators
.BR == " or " != ,
and the third part is a string literal for matching it. This
comparison is a wildcard (mis)match.
.PP
Similarly, if the first part is an identifier like
.BR CONFIG_something
to refer to a kernel configuration option, then the second part is
.BR == " or " != ,
and the third part is a string literal for matching the value
(commonly "y" or "m"). Nonexistent or unset kernel configuration
options are represented by the empty string. This comparison is also
a wildcard (mis)match.
.PP
If the first part is the identifier
.BR systemtap_v ,
the test refers to the systemtap compatibility version, which may be
overridden for old scripts with the
.BI \-\-compatible
flag. The comparison operator is as is for
.BR kernel_v
and the right operand is a version string. See also the DEPRECATION
section below.
.PP
Otherwise, the CONDITION is expected to be a comparison between two string
literals or two numeric literals. In this case, the arguments are the only
variables usable.
.PP
The TRUE-TOKENS and FALSE-TOKENS are zero or more general parser
tokens (possibly including nested preprocessor conditionals), and are
passed into the input stream if the condition is true or false. For
example, the following code induces a parse error unless the target
kernel version is newer than 2.6.5:
.SAMPLE
%( kernel_v <= "2.6.5" %? **ERROR** %) # invalid token sequence
.ESAMPLE
The following code might adapt to hypothetical kernel version drift:
.SAMPLE
probe kernel.function (
%( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
%( kernel_vr == "2.6.13*smp" %? "do_page_fault" %:
UNSUPPORTED %) %)
) { /* ... */ }
%( arch == "ia64" %?
probe syscall.vliw = kernel.function("vliw_widget") {}
%)
.ESAMPLE
.SS VARIABLES
Identifiers for variables and functions are an alphanumeric sequence,
and may include "_" and "$" characters. They may not start with a
plain digit, as in C. Each variable is by default local to the probe
or function statement block within which it is mentioned, and therefore
its scope and lifetime is limited to a particular probe or function
invocation.
.\" XXX add statistics type here once it's supported
.PP
Scalar variables are implicitly typed as either string or integer.
Associative arrays also have a string or integer value, and a
tuple of strings and/or integers serving as a key. Here are a
few basic expressions.
.SAMPLE
var1 = 5
var2 = "bar"
array1 [pid()] = "name" # single numeric key
array2 ["foo",4,i++] += 5 # vector of string/num/num keys
if (["hello",5,4] in array2) println ("yes") # membership test
.ESAMPLE
.PP
The translator performs
.I type inference
on all identifiers, including array indexes and function parameters.
Inconsistent type-related use of identifiers signals an error.
.PP
Variables may be declared global, so that they are shared amongst all
probes and live as long as the entire systemtap session. There is one
namespace for all global variables, regardless of which script file
they are found within. Concurrent access to global variables is
automatically protected with locks, see the
.B SAFETY AND SECURITY
section for more details. A global declaration may be written at the
outermost level anywhere, not within a block of code. Global
variables which are written but never read will be displayed
automatically at session shutdown. The translator will
infer for each its value type, and if it is used as an array, its key
types. Optionally, scalar globals may be initialized with a string
or number literal. The following declaration marks variables as global.
.RS
.BR global " var1" , " var2" , " var3=4"
.RE
.PP
Global variables can also be set as module options. One can do this by either
using the \-G option, or the module must first be compiled using stap \-p4.
Global variables can then be set on the command line when calling staprun on
the module generated by stap \-p4. See
.IR staprun (8)
for more information.
.RS
.RE
.PP
Arrays are limited in size by the MAXMAPENTRIES variable -- see the
.B SAFETY AND SECURITY
section for details. Optionally, global arrays may be declared with a
maximum size in brackets, overriding MAXMAPENTRIES for that array only.
Note that this doesn't indicate the type of keys for the array, just the
size.
.RS
.BR global " tiny_array[10]" , " normal_array" , " big_array[50000]"
.RE
.PP
Arrays may be wrapped using the '%' character causing previously entered
elements to be overwritten if more elements are inserted than the array can
hold. This works for both associative and statistics typed arrays.
.RS
.BR global " wrapped_array1%[10]", " wrapped_array2%"
.RE
.\" XXX add statistics type here once it's supported
.SS STATEMENTS
Statements enable procedural control flow. They may occur within
functions and probe handlers. The total number of statements executed
in response to any single probe event is limited to some number
defined by a macro in the translated C code, and is in the
neighbourhood of 1000.
.TP
EXP
Execute the string- or integer-valued expression and throw away
the value.
.TP
.BR { " STMT1 STMT2 ... " }
Execute each statement in sequence in this block. Note that
separators or terminators are generally not necessary between statements.
.TP
.BR ;
Null statement, do nothing. It is useful as an optional separator between
statements to improve syntax-error detection and to handle certain
grammar ambiguities.
.TP
.BR if " (EXP) STMT1 [ " else " STMT2 ]"
Compare integer-valued EXP to zero. Execute the first (non-zero)
or second STMT (zero).
.TP
.BR while " (EXP) STMT"
While integer-valued EXP evaluates to non-zero, execute STMT.
.TP
.BR for " (EXP1; EXP2; EXP3) STMT"
Execute EXP1 as initialization. While EXP2 is non-zero, execute
STMT, then the iteration expression EXP3.
.TP
.BR foreach " (VAR " in " ARRAY [ "limit " EXP ]) STMT"
Loop over each element of the named global array, assigning current
key to VAR. The array may not be modified within the statement.
By adding a single
.BR + " or " \-
operator after the VAR or the ARRAY identifier, the iteration will
proceed in a sorted order, by ascending or descending index or value.
Using the optional
.BR limit
keyword limits the number of loop iterations to EXP times. EXP is
evaluated once at the beginning of the loop.
.TP
.BR foreach " ([VAR1, VAR2, ...] " in " ARRAY [ "limit " EXP ]) STMT"
Same as above, used when the array is indexed with a tuple of keys.
A sorting suffix may be used on at most one VAR or ARRAY identifier.
.TP
.BR foreach " (VALUE = VAR " in " ARRAY [ "limit " EXP ]) STMT"
This variant of foreach saves current value into VALUE on each
iteration, so it is the same as ARRAY[VAR]. This also works with a
tuple of keys. Sorting suffixes on VALUE have the same effect as on ARRAY.
.TP
.BR break ", " continue
Exit or iterate the innermost nesting loop
.RB ( while " or " for " or " foreach )
statement.
.TP
.BR return " EXP"
Return EXP value from enclosing function. If the function's value is
not taken anywhere, then a return statement is not needed, and the
function will have a special "unknown" type with no return value.
.TP
.BR next
Return now from enclosing probe handler. This is especially useful in
probe aliases that apply event filtering predicates.
.TP
.BR try " { STMT1 } " catch " { STMT2 }"
Run the statements in the first block. Upon any run-time errors, abort
STMT1 and start executing STMT2. Any errors in STMT2 will propagate to
outer try/catch blocks, if any.
.TP
.BR try " { STMT1 } " catch "(VAR) { STMT2 }"
Same as above, plus assign the error message to the string scalar variable VAR.
.TP
.BR delete " ARRAY[INDEX1, INDEX2, ...]"
Remove from ARRAY the element specified by the index tuple. The value will no
longer be available, and subsequent iterations will not report the element.
It is not an error to delete an element that does not exist.
.TP
.BR delete " ARRAY"
Remove all elements from ARRAY.
.TP
.BR delete " SCALAR"
Removes the value of SCALAR. Integers and strings are cleared to 0 and ""
respectively, while statistics are reset to the initial empty state.
.SS EXPRESSIONS
Systemtap supports a number of operators that have the same general syntax,
semantics, and precedence as in C and awk. Arithmetic is performed as per
typical C rules for signed integers. Division by zero or overflow is
detected and results in an error.
.TP
binary numeric operators
.B * / % + \- >> << & ^ | && ||
.TP
binary string operators
.B .
(string concatenation)
.TP
numeric assignment operators
.B = *= /= %= += \-= >>= <<= &= ^= |=
.TP
string assignment operators
.B = .=
.TP
unary numeric operators
.B + \- ! ~ ++ \-\-
.TP
binary numeric or string comparison operators
.B < > <= >= == !=
.TP
ternary operator
.RB cond " ? " exp1 " : " exp2
.TP
grouping operator
.BR ( " exp " )
.TP
function call
.RB "fn " ( "[ arg1, arg2, ... ]" )
.TP
array membership check
.RB exp " in " array
.br
.BR "[" exp1 ", " exp2 ", " ... "] in " array
.SS PROBES
The main construct in the scripting language identifies probes.
Probes associate abstract events with a statement block ("probe
handler") that is to be executed when any of those events occur. The
general syntax is as follows:
.SAMPLE
.BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " }
.ESAMPLE
.PP
Events are specified in a special syntax called "probe points". There
are several varieties of probe points defined by the translator, and
tapset scripts may define further ones using aliases. These are
listed in the
.IR stapprobes (3stap)
manual pages.
.PP
The probe handler is interpreted relative to the context of each
event. For events associated with kernel code, this context may
include
.I variables
defined in the
.I source code
at that spot. These "target variables" are presented to the script as
variables whose names are prefixed with "$". They may be accessed
only if the kernel's compiler preserved them despite optimization.
This is the same constraint that a debugger user faces when working
with optimized code. Some other events have very little context.
See the
.IR stapprobes (3stap)
man pages to see the kinds of context variables available at each kind
of probe point.
.PP
New probe points may be defined using "aliases". Probe point aliases
look similar to probe definitions, but instead of activating a probe
at the given point, it just defines a new probe point name as an alias
to an existing one. There are two types of alias, i.e. the prologue
style and the epilogue style which are identified by "=" and "+="
respectively.
.PP
For prologue style alias, the statement block that follows an alias
definition is implicitly added as a prologue to any probe that refers
to the alias. While for the epilogue style alias, the statement block
that follows an alias definition is implicitly added as an epilogue to
any probe that refers to the alias. For example:
.SAMPLE
probe syscall.read = kernel.function("sys_read") {
fildes = $fd
if (execname() == "init") next # skip rest of probe
}
.ESAMPLE
defines a new probe point
.nh
.IR syscall.read ,
.hy
which expands to
.nh
.IR kernel.function("sys_read") ,
.hy
with the given statement as a prologue, which is useful to predefine
some variables for the alias user and/or to skip probe processing
entirely based on some conditions. And
.SAMPLE
probe syscall.read += kernel.function("sys_read") {