1STAP(1)                     General Commands Manual                    STAP(1)
2
3
4

NAME

6       stap - systemtap script translator/driver
7
8
9

SYNOPSIS

11       stap [ OPTIONS ] FILENAME [ ARGUMENTS ]
12       stap [ OPTIONS ] - [ ARGUMENTS ]
13       stap [ OPTIONS ] -e SCRIPT [ ARGUMENTS ]
14       stap [ OPTIONS ] -l PROBE [ ARGUMENTS ]
15       stap [ OPTIONS ] -L PROBE [ ARGUMENTS ]
16       stap [ OPTIONS ] --dump-probe-types
17       stap [ OPTIONS ] --dump-probe-aliases
18       stap [ OPTIONS ] --dump-functions
19
20

DESCRIPTION

22       The  stap  program  is the front-end to the Systemtap tool.  It accepts
23       probing instructions written  in  a  simple  domain-specific  language,
24       translates  those  instructions  into C code, compiles this C code, and
25       loads the resulting module into a running Linux  kernel  or  a  DynInst
26       user-space  mutator,  to perform the requested system trace/probe func‐
27       tions.  You can supply the script in  a  named  file  (FILENAME),  from
28       standard  input  (use  - instead of FILENAME), or from the command line
29       (using -e SCRIPT).  The program runs until it  is  interrupted  by  the
30       user,  or  if the script voluntarily invokes the exit() function, or by
31       sufficient number of soft errors.
32
33       The language, which is described the SCRIPT LANGUAGE section below,  is
34       strictly  typed, expressive, declaration free, procedural, prototyping-
35       friendly, and inspired by awk and C.  It allows source code  points  or
36       events  in the system to be associated with handlers, which are subrou‐
37       tines that are executed synchronously.  It is somewhat similar  concep‐
38       tually to "breakpoint command lists" in the gdb debugger.
39
40

OPTIONS

42       The  systemtap  translator  supports  the following options.  Any other
43       option prints a list of supported options.  Options may be given on the
44       command  line,  as usual.  If the file $SYSTEMTAP_DIR/rc exist, options
45       are also loaded from  there  and  interpreted  first.   ($SYSTEMTAP_DIR
46       defaults to $HOME/.systemtap if unset.)
47
48       -      Use standard input instead of a given FILENAME as probe language
49              input, unless -e SCRIPT is given.
50
51       -h --help
52              Show help message.
53
54       -V --version
55              Show version message.
56
57       -p NUM Stop after pass NUM.  The passes are numbered 1-5: parse, elabo‐
58              rate,  translate,  compile, run.  See the PROCESSING section for
59              details.
60
61       -v     Increase verbosity for all passes.  Produce a larger  volume  of
62              informative (?) output each time option repeated.
63
64       --vp ABCDE
65              Increase verbosity on a per-pass basis.  For example, "--vp 002"
66              adds 2 units of verbosity  to  pass  3  only.   The  combination
67              "-v --vp 00004"  adds  1 unit of verbosity for all passes, and 4
68              more for pass 5.
69
70       -k     Keep the temporary directory after all processing.  This may  be
71              useful in order to examine the generated C code, or to reuse the
72              compiled kernel object.
73
74       -g     Guru mode.  Enable parsing  of  unsafe  expert-level  constructs
75              like embedded C.
76
77       -P     Prologue-searching   mode.    This   is   equivalent  to  --pro‐
78              logue-searching=always.   Activate  heuristics  to  work  around
79              incorrect  debugging information for function parameter $context
80              variables.
81
82       -u     Unoptimized mode.  Disable unused code elision  and  many  other
83              optimizations during elaboration / translation.
84
85       -w     Suppressed warnings mode.  Disables all warning messages.
86
87       -W     Treat all warnings as errors.
88
89       -b     Use  bulk  mode (percpu files) for kernel-to-user data transfer.
90              Use the stap-merge  program  to  multiplex  them  back  together
91              later.
92
93       -t     Collect timing information on the number of times probe executes
94              and average amount of time spent in each probe-point. Also shows
95              the derivation for each probe-point.
96
97       -sNUM  Use NUM megabyte buffers for kernel-to-user data transfer.  On a
98              multiprocessor in bulk mode, this is a per-processor amount.
99
100       -I DIR Add the given directory to the tapset search directory.  See the
101              description of pass 2 for details.
102
103       -D NAME=VALUE
104              Add  the  given C preprocessor directive to the module Makefile.
105              These can be used to override limit parameters described below.
106
107       -B NAME=VALUE
108              Add the given make directive to the kernel module  build's  make
109              invocation.   These  can  be  used  to  add  or override kconfig
110              options.
111
112       -a ARCH
113              Use a cross-compilation mode for the given target  architecture.
114              This  requires access to the cross-compiler and the kernel build
115              tree, and goes along with the -B CROSS_COMPILE=arch-tool-prefix-
116              and -r /build/tree options.
117
118       --modinfo NAME=VALUE
119              Add  the name/value pair as a MODULE_INFO macro call to the gen‐
120              erated module.  This may be useful to inform or override various
121              module-related checks in the kernel.
122
123       -G NAME=VALUE
124              Sets  the value of global variable NAME to VALUE when staprun is
125              invoked.  This applies to scalar variables  declared  global  in
126              the script/tapset.
127
128       -R DIR Look for the systemtap runtime sources in the given directory.
129
130       -r /DIR
131              Build  for  kernel in given build tree. Can also be set with the
132              SYSTEMTAP_RELEASE environment variable.
133
134       -r RELEASE
135              Build for kernel in build tree /lib/modules/RELEASE/build.   Can
136              also be set with the SYSTEMTAP_RELEASE environment variable.
137
138       -m MODULE
139              Use  the  given  name  for  the  generated kernel object module,
140              instead of a  unique  randomized  name.   The  generated  kernel
141              object module is copied to the current directory.
142
143       -d MODULE
144              Add symbol/unwind information for the given module into the ker‐
145              nel object module.  This may  enable  symbolic  tracebacks  from
146              those  modules/programs,  even  if  they do not have an explicit
147              probe placed into them.
148
149       --ldd  Add symbol/unwind information for all shared libraries suspected
150              by  ldd  to  be necessary for user-space binaries being probe or
151              listed with the -d option.  Caution: this  can  make  the  probe
152              modules considerably larger.
153
154       --all-modules
155              Equivalent  to  specifying "-dkernel" and a "-d" for each kernel
156              module that is currently loaded.  Caution:  this  can  make  the
157              probe modules considerably larger.
158
159       -o FILE
160              Send  standard  output to named file. In bulk mode, percpu files
161              will start with FILE_ (FILE_cpu with -F)  followed  by  the  cpu
162              number.  This supports strftime(3) formats for FILE.
163
164       -c CMD Start  the  probes,  run  CMD, and exit when CMD finishes.  This
165              also has the effect of setting target() to the pid of  the  com‐
166              mand ran.
167
168       -x PID Sets  target()  to  PID.  This allows scripts to be written that
169              filter on a specific process. Scripts  run  independent  of  the
170              PID's lifespan.
171
172       -e SCRIPT
173              Run the given SCRIPT specified on the command line.
174
175       -E SCRIPT
176              Run  the  given SCRIPT specified. This SCRIPT is run in addition
177              to the main script specified, through -e, or as a  script  file.
178              This  option can be repeated to run multiple scripts, and can be
179              used in listing mode (-l/-L).
180
181       -l PROBE
182              Instead of running a probe script, just list all available probe
183              points  matching  the given single probe point.  The pattern may
184              include wildcards and aliases, but not comma-separated  multiple
185              probe  points.  The process result code will indicate failure if
186              there are no matches.
187
188       -L PROBE
189              Similar to "-l", but list probe points  and  script-level  local
190              variables.
191
192       -F     Without  -o  option,  load  module and start probes, then detach
193              from the module leaving the probes running.  With -o option, run
194              staprun in background as a daemon and show its pid.
195
196       -S size[,N]
197              Sets  the  maximum size of output file and the maximum number of
198              output files.  If the size of output file  will  exceed  size  ,
199              systemtap switches output file to the next file. And if the num‐
200              ber of output files exceed N , systemtap removes the oldest out‐
201              put file. You can omit the second argument.
202
203       --skip-badvars
204              Ignore  unresolvable  or run-time-inaccessible context variables
205              and substitute with 0, without errors.
206
207
208       --prologue-searching[=WHEN]
209              Prologue-searching mode.  Activate  heuristics  to  work  around
210              incorrect  debugging information  for  function  parameter $con‐
211              text variables. WHEN can be either "never", "always", or  "auto"
212              (i.e.  enabled  by heuristic). If WHEN is missing, then "always"
213              is assumed. If the option is missing, then "auto" is assumed.
214
215
216       --suppress-handler-errors
217              Wrap all probe handlers into something like this
218
219              try { ... } catch { next }
220
221              block, which causes any runtime errors to be quietly suppressed.
222              Suppressed  errors  do  not  count against MAXERRORS limits.  In
223              this mode, the MAXSKIPPED limits are also  suppressed,  so  that
224              many  errors  and  skipped  probes  may  be accumulated during a
225              script's runtime.  Any overall counts will still be reported  at
226              shutdown.
227
228
229       --compatible VERSION
230              Suppress  recent script language or tapset changes which are in‐
231              compatible with given older version of systemtap.  This  may  be
232              useful  if  a much older systemtap script fails to run.  See the
233              DEPRECATION section for more details.
234
235
236       --check-version
237              This option is used to check if the active script has  any  con‐
238              structs  that may be systemtap version specific.  See the DEPRE‐
239              CATION section for more details.
240
241
242       --clean-cache
243              This option prunes stale entries from the cache directory.  This
244              is  normally  done automatically after successful runs, but this
245              option will trigger the cleanup manually and then exit.  See the
246              CACHING section for more details about cache limits.
247
248
249       --color[=WHEN], --colour[=WHEN]
250              This option controls coloring of error messages. WHEN can be ei‐
251              ther "never", "always", or "auto" (i.e. enable only if at a ter‐
252              minal). If WHEN is missing, then "always" is assumed. If the op‐
253              tion is missing, then "auto" is assumed.
254
255              Colors can be modified using  the  SYSTEMTAP_COLORS  environment
256              variable.     The     format     must    be    of    the    form
257              key1=val1:key2=val2:key3=val3 ...etc.  Valid keys  are  "error",
258              "warning",  "source",  "caret",  and "token".  Values constitute
259              Select Graphic Rendition (SGR) parameter(s). Consult  the  docu‐
260              mentation of your terminal for the SGRs it supports. As an exam‐
261              ple,   the   default    colors    would    be    expressed    as
262              error=01;31:warning=00;33:source=00;34:caret=01:token=01.     If
263              SYSTEMTAP_COLORS is absent, the default colors will be used.  If
264              it is empty or invalid, coloring is turned off.
265
266
267       --disable-cache
268              This  option  disables all use of the cache directory.  No files
269              will be either read from or written to the cache.
270
271
272       --poison-cache
273              This option treats files in the cache directory as invalid.   No
274              files will be read from the cache, but resulting files from this
275              run will still be written to the cache.   This  is  meant  as  a
276              troubleshooting aid when stap's cached behavior seems to be mis‐
277              behaving.
278
279
280       --privilege[=stapusr | =stapsys | =stapdev]
281              This option instructs stap to examine  the  script  looking  for
282              constructs  which  are  not  allowed for the specified privilege
283              level (see UNPRIVILEGED USERS).  Compilation fails if  any  such
284              constructs  are  used.  If stapusr or stapsys are specified when
285              using a compile server (see --use-server), the server will exam‐
286              ine  the  script  and,  if compilation succeeds, the server will
287              cryptographically sign the resulting kernel  module,  certifying
288              that is it safe for use by users at the specified privilege lev‐
289              el.
290
291              If --privilege has not been specified, -pN has not  been  speci‐
292              fied with N < 5, and the invoking user is not root, and is not a
293              member of the group stapdev, then stap  will  automatically  add
294              the appropriate --privilege option to the options already speci‐
295              fied.
296
297
298       --unprivileged
299              This option is equivalent to --privilege=stapusr.
300
301
302       --use-server[=HOSTNAME[:PORT] | =IP_ADDRESS[:PORT] | =CERT_SERIAL]
303              Specify compile-server(s) to be used for compilation  and/or  in
304              conjunction with --list-servers and --trust-servers (see below).
305              If no argument is supplied, then  the  default  in  unprivileged
306              mode (see --privilege) is to select compatible servers which are
307              trusted as SSL peers and as module signers and currently online.
308              Otherwise  the default is to select compatible servers which are
309              trusted as SSL peers and currently online.  --use-server may  be
310              specified more than once, in which case a list of servers is ac‐
311              cumulated in the order specified. Servers may  be  specified  by
312              host name, ip address, or by certificate serial number (obtained
313              using --list-servers).  The latter is most  commonly  used  when
314              adding  or  revoking  trust in a server (see --trust-servers be‐
315              low). If a server is specified by host name or ip address,  then
316              an optional port number may be specified. This is useful for ac‐
317              cessing servers which are not on the local network or to specify
318              a particular server.
319
320              IP addresses may be IPv4 or IPv6 addresses.
321
322              If  a  particular  IPv6 address is link local and exists on more
323              than one interface, the intended interface may be  specified  by
324              appending  the  address  with a percent sign (%) followed by the
325              intended       interface        name.        For        example,
326              "fe80::5eff:35ff:fe07:55ca%eth0".
327
328              In  order  to  specify a port number with an IPv6 address, it is
329              necessary to enclose the IPv6 address in square brackets ([]) in
330              order  to separate the port number from the rest of the address.
331              For     example,      "[fe80::5eff:35ff:fe07:55ca]:5000"      or
332              "[fe80::5eff:35ff:fe07:55ca%eth0]:5000".
333
334              If  --use-server has not been specified, -pN has not been speci‐
335              fied with N < 5, and the invoking user not root, is not a member
336              of the group stapdev, but is a member of the group stapusr, then
337              stap will automatically add --use-server to the options  already
338              specified.
339
340
341       --use-server-on-error[=yes|=no]
342              Instructs  stap to retry compilation of a script using a compile
343              server if compilation on the local host fails in a manner  which
344              suggests  that  it might succeed using a server.  If this option
345              is not specified, the default is no.  If no argument is  provid‐
346              ed,  then  the  default  is yes. Compilation will be retried for
347              certain types of errors (e.g. insufficient  data  or  resources)
348              which  may  not occur during re-compilation by a compile server.
349              Compile servers will be selected automatically for the re-compi‐
350              lation  attempt  as  if --use-server was specified with no argu‐
351              ments.
352
353
354       --list-servers[=SERVERS]
355              Display the status of the requested SERVERS, where SERVERS is  a
356              comma-separated  list  of  server  attributes.  The  list of at‐
357              tributes is combined to filter the list  of  servers  displayed.
358              Supported attributes are:
359
360              all    specifies  all  known servers (trusted SSL peers, trusted
361                     module signers, online servers).
362
363              specified
364                     specifies servers specified using --use-server.
365
366              online filters the output by retaining information about servers
367                     which are currently online.
368
369              trusted
370                     filters the output by retaining information about servers
371                     which are trusted as SSL peers.
372
373              signer filters the output by retaining information about servers
374                     which are trusted as module signers (see --privilege).
375
376              compatible
377                     filters the output by retaining information about servers
378                     which are compatible with the current kernel release  and
379                     architecture.
380
381              If  no  argument is provided, then the default is specified.  If
382              no servers were specified using --use-server, then  the  default
383              servers for --use-server are listed.
384
385              Note that --list-servers uses the avahi-daemon service to detect
386              online  servers.  If  this  service  is  not   available,   then
387              --list-servers  will fail to detect any online servers. In order
388              for --list-servers to detect servers listening on IPv6  address‐
389              es,  the  avahi-daemon  configuration file /etc/avahi/avahi-dae‐
390              mon.conf must contain an active "use-ipv6=yes" line. The service
391              must be restarted after adding this line in order for IPv6 to be
392              enabled.
393
394
395       --trust-servers[=TRUST_SPEC]
396              Grant  or  revoke  trust  in  compile-servers,  specified  using
397              --use-server  as  specified by TRUST_SPEC, where TRUST_SPEC is a
398              comma-separated list specifying the trust which is to be granted
399              or revoked. Supported elements are:
400
401              ssl    trust the specified servers as SSL peers.
402
403              signer trust  the  specified  servers  as  module  signers  (see
404                     --privilege).  Only root can specify signer.
405
406              all-users
407                     grant trust as an ssl peer for all  users  on  the  local
408                     host.  The  default  is to grant trust as an ssl peer for
409                     the current user only. Trust as a module signer is always
410                     granted for all users. Only root can specify all-users.
411
412              revoke revoke the specified trust. The default is to grant it.
413
414              no-prompt
415                     do  not  prompt the user for confirmation before carrying
416                     out the requested action. The default is  to  prompt  the
417                     user for confirmation.
418
419              If  no  argument  is  provided,  then the default is ssl.  If no
420              servers were specified using --use-server, then no trust will be
421              granted or revoked.
422
423              Unless  no-prompt  has been specified, the user will be prompted
424              to confirm the trust to be granted or revoked before the  opera‐
425              tion is performed.
426
427
428       --dump-probe-types
429              Dumps  a  list  of  supported probe types and exits. If --privi‐
430              lege=stapusr is also specified, the  list  will  be  limited  to
431              probe types available to unprivileged users.
432
433
434       --dump-probe-aliases
435              Dumps a list of all probe aliases found in library files and ex‐
436              its.
437
438
439       --dump-functions
440              Dumps a list of all functions found in library files and  exits.
441              Also  includes  their  parameters  and types. A function of type
442              'unknown' indicates a function that does  not  return  a  value.
443              Note  that  not  all  function/parameter  types  may be resolved
444              (these are also shown by 'unknown'). This features is very memo‐
445              ry-intensive and thus may not work properly with --use-server if
446              the target server imposes an  rlimit  on  process  memory  (i.e.
447              through  the  ~stap-server/.systemtap/rc configuration file, see
448              stap-server(8)).
449
450
451       --remote URL
452              Set the execution target to the given host.  This option may  be
453              repeated  to  target multiple execution targets.  Passes 1-4 are
454              completed locally as normal to build the script, and then pass 5
455              will  copy  the module to the target and run it.  Acceptable URL
456              forms include:
457
458              [USER@]HOSTNAME, ssh://[USER@]HOSTNAME
459                     This mode uses  ssh,  optionally  using  a  username  not
460                     matching your own. If a custom ssh_config file is in use,
461                     add SendEnv LANG to retain internationalization function‐
462                     ality.
463
464              libvirt://DOMAIN, libvirt://DOMAIN/LIBVIRT_URI
465                     This mode uses stapvirt to execute the script on a domain
466                     managed by libvirt. Optionally, LIBVIRT_URI may be speci‐
467                     fied  to  connect  to  a  specific driver and/or a remote
468                     host. For example, to connect to the local privileged QE‐
469                     MU driver, use:
470
471                     --remote libvirt://MyDomain/qemu:///system
472
473                     See  the  page  at <http://libvirt.org/uri.html> for sup‐
474                     ported URIs. Also see stapvirt(1) for more information on
475                     how to prepare the domain for stap probing.
476
477              unix:PATH
478                     This  mode  connects  to  a UNIX socket. This can be used
479                     with a QEMU virtio-serial port for executing scripts  in‐
480                     side a running virtual machine.
481
482              direct://
483                     Special loopback mode to run on the local host.
484
485       --remote-prefix
486              Prefix each line of remote output with "N: ", where N is the in‐
487              dex of the remote execution target from  which  the  given  line
488              originated.
489
490
491       --download-debuginfo[=OPTION]
492              Enable,  disable  or  set  a timeout for the automatic debuginfo
493              downloading feature offered by  abrt  as  specified  by  OPTION,
494              where OPTION is one of the following:
495
496              yes    enable  automatic  downloading of debuginfo with no time‐
497                     out. This is the same as not providing an OPTION value to
498                     --download-debuginfo
499
500              no     explicitly  disable  automatic  downloading of debuginfo.
501                     This is the same as not using the option at all.
502
503              ask    show abrt output, and ask before continuing download.  No
504                     timeout will be set.
505
506              <timeout>
507                     specify  a timeout as a positive number to stop the down‐
508                     load if it is taking too long.
509
510       --rlimit-as=NUM
511              Specify the maximum size of the process's  virtual  memory  (ad‐
512              dress  space),  in bytes. If nothing is specified, no limits are
513              imposed.
514
515
516       --rlimit-cpu=NUM
517              Specify the CPU time limit, in seconds. If nothing is specified,
518              no limits are imposed.
519
520
521       --rlimit-nproc=NUM
522              Specify  the maximum number of processes that can be created. If
523              nothing is specified, no limits are imposed.
524
525
526       --rlimit-stack=NUM
527              Specify the maximum size of the  process  stack,  in  bytes.  If
528              nothing is specified, no limits are imposed.
529
530
531       --rlimit-fsize=NUM
532              Specify  the  maximum size of files that the process may create,
533              in bytes. If nothing is specified, no limits are imposed.
534
535
536       --sysroot=DIR
537              Specify sysroot directory where target files  (executables,  li‐
538              braries,  etc.)  are located.  With -r RELEASE, the sysroot will
539              be searched for the appropriate kernel build directory.  With -r
540              /DIR,  however,  the sysroot will not be used to find the kernel
541              build.
542
543
544       --sysenv=VAR=VALUE
545              Provide an alternate value for an environment variable where the
546              value  on  a  remote system differs.  Path variables (e.g. PATH,
547              LD_LIBRARY_PATH) are assumed to be  relative  to  the  directory
548              provided by --sysroot, if provided.
549
550
551       --suppress-time-limits
552              Disable  -DSTP_OVERLOAD  related  options as well as -DMAXACTION
553              and -DMAXTRYLOCK.  This option requires guru mode.
554
555
556       --runtime=MODE
557              Set the pass-5 runtime mode.  Valid options are kernel (default)
558              and dyninst.  See ALTERNATE RUNTIMES below for more information.
559
560
561       --dyninst
562              Shorthand for --runtime=dyninst.
563
564
565       --save-uprobes
566              On machines that require SystemTap to build its own uprobes mod‐
567              ule (kernels prior to version 3.5), this option  instructs  Sys‐
568              temTap to also save a copy of the module in the current directo‐
569              ry (creating a new "uprobes" directory first).
570
571
572       --target-namespaces=PID
573              Allow for a set of target namespaces to  be  set  based  on  the
574              namespaces  the  given  PID  is  in. This is for namespace-aware
575              tapset functions. If the target namespaces was not set, the tar‐
576              get defaults to the stap process' namespaces.
577
578

ARGUMENTS

580       Any  additional  arguments on the command line are passed to the script
581       parser for substitution.  See below.
582
583

SCRIPT LANGUAGE

585       The systemtap script language resembles awk and C.  There are two  main
586       outermost  constructs:  probes and functions.  Within these, statements
587       and expressions use C-like operator syntax and precedence.
588
589
590   GENERAL SYNTAX
591       Whitespace is ignored.  Three forms of comments are supported:
592              # ... shell style, to the end of line, except for $# and @#
593              // ... C++ style, to the end of line
594              /* ... C style ... */
595       Literals are either strings enclosed in double-quotes (passing  through
596       the  usual  C  escape  codes with backslashes, and with adjacent string
597       literals glued together, also as in C), or integers (in decimal,  hexa‐
598       decimal,  or  octal, using the same notation as in C).  All strings are
599       limited in length to some reasonable value (a few hundred bytes).   In‐
600       tegers  are  64-bit signed quantities, although the parser also accepts
601       (and wraps around) values above positive 2**63.
602
603       In addition, script arguments given at the end of the command line  may
604       be inserted.  Use $1 ... $<NN> for insertion unquoted, @1 ... @<NN> for
605       insertion as a string literal.  The number of arguments may be accessed
606       through  $# (as an unquoted number) or through @# (as a quoted number).
607       These may be used at any place a token may begin, including within  the
608       preprocessing  stage.   Reference to an argument number beyond what was
609       actually given is an error.
610
611
612   PREPROCESSING
613       A simple conditional preprocessing stage is run as a part  of  parsing.
614       The general form is similar to the cond ? exp1 : exp2 ternary operator:
615
616              %( CONDITION %? TRUE-TOKENS %)
617              %( CONDITION %? TRUE-TOKENS %: FALSE-TOKENS %)
618
619       The CONDITION is either an expression whose format is determined by its
620       first keyword, or a string literals comparison or  a  numeric  literals
621       comparison.   It can be also composed of many alternatives and conjunc‐
622       tions of CONDITIONs (meant as in previous sentence) using || and && re‐
623       spectively.  However, parentheses are not supported yet, so remembering
624       that conjunction takes precedence over alternative is important.
625
626       If the first part is the identifier kernel_vr or kernel_v to  refer  to
627       the  kernel  version  number,  with  ("2.6.13-1.322FC3smp")  or without
628       ("2.6.13") the release code suffix, then the second part is one of  the
629       six standard numeric comparison operators <, <=, ==, !=, >, and >=, and
630       the third part is a string literal that contains an RPM-style  version-
631       release value.  The condition is deemed satisfied if the version of the
632       target kernel (as optionally overridden by the -r option)  compares  to
633       the  given  version  string.   The comparison is performed by the glibc
634       function strverscmp.  As a special case, if the operator is for  simple
635       equality  (==),  or  inequality  (!=),  and the third part contains any
636       wildcard characters (* or ? or [), then the expression is treated as  a
637       wildcard (mis)match as evaluated by fnmatch.
638
639       If,  on  the other hand, the first part is the identifier arch to refer
640       to the processor architecture (as named  by  the  kernel  build  system
641       ARCH/SUBARCH), then the second part is one of the two string comparison
642       operators == or !=, and the third part is a string literal for matching
643       it.  This comparison is a wildcard (mis)match.
644
645       Similarly,  if the first part is an identifier like CONFIG_something to
646       refer to a kernel configuration option, then the second part is  ==  or
647       !=, and the third part is a string literal for matching the value (com‐
648       monly "y" or "m").  Nonexistent or unset kernel  configuration  options
649       are  represented  by the empty string.  This comparison is also a wild‐
650       card (mis)match.
651
652       If the first part is the identifier systemtap_v, the test refers to the
653       systemtap  compatibility  version,  which  may  be  overridden  for old
654       scripts with the --compatible flag.  The comparison operator is  as  is
655       for  kernel_v  and the right operand is a version string.  See also the
656       DEPRECATION section below.
657
658       If the first part  is  the  identifier  systemtap_privilege,  the  test
659       refers  to  the  privilege  level that the systemtap script is compiled
660       with. Here the second part is == or !=, and the third part is a  string
661       literal, either "stapusr" or "stapsys" or "stapdev".
662
663       If  the  first  part is the identifier guru_mode, the test refers to if
664       the systemtap script is compiled with guru_mode. Here the  second  part
665       is == or !=, and the third part is a number, either 1 or 0.
666
667       If  the  first  part  is the identifier runtime, the test refers to the
668       systemtap runtime mode. See ALTERNATE RUNTIMES below for more  informa‐
669       tion  on runtimes.  The second part is one of the two string comparison
670       operators == or !=, and the third part is a string literal for matching
671       it.  This comparison is a wildcard (mis)match.
672
673       Otherwise,  the  CONDITION  is  expected to be a comparison between two
674       string literals or two numeric literals.  In this case,  the  arguments
675       are the only variables usable.
676
677       The TRUE-TOKENS and FALSE-TOKENS are zero or more general parser tokens
678       (possibly including nested preprocessor conditionals), and  are  passed
679       into  the input stream if the condition is true or false.  For example,
680       the following code induces a parse error unless the target kernel  ver‐
681       sion is newer than 2.6.5:
682
683              %( kernel_v <= "2.6.5" %? **ERROR** %) # invalid token sequence
684
685       The following code might adapt to hypothetical kernel version drift:
686
687              probe kernel.function (
688                %( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
689                   %( kernel_vr == "2.6.13*smp" %? "do_page_fault" %:
690                      UNSUPPORTED %) %)
691              ) { /* ... */ }
692
693              %( arch == "ia64" %?
694                 probe syscall.vliw = kernel.function("vliw_widget") {}
695              %)
696
697
698
699   PREPROCESSOR MACROS
700       The  preprocessor also supports a simple macro facility, run as a sepa‐
701       rate pass before conditional preprocessing.
702
703       Macros are defined using the following construct:
704
705              @define NAME %( BODY %)
706              @define NAME(PARAM_1, PARAM_2, ...) %( BODY %)
707
708       Macros, and parameters inside a macro body, are both invoked by prefix‐
709       ing the macro name with an @ symbol:
710
711              @define foo %( x %)
712              @define add(a,b) %( ((@a)+(@b)) %)
713
714                 @foo = @add(2,2)
715
716
717       Macro expansion is currently performed in a separate pass before condi‐
718       tional compilation. Therefore, both TRUE- and  FALSE-tokens  in  condi‐
719       tional  expressions  will be macroexpanded regardless of how the condi‐
720       tion is evaluated. This can sometimes lead to errors:
721
722              // The following results in a conflict:
723              %( CONFIG_UTRACE == "y" %?
724                  @define foo %( process.syscall %)
725              %:
726                  @define foo %( **ERROR** %)
727              %)
728
729              // The following works properly as expected:
730              @define foo %(
731                %( CONFIG_UTRACE == "y" %? process.syscall %: **ERROR** %)
732              %)
733
734       The first example is incorrect because both @defines are evaluated in a
735       pass prior to the conditional being evaluated.
736
737       Normally,  a  macro definition is local to the file it occurs in. Thus,
738       defining a macro in a tapset does not make it available to the user  of
739       the  tapset.  Publically available library macros can be defined by in‐
740       cluding .stpm files on the tapset search path.  These  files  may  only
741       contain @define constructs, which become visible across all tapsets and
742       user scripts.
743
744
745   VARIABLES
746       Identifiers for variables and functions are an  alphanumeric  sequence,
747       and  may  include  _ and $ characters.  They may not start with a plain
748       digit, as in C.  Each variable is by default  local  to  the  probe  or
749       function  statement  block  within which it is mentioned, and therefore
750       its scope and lifetime is limited to a particular probe or function in‐
751       vocation.
752
753       Scalar variables are implicitly typed as either string or integer.  As‐
754       sociative arrays also have a string or integer value, and  a  tuple  of
755       strings and/or integers serving as a key.  Here are a few basic expres‐
756       sions.
757
758              var1 = 5
759              var2 = "bar"
760              array1 [pid()] = "name"     # single numeric key
761              array2 ["foo",4,i++] += 5   # vector of string/num/num keys
762              if (["hello",5,4] in array2) println ("yes")  # membership test
763
764
765       The translator performs type inference on  all  identifiers,  including
766       array  indexes  and function parameters.  Inconsistent type-related use
767       of identifiers signals an error.
768
769       Variables may be declared global, so that they are shared  amongst  all
770       probes  and live as long as the entire systemtap session.  There is one
771       namespace for all global variables, regardless  of  which  script  file
772       they  are found within.  Concurrent access to global variables is auto‐
773       matically protected with locks, see the SAFETY AND SECURITY section for
774       more  details.   A  global  declaration may be written at the outermost
775       level anywhere, not within a block of code.  Global variables which are
776       written but never read will be displayed automatically at session shut‐
777       down.  The translator will infer for each its value type, and if it  is
778       used  as  an  array,  its key types.  Optionally, scalar globals may be
779       initialized with a string or number literal.  The following declaration
780       marks variables as global.
781
782              global var1, var2, var3=4
783
784
785       Global  variables can also be set as module options. One can do this by
786       either using the -G option, or the module must first be compiled  using
787       stap  -p4.   Global  variables can then be set on the command line when
788       calling staprun on the module generated by stap -p4. See staprun(8) for
789       more information.
790
791       Arrays  are  limited  in  size by the MAXMAPENTRIES variable -- see the
792       SAFETY AND SECURITY section for details.  Optionally, global arrays may
793       be  declared  with a maximum size in brackets, overriding MAXMAPENTRIES
794       for that array only.  Note that this doesn't indicate the type of  keys
795       for the array, just the size.
796
797              global tiny_array[10], normal_array, big_array[50000]
798
799
800       Arrays may be configured for wrapping using the '%' suffix.  This caus‐
801       es older elements to be overwritten if more elements are inserted  than
802       the  array  can  hold.  This  works for both associative and statistics
803       typed arrays.
804
805              global wrapped_array1%[10], wrapped_array2%
806
807
808
809       Many types of probe points provide context variables,  which  are  run-
810       time  values, safely extracted from the kernel or userspace program be‐
811       ing probed.  These are prefixed with  the  $  character.   The  CONTEXT
812       VARIABLES section in stapprobes(3stap) lists what is available for each
813       type of probe point.  These context variables become normal  string  or
814       numeric  scalars  once they are stored in normal script variables.  See
815       the TYPECASTING section below on how to to turn them  back  into  typed
816       pointers for further processing as context variables.
817
818
819   STATEMENTS
820       Statements enable procedural control flow.  They may occur within func‐
821       tions and probe handlers.  The total number of statements  executed  in
822       response to any single probe event is limited to some number defined by
823       a macro in the translated C code, and is in the neighbourhood of 1000.
824
825       EXP    Execute the string- or integer-valued expression and throw  away
826              the value.
827
828       { STMT1 STMT2 ... }
829              Execute  each  statement  in  sequence in this block.  Note that
830              separators or terminators are generally  not  necessary  between
831              statements.
832
833       ;      Null statement, do nothing.  It is useful as an optional separa‐
834              tor between statements to improve syntax-error detection and  to
835              handle certain grammar ambiguities.
836
837       if (EXP) STMT1 [ else STMT2 ]
838              Compare  integer-valued EXP to zero.  Execute the first (non-ze‐
839              ro) or second STMT (zero).
840
841       while (EXP) STMT
842              While integer-valued EXP evaluates to non-zero, execute STMT.
843
844       for (EXP1; EXP2; EXP3) STMT
845              Execute EXP1 as initialization.  While EXP2 is non-zero, execute
846              STMT, then the iteration expression EXP3.
847
848       foreach (VAR in ARRAY [ limit EXP ]) STMT
849              Loop over each element of the named global array, assigning cur‐
850              rent key to VAR.  The array  may  not  be  modified  within  the
851              statement.   By adding a single + or - operator after the VAR or
852              the ARRAY identifier, the iteration will proceed in a sorted or‐
853              der,  by  ascending  or descending index or value.  If the array
854              contains statistics aggregates, adding the desired @operator be‐
855              tween the ARRAY identifier and the + or - will specify the sort‐
856              ing aggregate function.  See the STATISTICS  section  below  for
857              the ones available.  Default is @count.  Using the optional lim‐
858              it keyword limits the number of loop iterations  to  EXP  times.
859              EXP is evaluated once at the beginning of the loop.
860
861       foreach ([VAR1, VAR2, ...] in ARRAY [ limit EXP ]) STMT
862              Same  as  above,  used when the array is indexed with a tuple of
863              keys.  A sorting suffix may be used on at most one VAR or  ARRAY
864              identifier.
865
866       foreach  ([VAR1,  VAR2, ...] in ARRAY [INDEX1, INDEX2, ...] [ limit EXP
867       ]) STMT
868              Same as above, where iterations are limited to elements  in  the
869              array  where the keys match the index values specified. The sym‐
870              bol * can be used to specify an index and will be treated  as  a
871              wildcard.
872
873       foreach (VALUE = VAR in ARRAY [ limit EXP ]) STMT
874              This  variant  of foreach saves current value into VALUE on each
875              iteration, so it is the same as  ARRAY[VAR].   This  also  works
876              with  a  tuple of keys.  Sorting suffixes on VALUE have the same
877              effect as on ARRAY.
878
879       foreach (VALUE = VAR in ARRAY [INDEX1, INDEX2, ...] [ limit EXP ]) STMT
880              Same as above, where iterations are limited to elements  in  the
881              array  where the keys match the index values specified. The sym‐
882              bol * can be used to specify an index and will be treated  as  a
883              wildcard.
884
885       break, continue
886              Exit  or  iterate  the  innermost  nesting loop (while or for or
887              foreach) statement.
888
889       return EXP
890              Return EXP value from enclosing  function.   If  the  function's
891              value  is  not  taken  anywhere,  then a return statement is not
892              needed, and the function will have a special "unknown" type with
893              no return value.
894
895       next   Return  now  from  enclosing  probe handler.  This is especially
896              useful in probe aliases that apply event filtering predicates.
897
898       try { STMT1 } catch { STMT2 }
899              Run the statements in the first block.  Upon  any  run-time  er‐
900              rors,  abort  STMT1  and  start  executing STMT2.  Any errors in
901              STMT2 will propagate to outer try/catch blocks, if any.
902
903       try { STMT1 } catch(VAR) { STMT2 }
904              Same as above, plus assign  the  error  message  to  the  string
905              scalar variable VAR.
906
907       delete ARRAY[INDEX1, INDEX2, ...]
908              Remove  from ARRAY the element specified by the index tuple.  If
909              the index tuple contains a * in place of  an  index,  the  *  is
910              treated  as a wildcard and all elements with keys that match the
911              index tuple will be removed  from  ARRAY.   The  value  will  no
912              longer  be  available, and subsequent iterations will not report
913              the element.  It is not an error to delete an element that  does
914              not exist.
915
916       delete ARRAY
917              Remove all elements from ARRAY.
918
919       delete SCALAR
920              Removes  the  value of SCALAR.  Integers and strings are cleared
921              to 0 and "" respectively, while statistics are reset to the ini‐
922              tial empty state.
923
924
925   EXPRESSIONS
926       Systemtap  supports  a  number  of operators that have the same general
927       syntax, semantics, and precedence as in C and awk.  Arithmetic is  per‐
928       formed as per typical C rules for signed integers.  Division by zero or
929       overflow is detected and results in an error.
930
931       binary numeric operators
932              * / % + - >> << & ^ | && ||
933
934       binary string operators
935              .  (string concatenation)
936
937       numeric assignment operators
938              = *= /= %= += -= >>= <<= &= ^= |=
939
940       string assignment operators
941              = .=
942
943       unary numeric operators
944              + - ! ~ ++ --
945
946       binary numeric, string comparison or regex matching operators
947              < > <= >= == != =~ !~
948
949       ternary operator
950              cond ? exp1 : exp2
951
952       grouping operator
953              ( exp )
954
955       function call
956              fn ([ arg1, arg2, ... ])
957
958       array membership check
959              exp in array
960              [exp1, exp2, ...] in array
961              [*, *, ... ]in array
962
963
964   REGULAR EXPRESSION MATCHING
965       The scripting language supports regular expression matching.  The basic
966       syntax is as follows:
967
968              exp =~ regex
969              exp !~ regex
970
971       (The  first  operand  must be an expression evaluating to a string; the
972       second operand must be a  string  literal  containing  a  syntactically
973       valid regular expression.)
974
975       The  regular  expression  syntax supports most of the features of POSIX
976       Extended Regular Expressions, except  for  subexpression  reuse  ("\1")
977       functionality.  The  ability to capture and extract the contents of the
978       matched string and subexpressions has not yet been implemented.
979
980
981   PROBES
982       The main construct in the scripting language identifies probes.  Probes
983       associate abstract events with a statement block ("probe handler") that
984       is to be executed when any of those events occur.  The  general  syntax
985       is as follows:
986
987              probe PROBEPOINT [, PROBEPOINT] { [STMT ...] }
988              probe PROBEPOINT [, PROBEPOINT] if (CONDITION) { [STMT ...] }
989
990
991       Events  are specified in a special syntax called "probe points".  There
992       are several varieties of probe points defined by  the  translator,  and
993       tapset scripts may define further ones using aliases.  Probe points may
994       be wildcarded, grouped, or listed in preference sequences, or  declared
995       optional.   More details on probe point syntax and semantics are listed
996       on the stapprobes(3stap) manual page.
997
998       The probe handler is interpreted relative to the context of each event.
999       For  events associated with kernel code, this context may include vari‐
1000       ables defined in the source code at that spot.   These  "context  vari‐
1001       ables"  are  presented  to the script as variables whose names are pre‐
1002       fixed with "$".  They may be accessed only  if  the  kernel's  compiler
1003       preserved  them despite optimization.  This is the same constraint that
1004       a debugger user faces when working with optimized code.   In  addition,
1005       the  objects must exist in paged-in memory at the moment of the system‐
1006       tap probe handler's execution, because systemtap must not  cause  (sup‐
1007       presses) any additional paging.  Some probe types have very little con‐
1008       text.  See the stapprobes(3stap) man pages to see the kinds of  context
1009       variables available at each kind of probe point.
1010
1011       Probes  may be decorated with an arming condition, consisting of a sim‐
1012       ple boolean expression on read-only  global  script  variables.   While
1013       disarmed  (condition  evaluates  to  false), some probe types reduce or
1014       eliminate their run-time overheads.  When an arming condition evaluates
1015       to  true,  probes  will be soon re-armed, and their probe handlers will
1016       start getting called as the events fire.  (Some events may be lost dur‐
1017       ing  the  arming  interval.  If this is unacceptable, do not use arming
1018       conditions for those probes.)
1019
1020       New probe points may be defined using "aliases".  Probe  point  aliases
1021       look similar to probe definitions, but instead of activating a probe at
1022       the given point, it just defines a new probe point name as an alias  to
1023       an  existing one. There are two types of alias, i.e. the prologue style
1024       and the epilogue style which are identified by "=" and "+=" respective‐
1025       ly.
1026
1027       For  prologue  style  alias,  the statement block that follows an alias
1028       definition is implicitly added as a prologue to any probe  that  refers
1029       to  the  alias. While for the epilogue style alias, the statement block
1030       that follows an alias definition is implicitly added as an epilogue  to
1031       any probe that refers to the alias.  For example:
1032
1033              probe syscall.read = kernel.function("sys_read") {
1034                fildes = $fd
1035                if (execname() == "init") next  # skip rest of probe
1036              }
1037
1038       defines   a   new   probe   point   syscall.read,   which   expands  to
1039       kernel.function("sys_read"), with the given statement  as  a  prologue,
1040       which  is  useful to predefine some variables for the alias user and/or
1041       to skip probe processing entirely based on some conditions.  And
1042
1043              probe syscall.read += kernel.function("sys_read") {
1044                if (tracethis) println ($fd)
1045              }
1046
1047       defines a new probe point with the  given  statement  as  an  epilogue,
1048       which  is  useful to take actions based upon variables set or left over
1049       by the the alias user.  Please note that in each case,  the  statements
1050       in  the  alias  handler block are treated ordinarily, so that variables
1051       assigned there constitute mere initialization, not  a  macro  substitu‐
1052       tion.
1053
1054       An alias is used just like a built-in probe type.
1055
1056              probe syscall.read {
1057                printf("reading fd=%d\n", fildes)
1058                if (fildes > 10) tracethis = 1
1059              }
1060
1061
1062
1063   FUNCTIONS
1064       Systemtap  scripts  may  define  subroutines to factor out common work.
1065       Functions take any number of scalar (integer or string) arguments,  and
1066       must  return  a single scalar (integer or string).  An example function
1067       declaration looks like this:
1068
1069              function thisfn (arg1, arg2) {
1070                 return arg1 + arg2
1071              }
1072
1073       Note the general absence of type declarations, which  are  instead  in‐
1074       ferred  by  the translator.  However, if desired, a function definition
1075       may include explicit type declarations for its return value and/or  its
1076       arguments.   This  is  especially helpful for embedded-C functions.  In
1077       the following example, the type inference engine need only  infer  type
1078       type of arg2 (a string).
1079
1080              function thatfn:string (arg1:long, arg2) {
1081                 return sprint(arg1) . arg2
1082              }
1083
1084       Functions  may  call  others  or  themselves recursively, up to a fixed
1085       nesting limit.  This limit is defined by a macro in  the  translated  C
1086       code and is in the neighbourhood of 10.
1087
1088
1089   PRINTING
1090       There  are  a  set  of function names that are specially treated by the
1091       translator.  They format values for printing to the standard  systemtap
1092       output  stream  in  a more convenient way.  The sprint* variants return
1093       the formatted string instead of printing it.
1094
1095       print, sprint
1096              Print one or more values of any type, concatenated directly  to‐
1097              gether.
1098
1099       println, sprintln
1100              Print values like print and sprint, but also append a newline.
1101
1102       printd, sprintd
1103              Take  a string delimiter and two or more values of any type, and
1104              print the values with the delimiter interposed.   The  delimiter
1105              must be a literal string constant.
1106
1107       printdln, sprintdln
1108              Print  values with a delimiter like printd and sprintd, but also
1109              append a newline.
1110
1111       printf, sprintf
1112              Take a formatting string and a number of values of corresponding
1113              types,  and print them all.  The format must be a literal string
1114              constant.
1115
1116       The printf formatting directives similar to those  of  C,  except  that
1117       they are fully type-checked by the translator:
1118
1119              %b     Writes a binary blob of the value given, instead of ASCII
1120                     text.  The width specifier determines the number of bytes
1121                     to  write;  valid specifiers are %b %1b %2b %4b %8b.  De‐
1122                     fault (%b) is 8 bytes.
1123
1124              %c     Character.
1125
1126              %d,%i  Signed decimal.
1127
1128              %m     Safely reads kernel memory at the given address,  outputs
1129                     its content.  The optional precision specifier (not field
1130                     width) determines the number of bytes to read  -  default
1131                     is  1  byte.   %10.4m  prints  4 bytes of the memory in a
1132                     10-character-wide field.
1133
1134              %M     Same as %m, but outputs in hexadecimal.  The minimal size
1135                     of  output  is  double the optional precision specifier -
1136                     default is 1 byte (2 hex chars).  %10.4M prints  4  bytes
1137                     of the memory as 8 hexadecimal characters in a 10-charac‐
1138                     ter-wide field.
1139
1140              %o     Unsigned octal.
1141
1142              %p     Unsigned pointer address.
1143
1144              %s     String.
1145
1146              %u     Unsigned decimal.
1147
1148              %x     Unsigned hex value, in all lower-case.
1149
1150              %X     Unsigned hex value, in all upper-case.
1151
1152              %%     Writes a %.
1153
1154       The # flag selects the alternate forms.  For octal, this prefixes a  0.
1155       For  hex,  this  prefixes 0x or 0X, depending on case.  For characters,
1156       this escapes non-printing values with either C-like escapes or raw  oc‐
1157       tal.
1158
1159       Examples:
1160
1161              a = "alice", b = "bob", p = 0x1234abcd, i = 123, j = -1, id[a] = 1234, id[b] = 4567
1162              print("hello")
1163                   Prints: hello
1164              println(b)
1165                   Prints: bob\n
1166              println(a . " is " . sprint(16))
1167                   Prints: alice is 16
1168              foreach (name in id)  printdln("|", strlen(name), name, id[name])
1169                   Prints: 5|alice|1234\n3|bob|4567
1170              printf("%c is %s; %x or %X or %p; %d or %u\n",97,a,p,p,p,j,j)
1171                   Prints: a is alice; 1234abcd or 1234ABCD or 0x1234abcd; -1 or 18446744073709551615\n
1172              printf("2 bytes of kernel buffer at address %p: %2m", p, p)
1173                   Prints: 2 byte of kernel buffer at address 0x1234abcd: <binary data>
1174              printf("%4b", p)
1175                   Prints (these values as binary data): 0x1234abcd
1176              printf("%#o %#x %#X\n", 1, 2, 3)
1177                   Prints: 01 0x2 0X3
1178              printf("%#c %#c %#c\n", 0, 9, 42)
1179                   Prints: \000 \t *
1180
1181
1182
1183   STATISTICS
1184       It  is  often  desirable to collect statistics in a way that avoids the
1185       penalties of repeatedly exclusive locking the  global  variables  those
1186       numbers are being put into.  Systemtap provides a solution using a spe‐
1187       cial operator to accumulate values, and several pseudo-functions to ex‐
1188       tract the statistical aggregates.
1189
1190       The  aggregation operator is <<<, and resembles an assignment, or a C++
1191       output-streaming operation.  The left operand specifies a scalar or ar‐
1192       ray-index  lvalue, which must be declared global.  The right operand is
1193       a numeric expression.  The meaning is intuitive: add the  given  number
1194       to the pile of numbers to compute statistics of.  (The specific list of
1195       statistics to gather is given separately, by the extraction functions.)
1196
1197              foo <<< 1
1198              stats[pid()] <<< memsize
1199
1200
1201       The extraction functions are also special.  For each  appearance  of  a
1202       distinct  extraction  function  operating  on  a  given identifier, the
1203       translator arranges to compute a set of  statistics  that  satisfy  it.
1204       The statistics system is thereby "on-demand".  Each execution of an ex‐
1205       traction function causes the aggregation to be computed for that moment
1206       across all processors.
1207
1208       Here  is the set of extractor functions.  The first argument of each is
1209       the same style of lvalue used on the left hand side of  the  accumulate
1210       operation.  The @count(v), @sum(v), @min(v), @max(v), @avg(v) extractor
1211       functions compute the number/total/minimum/maximum/average of all accu‐
1212       mulated  values.  The resulting values are all simple integers.  Arrays
1213       containing aggregates may be sorted and iterated.  See the foreach con‐
1214       struct above.
1215
1216       Histograms  are  also  available, but are more complicated because they
1217       have a vector rather than scalar value.   @hist_linear(v,start,stop,in‐
1218       terval)  represents a linear histogram from "start" to "stop" by incre‐
1219       ments  of  "interval".   The  interval  must  be  positive.  Similarly,
1220       @hist_log(v) represents a base-2 logarithmic histogram. Printing a his‐
1221       togram with the print family of functions renders a histogram object as
1222       a tabular "ASCII art" bar chart.
1223
1224              probe timer.profile {
1225                x[1] <<< pid()
1226                x[2] <<< uid()
1227                y <<< tid()
1228              }
1229              global x // an array containing aggregates
1230              global y // a scalar
1231              probe end {
1232                foreach ([i] in x @count+) {
1233                   printf ("x[%d]: avg %d = sum %d / count %d\n",
1234                           i, @avg(x[i]), @sum(x[i]), @count(x[i]))
1235                   println (@hist_log(x[i]))
1236                }
1237                println ("y:")
1238                println (@hist_log(y))
1239              }
1240
1241
1242
1243   TYPECASTING
1244       Once a pointer (see the CONTEXT VARIABLES section of stapprobes(3stap))
1245       has been saved into a script integer variable, the translator loses the
1246       type  information necessary to access members from that pointer.  Using
1247       the @cast() operator tells the translator how to interpret  the  number
1248       as a typed pointer.
1249
1250              @cast(p, "type_name"[, "module"])->member
1251
1252
1253       This  will  interpret  p as a pointer to a struct/union named type_name
1254       and dereference the member value.  Further ->subfield  expressions  may
1255       be  appended to dereference more levels.   NOTE: the same dereferencing
1256       operator -> is used to refer to both direct containment or pointer  in‐
1257       direction.   Systemtap  automatically  determines  which.  The optional
1258       module tells the translator where to look for  information  about  that
1259       type.   Multiple  modules may be specified as a list with : separators.
1260       If the module is not specified, it will default  either  to  the  probe
1261       module  for  dwarf  probes,  or to "kernel" for functions and all other
1262       probes types.
1263
1264       The translator can create its own module with type information  from  a
1265       header  surrounded  by  angle brackets, in case normal debuginfo is not
1266       available.  For kernel headers, prefix it with "kernel" to use the  ap‐
1267       propriate  build  system.  All other headers are build with default GCC
1268       parameters into a user module.  Multiple headers may  be  specified  in
1269       sequence to resolve a codependency.
1270
1271              @cast(tv, "timeval", "<sys/time.h>")->tv_sec
1272              @cast(task, "task_struct", "kernel<linux/sched.h>")->tgid
1273              @cast(task, "task_struct",
1274                    "kernel<linux/sched.h><linux/fs_struct.h>")->fs->umask
1275
1276       Values  acquired  by @cast may be pretty-printed by the $ and $$ suffix
1277       operators, the same way as described in the CONTEXT  VARIABLES  section
1278       of the stapprobes(3stap) manual page.
1279
1280
1281       When in guru mode, the translator will also allow scripts to assign new
1282       values to members of typecasted pointers.
1283
1284       Typecasting is also useful in the case of void* members whose type  may
1285       be determinable at runtime.
1286
1287              probe foo {
1288                if ($var->type == 1) {
1289                  value = @cast($var->data, "type1")->bar
1290                } else {
1291                  value = @cast($var->data, "type2")->baz
1292                }
1293                print(value)
1294              }
1295
1296
1297
1298   EMBEDDED C
1299       When in guru mode, the translator accepts embedded code in the top lev‐
1300       el of the script.  Such code is enclosed between %{ and %} markers, and
1301       is  transcribed  verbatim, without analysis, in some sequence, into the
1302       top level of the generated C code.  At the outermost level, this may be
1303       useful  to add #include instructions, and any auxiliary definitions for
1304       use by other embedded code.
1305
1306       Another place where embedded code is permitted is as a  function  body.
1307       In  this case, the script language body is replaced entirely by a piece
1308       of C code enclosed again between %{ and %} markers.  This C code may do
1309       anything  reasonable  and safe.  There are a number of undocumented but
1310       complex safety constraints on atomicity, concurrency, resource consump‐
1311       tion, and run time limits, so this is an advanced technique.
1312
1313       The  memory  locations  set  aside for input and output values are made
1314       available to it using macros STAP_ARG_* and STAP_RETVALUE.  Errors  may
1315       be  signalled  with STAP_ERROR. Output may be written with STAP_PRINTF.
1316       The function may return early with STAP_RETURN.  Here  are  some  exam‐
1317       ples:
1318
1319              function integer_ops (val) %{
1320                STAP_PRINTF("%d\n", STAP_ARG_val);
1321                STAP_RETVALUE = STAP_ARG_val + 1;
1322                if (STAP_RETVALUE == 4)
1323                    STAP_ERROR("wrong guess: %d", (int) STAP_RETVALUE);
1324                if (STAP_RETVALUE == 3)
1325                    STAP_RETURN(0);
1326                STAP_RETVALUE ++;
1327              %}
1328              function string_ops (val) %{
1329                strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN);
1330                strlcat (STAP_RETVALUE, "one", MAXSTRINGLEN);
1331                if (strcmp (STAP_RETVALUE, "three-two-one"))
1332                    STAP_RETURN("parameter should be three-two-");
1333              %}
1334              function no_ops () %{
1335                  STAP_RETURN(); /* function inferred with no return value */
1336              %}
1337
1338       The function argument and return value types have to be inferred by the
1339       translator from the call sites in order for  this  to  work.  The  user
1340       should  examine C code generated for ordinary script-language functions
1341       in order to write compatible embedded-C ones.
1342
1343       The last place where embedded code is permitted  is  as  an  expression
1344       rvalue.  In this case, the C code enclosed between %{ and %} markers is
1345       interpreted as an ordinary expression value.  It is  assumed  to  be  a
1346       normal  64-bit signed number, unless the marker /* string */ is includ‐
1347       ed, in which case it's treated as a string.
1348
1349              function add_one (val) {
1350                return val + %{ 1 %}
1351              }
1352              function add_string_two (val) {
1353                return val . %{ /* string */ "two" %}
1354              }
1355
1356
1357       The embedded-C code may contain  markers  to  assert  optimization  and
1358       safety properties.
1359
1360       /* pure */
1361              means  that the C code has no side effects and may be elided en‐
1362              tirely if its value is not used by script code.
1363
1364       /* stable */
1365              means that the C code always has the same value  (in  any  given
1366              probe handler invocation), so repeated calls may be automatical‐
1367              ly replaced by memoized values.  Such functions must take no pa‐
1368              rameters, and also be pure.
1369
1370       /* unprivileged */
1371              means  that  the  C code is so safe that even unprivileged users
1372              are permitted to use it.
1373
1374       /* myproc-unprivileged */
1375              means that the C code is so safe that  even  unprivileged  users
1376              are permitted to use it, provided that the target of the current
1377              probe is within the user's own process.
1378
1379       /* guru */
1380              means that the C code is so unsafe that a  systemtap  user  must
1381              specify -g (guru mode) to use this.
1382
1383       /* unmangled */
1384              in an embedded-C function, means that the legacy (pre-1.8) argu‐
1385              ment access syntax should be made available inside the function.
1386              Hence, in addition to STAP_ARG_foo and STAP_RETVALUE one can use
1387              THIS->foo and THIS->__retvalue respectively inside the function.
1388              This  is useful for quickly migrating code written for SystemTap
1389              version 1.7 and earlier.
1390
1391       /* unmodified-fnargs */
1392              in an embedded-C function, means that the function arguments are
1393              not modified inside the function body.
1394
1395       /* string */
1396              in  embedded-C  expressions  only, means that the expression has
1397              const char * type and should be treated as a string  value,  in‐
1398              stead of the default long numeric.
1399
1400
1401   BUILT-INS
1402       A  set  of  builtin probe point aliases are provided by the scripts in‐
1403       stalled in the directory specified in  the  stappaths(7)  manual  page.
1404       The functions are described in the stapprobes(3stap) manual page.
1405
1406

PROCESSING

1408       The translator begins pass 1 by parsing the given input script, and all
1409       scripts (files named *.stp) found in a tapset directory.  The  directo‐
1410       ries  listed with -I are processed in sequence, each processed in "guru
1411       mode".  For  each  directory,  a  number  of  subdirectories  are  also
1412       searched.   These  subdirectories  are derived from the selected kernel
1413       version (the -R option), in order to allow more kernel-version-specific
1414       scripts to override less specific ones.  For example, for a kernel ver‐
1415       sion 2.6.12-23.FC3 the following patterns would  be  searched,  in  se‐
1416       quence:   2.6.12-23.FC3/*.stp,  2.6.12/*.stp,  2.6/*.stp,  and  finally
1417       *.stp.  Stopping the translator after pass 1 causes  it  to  print  the
1418       parse trees.
1419
1420
1421       In  pass 2, the translator analyzes the input script to resolve symbols
1422       and types.  References to variables, functions, and probe aliases  that
1423       are unresolved internally are satisfied by searching through the parsed
1424       tapset script files.  If any tapset script file is selected because  it
1425       defines  an  unresolved symbol, then the entirety of that file is added
1426       to the translator's resolution queue.  This process iterates until  all
1427       symbols are resolved and a subset of tapset script files is selected.
1428
1429       Next, all probe point descriptions are validated against the wide vari‐
1430       ety supported by the translator.  Probe points that refer to code loca‐
1431       tions  ("synchronous  probe points") require the appropriate kernel de‐
1432       bugging information to be installed.  In the associated probe handlers,
1433       target-side  variables  (whose names begin with "$") are found and have
1434       their run-time locations decoded.
1435
1436       Next, all probes and functions are analyzed for optimization opportuni‐
1437       ties,  in  order  to  remove variables, expressions, and functions that
1438       have no useful value and no side-effect.  Embedded-C functions are  as‐
1439       sumed  to  have  side-effects  unless  they  include  the  magic string
1440       /* pure */.  Since this optimization can hide latent code  errors  such
1441       as  type  mismatches or invalid $context variables, it sometimes may be
1442       useful to disable the optimizations with the -u option.
1443
1444       Finally, all variable, function, parameter, array, and index types  are
1445       inferred  from context (literals and operators).  Stopping the transla‐
1446       tor after pass 2 causes it to list all the probes, functions, and vari‐
1447       ables,  along  with all inferred types.  Any inconsistent or unresolved
1448       types cause an error.
1449
1450
1451       In pass 3, the translator writes C code that represents the actions  of
1452       all  selected script files, and creates a Makefile to build that into a
1453       kernel object.  These files are  placed  into  a  temporary  directory.
1454       Stopping  the  translator at this point causes it to print the contents
1455       of the C file.
1456
1457
1458       In pass 4, the translator invokes the Linux kernel build system to cre‐
1459       ate  the  actual kernel object file.  This involves running make in the
1460       temporary directory, and requires a kernel module build  system  (head‐
1461       ers,  config and Makefiles) to be installed in the usual spot /lib/mod‐
1462       ules/VERSION/build.  Stopping the translator after pass 4 is  the  last
1463       chance  before  running  the  kernel object.  This may be useful if you
1464       want to archive the file.
1465
1466
1467       In pass 5, the  translator  invokes  the  systemtap  auxiliary  program
1468       staprun  program for the given kernel object.  This program arranges to
1469       load the module then communicates with it, copying trace data from  the
1470       kernel  into temporary files, until the user sends an interrupt signal.
1471       Any run-time error encountered by the probe handlers, such  as  running
1472       out  of  memory, division by zero, exceeding nesting or runtime limits,
1473       results in a soft error indication.  Soft errors in excess of MAXERRORS
1474       block of all subsequent probes (except error-handling probes), and ter‐
1475       minate the session.  Finally, staprun unloads the  module,  and  cleans
1476       up.
1477
1478
1479   ABNORMAL TERMINATION
1480       One  should  avoid  killing the stap process forcibly, for example with
1481       SIGKILL, because the stapio  process  (a  child  process  of  the  stap
1482       process)  and  the loaded module may be left running on the system.  If
1483       this happens, send SIGTERM or SIGINT to any remaining stapio processes,
1484       then use rmmod to unload the systemtap module.
1485
1486
1487

EXAMPLES

1489       See the stapex(3stap) manual page for a brief collection of samples, or
1490       a large  set  of  installed  samples  under  the  systemtap  documenta‐
1491       tion/testsuite  directories.  See stappaths(7stap) for the likely loca‐
1492       tion of these on the system.
1493
1494

CACHING

1496       The systemtap translator caches the pass  3  output  (the  generated  C
1497       code) and the pass 4 output (the compiled kernel module) if pass 4 com‐
1498       pletes successfully.  This cached output is reused if the  same  script
1499       is  translated  again  assuming  the same conditions exist (same kernel
1500       version, same systemtap version, etc.).  Cached files are stored in the
1501       $SYSTEMTAP_DIR/cache  directory. The cache can be limited by having the
1502       file cache_mb_limit placed in the cache directory  (shown  above)  con‐
1503       taining  only  an  ASCII  integer  representing  how many MiB the cache
1504       should not exceed. In the absence of this file, a default will be  cre‐
1505       ated  with the limit set to 256MiB.  This is a 'soft' limit in that the
1506       cache will be cleaned after a new entry is added if the cache clean in‐
1507       terval is exceeded, so the total cache size may temporarily exceed this
1508       limit.  This  interval  can   be   specified   by   having   the   file
1509       cache_clean_interval_s placed in the cache directory (shown above) con‐
1510       taining only an ASCII integer representing the interval in seconds.  In
1511       the  absence  of this file, a default will be created with the interval
1512       set to 300 s.
1513
1514

SAFETY AND SECURITY

1516       Systemtap is may be used as a powerful administrative tool.  It can ex‐
1517       pose  kernel  internal data structures and potentially private user in‐
1518       formation.  (In dyninst runtime mode, this is not the case, see the AL‐
1519       TERNATE RUNTIMES section below.)
1520
1521       The  translator  asserts many safety constraints during compilation and
1522       more during run-time.  It aims to ensure that no  handler  routine  can
1523       run  for  very  long,  allocate boundless memory, perform unsafe opera‐
1524       tions, or in unintentionally interfere with the system.  Uses of script
1525       global variables are automatically read/write locked as appropriate, to
1526       protect against manipulation by concurrent probe handlers.   (Deadlocks
1527       are  detected with timeouts.  Use the -t flag to receive reports of ex‐
1528       cessive lock contention.)  Experimenting with scripts is therefore gen‐
1529       erally  safe.   The guru-mode -g option allows administrators to bypass
1530       most safety measures, which permits invasive or  state-changing  opera‐
1531       tions,  embedded-C  code, and increases the risk of upset.  By default,
1532       overload prevention is turned on for all modules.  If you would like to
1533       disable overload processing, use the --suppress-time-limits option.
1534
1535       Errors  that  are  caught at run time normally result in a clean script
1536       shutdown and a pass-5 error message.  The --suppress-handler-errors op‐
1537       tion lets scripts tolerate soft errors without shutting down.
1538
1539
1540
1541   PERMISSIONS
1542       For  the  normal linux-kernel-module runtime, to run the kernel objects
1543       systemtap builds, a user must be one of the following:
1544
1545       ·   the root user;
1546
1547       ·   a member of the stapdev and stapusr groups;
1548
1549       ·   a member of the stapsys and stapusr groups; or
1550
1551       ·   a member of the stapusr group.
1552
1553       The root user or a user who is a member of both the stapdev and stapusr
1554       groups can build and run any systemtap script.
1555
1556       A  user who is a member of both the stapsys and stapusr groups can only
1557       use pre-built modules under the following conditions:
1558
1559       ·   The module has been signed by a trusted signer. Trusted signers are
1560           normally  systemtap  compile-servers  which  sign  modules when the
1561           --privilege option is specified by the client. See  the  stap-serv‐
1562           er(8) manual page for more information.
1563
1564       ·   The  module was built using the --privilege=stapsys or the --privi‐
1565           lege=stapusr options.
1566
1567       Members of only the stapusr group can only use pre-built modules  under
1568       the following conditions:
1569
1570       ·   The  module is located in the /lib/modules/VERSION/systemtap direc‐
1571           tory.  This directory must be  owned  by  root  and  not  be  world
1572           writable.
1573
1574       or
1575
1576       ·   The module has been signed by a trusted signer. Trusted signers are
1577           normally systemtap compile-servers  which  sign  modules  when  the
1578           --privilege  option  is specified by the client. See the stap-serv‐
1579           er(8) manual page for more information.
1580
1581       ·   The module was built using the --privilege=stapusr option.
1582
1583       The kernel modules generated by stap program are  run  by  the  staprun
1584       program.   The  latter is a part of the Systemtap package, dedicated to
1585       module loading and unloading (but only in the white zone), and  kernel-
1586       to-user  data  transfer.  Since staprun does not perform any additional
1587       security checks on the kernel objects it is given, it would  be  unwise
1588       for  a  system  administrator  to add untrusted users to the stapdev or
1589       stapusr groups.
1590
1591
1592   SECUREBOOT
1593       If the current system has SecureBoot turned on in  the  UEFI  firmware,
1594       all  kernel  modules must be signed.  (Some kernels may allow disabling
1595       SecureBoot long after booting with a key sequence such as SysRq-X, mak‐
1596       ing  it unnecessary to sign modules.)  The systemtap compile server can
1597       sign modules with a MOK (Machine Owner Key) that it has in common  with
1598       a client system. See the following wiki page for more details:
1599
1600              https://sourceware.org/systemtap/wiki/SecureBoot
1601
1602
1603   RESOURCE LIMITS
1604       Many  resource  use  limits  are set by macros in the generated C code.
1605       These may be overridden with -D flags.  A selection of these is as fol‐
1606       lows:
1607
1608       MAXNESTING
1609              Maximum  number of nested function calls.  Default determined by
1610              script analysis, with a  bonus  10  slots  added  for  recursive
1611              scripts.
1612
1613       MAXSTRINGLEN
1614              Maximum length of strings, default 128.
1615
1616       MAXTRYLOCK
1617              Maximum  number  of iterations to wait for locks on global vari‐
1618              ables before declaring possible deadlock and skipping the probe,
1619              default 1000.
1620
1621       MAXACTION
1622              Maximum  number of statements to execute during any single probe
1623              hit (with interrupts disabled), default  1000.   Note  that  for
1624              straight-through  probe handlers lacking loops or recursion, due
1625              to optimization, this parameter may be interpreted too conserva‐
1626              tively.
1627
1628       MAXACTION_INTERRUPTIBLE
1629              Maximum  number of statements to execute during any single probe
1630              hit which is executed with interrupts enabled (such as begin/end
1631              probes), default (MAXACTION * 10).
1632
1633       MAXBACKTRACE
1634              Maximum  number of stack frames that will be be processed by the
1635              stap runtime unwinder as produced by the backtrace functions  in
1636              the [u]context-unwind.stp tapsets, default 20.
1637
1638       MAXMAPENTRIES
1639              Default  maximum  number of rows in any single global array, de‐
1640              fault 2048.  Individual arrays may be declared with a larger  or
1641              smaller limit instead:
1642
1643              global big[10000],little[5]
1644
1645              or denoted with % to make them wrap-around automatically.
1646
1647       MAXERRORS
1648              Maximum  number  of soft errors before an exit is triggered, de‐
1649              fault 0, which means that the first error will exit the  script.
1650              Note  that with the --suppress-handler-errors option, this limit
1651              is not enforced.
1652
1653       MAXSKIPPED
1654              Maximum number of skipped probes before an  exit  is  triggered,
1655              default 100.  Running systemtap with -t (timing) mode gives more
1656              details about skipped probes.   With  the  default  -DINTERRUPT‐
1657              IBLE=1 setting, probes skipped due to reentrancy are not accumu‐
1658              lated against this limit.  Note that  with  the  --suppress-han‐
1659              dler-errors option, this limit is not enforced.
1660
1661       MINSTACKSPACE
1662              Minimum  number  of free kernel stack bytes required in order to
1663              run a probe handler, default 1024.  This number should be  large
1664              enough for the probe handler's own needs, plus a safety margin.
1665
1666       MAXUPROBES
1667              Maximum  number  of  concurrently  armed  user-space probes (up‐
1668              robes), default somewhat larger than the  number  of  user-space
1669              probe  points named in the script.  This pool needs to be poten‐
1670              tially large because individual uprobe objects (about  64  bytes
1671              each)  are  allocated for each process for each matching script-
1672              level probe.
1673
1674       STP_MAXMEMORY
1675              Maximum amount of memory (in kilobytes) that the systemtap  mod‐
1676              ule should use, default unlimited.  The memory size includes the
1677              size of the module  itself,  plus  any  additional  allocations.
1678              This  only  tracks  direct allocations by the systemtap runtime.
1679              This does not track indirect allocations (as done by kprobes/up‐
1680              robes/etc. internals).
1681
1682       STP_OVEROAD_THRESHOLD, STP_OVERLOAD_INTERVAL
1683              Maximum  number of machine cycles spent in probes on any cpu per
1684              given interval, before an overload condition is declared and the
1685              script  shut  down.  The defaults are 500 million and 1 billion,
1686              so as to limit stap script cpu consumption at around 50%.
1687
1688       STP_PROCFS_BUFSIZE
1689              Size of procfs probe  read  buffers  (in  bytes).   Defaults  to
1690              MAXSTRINGLEN.  This value can be overridden on a per-procfs file
1691              basis using the procfs read probe .maxsize(MAXSIZE) parameter.
1692
1693       With scripts that contain probes on any interrupt path, it is  possible
1694       that those interrupts may occur in the middle of another probe handler.
1695       The probe in the interrupt handler would be skipped  in  this  case  to
1696       avoid reentrance.  To work around this issue, execute stap with the op‐
1697       tion -DINTERRUPTIBLE=0 to mask interrupts throughout the probe handler.
1698       This  does  add  some  extra overhead to the probes, but it may prevent
1699       reentrance for common problem cases.  However, probes in  NMI  handlers
1700       and  in  the  callpath  of the stap runtime may still be skipped due to
1701       reentrance.
1702
1703
1704       Multiple scripts can write data into a  relay  buffer  concurrently.  A
1705       host  script  provides  an  interface for accessing its relay buffer to
1706       guest scripts.  Then, the output of the guests are merged into the out‐
1707       put of the host.  To run a script as a host, execute stap with -DRELAY‐
1708       HOST[=name] option. The name identifies your host script among  several
1709       hosts.   While  running the host, execute stap with -DRELAYGUEST[=name]
1710       to add a guest script to the host.  Note that you  must  unload  guests
1711       before  unloading  a  host.  If  there are some guests connected to the
1712       host, unloading the host will be failed.
1713
1714
1715       In case something goes wrong with stap or staprun after a probe has al‐
1716       ready started running, one may safely kill both user processes, and re‐
1717       move the active probe kernel module with rmmod.  Any pending trace mes‐
1718       sages may be lost.
1719
1720

UNPRIVILEGED USERS

1722       Systemtap  exposes kernel internal data structures and potentially pri‐
1723       vate user information. Because of this, use of systemtap's  full  capa‐
1724       bilities  are  restricted  to  root and to users who are members of the
1725       groups stapdev and stapusr.
1726
1727       However, a restricted set of systemtap's features can be made available
1728       to  trusted,  unprivileged  users. These users are members of the group
1729       stapusr only, or members of the  groups  stapusr  and  stapsys.   These
1730       users can load systemtap modules which have been compiled and certified
1731       by a trusted systemtap compile-server. See the descriptions of the  op‐
1732       tions --privilege and --use-server. See README.unprivileged in the sys‐
1733       temtap source code for information about setting up a  trusted  compile
1734       server.
1735
1736       The restrictions enforced when --privilege=stapsys is specified are de‐
1737       signed to prevent unprivileged users from:
1738
1739              ·   harming the system maliciously.
1740
1741       The restrictions enforced when --privilege=stapusr is specified are de‐
1742       signed to prevent unprivileged users from:
1743
1744              ·   harming the system maliciously.
1745
1746              ·   gaining  access  to  information which would not normally be
1747                  available to an unprivileged user.
1748
1749              ·   disrupting the performance of processes owned by other users
1750                  of  the  system.   Some overhead to the system in general is
1751                  unavoidable since the unprivileged  user's  probes  will  be
1752                  triggered  at  the  appropriate times. What we would like to
1753                  avoid is targeted interruption of another  user's  processes
1754                  which  would not normally be possible by an unprivileged us‐
1755                  er.
1756
1757
1758   PROBE RESTRICTIONS
1759       A member of the groups stapusr and stapsys may use all probe points.
1760
1761       A member of only the group stapusr may use only the following probes:
1762
1763              ·   begin, begin(n)
1764
1765              ·   end, end(n)
1766
1767              ·   error(n)
1768
1769              ·   never
1770
1771              ·   process.*, where the target process is owned by the user.
1772
1773              ·   timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)*
1774
1775              ·   timer.hz(n)
1776
1777
1778   SCRIPT LANGUAGE RESTRICTIONS
1779       The following scripting language features are unavailable  to  all  un‐
1780       privileged users:
1781
1782
1783              ·   any feature enabled by the Guru Mode (-g) option.
1784
1785              ·   embedded C code.
1786
1787
1788   RUNTIME RESTRICTIONS
1789       The  following  runtime  restrictions  are placed upon all unprivileged
1790       users:
1791
1792              ·   Only the default runtime code (see -R) may be used.
1793
1794       Additional restrictions are placed on members of only  the  group  sta‐
1795       pusr:
1796
1797              ·   Probing of processes owned by other users is not permitted.
1798
1799              ·   Access of kernel memory (read and write) is not permitted.
1800
1801
1802   COMMAND LINE OPTION RESTRICTIONS
1803       Some  command line options provide access to features which must not be
1804       available to all unprivileged users:
1805
1806
1807              ·   -g may not be specified.
1808
1809              ·   The following options may not be used by the  compile-server
1810                  client:
1811
1812                      -a, -B, -D, -I, -r, -R
1813
1814
1815
1816   ENVIRONMENT RESTRICTIONS
1817       The  following  environment  variables must not be set for all unprivi‐
1818       leged users:
1819
1820              SYSTEMTAP_RUNTIME
1821              SYSTEMTAP_TAPSET
1822              SYSTEMTAP_DEBUGINFO_PATH
1823
1824
1825
1826   TAPSET RESTRICTIONS
1827       In general, tapset functions are only  available  for  members  of  the
1828       group stapusr when they do not gather information that an ordinary pro‐
1829       gram running with that user's privileges would be denied access to.
1830
1831       There are two categories of unprivileged tapset  functions.  The  first
1832       category  consists of utility functions that are unconditionally avail‐
1833       able to all users; these include such things as:
1834
1835              cpu:long ()
1836              exit ()
1837              str_replace:string (prnt_str:string, srch_str:string, rplc_str:string)
1838
1839
1840       The second category consists of so-called myproc-unprivileged functions
1841       that  can  only  gather information within their own processes. Scripts
1842       that wish to use these functions must test the  result  of  the  tapset
1843       function  is_myproc  and  only call these functions if the result is 1.
1844       The script will exit immediately if any of these functions  are  called
1845       by  an  unprivileged  user within a probe within a process which is not
1846       owned by that user. Examples of myproc-unprivileged functions include:
1847
1848              print_usyms (stk:string)
1849              user_int:long (addr:long)
1850              usymname:string (addr:long)
1851
1852
1853       A compile error is triggered when any function not  in  either  of  the
1854       above categories is used by members of only the group stapusr.
1855
1856       No  other  built-in tapset functions may be used by members of only the
1857       group stapusr.
1858
1859

ALTERNATE RUNTIMES

1861       As described above, systemtap's default runtime mode involves  building
1862       and  loading kernel modules, with various security tradeoffs presented.
1863       Systemtap now includes a new prototype backend,  selected  with  --run‐
1864       time=dyninst,  which  uses Dyninst to instrument a user's own processes
1865       at runtime. This backend does not use kernel modules, and does not  re‐
1866       quire  root  privileges, but is restricted with respect to the kinds of
1867       probes and other constructs that a script may use.
1868
1869       The dyninst runtime operates in target-attach mode, so it does  require
1870       a -c COMMAND or -x PID process.  For example:
1871
1872              stap --runtime=dyninst -c 'stap -V' \
1873                   -e 'probe process.function("main")
1874                       { println("hi from dyninst!") }'
1875
1876
1877       It may be necessary to disable a conflicting selinux check with
1878
1879              # setsebool allow_execstack 1
1880
1881
1882

EXIT STATUS

1884       The  systemtap translator generally returns with a success code of 0 if
1885       the requested script was processed and  executed  successfully  through
1886       the  requested  pass.  Otherwise, errors may be printed to stderr and a
1887       failure code is returned.  Use -v or -vp N to increase (global or  per-
1888       pass) verbosity to identify the source of the trouble.
1889
1890       In  listings  mode (-l and -L), error messages are normally suppressed.
1891       A success code of 0 is returned if at  least  one  matching  probe  was
1892       found.
1893
1894       A  script  executing  in pass 5 that is interrupted with ^C / SIGINT is
1895       considered to be successful.
1896
1897

DEPRECATION

1899       Over time, some features of the script language and the tapset  library
1900       may  undergo  incompatible changes, so that a script written against an
1901       old version of systemtap may no longer run.  In  these  cases,  it  may
1902       help  to  run  systemtap with the --compatible VERSION flag, specifying
1903       the  last  known  working  version.    Running   systemtap   with   the
1904       --check-version flag will output a warning if any possible incompatible
1905       elements have been parsed.  Deprecation historical details may be found
1906       in the NEWS file.
1907
1908

FILES

1910       Important files and their corresponding paths can be located in the
1911              stappaths (7) manual page.
1912
1913

SEE ALSO

1915       stapprobes(3stap),
1916       function::*(3stap),
1917       probe::*(3stap),
1918       tapset::*(3stap),
1919       stappaths(7),
1920       staprun(8),
1921       stapdyn(8),
1922       systemtap(8),
1923       stapvars(3stap),
1924       stapex(3stap),
1925       stap-server(8),
1926       stap-prep(1),
1927       stapref(1),
1928       awk(1),
1929       gdb(1)
1930
1931

BUGS

1933       Use  the  Bugzilla  link  of  the project web page or our mailing list.
1934       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
1935
1936       error::reporting(7stap),
1937       https://sourceware.org/systemtap/wiki/HowToReportBugs
1938
1939
1940
1941                                                                       STAP(1)
Impressum