1STAPPROBES(3stap)                                            STAPPROBES(3stap)


6       stapprobes - systemtap probe points


11       The  following sections enumerate the variety of probe points supported
12       by the systemtap translator, and some of the additional aliases defined
13       by  standard  tapset  scripts.  Many are individually documented in the
14       3stap manual section, with the probe:: prefix.


18              probe PROBEPOINT [, PROBEPOINT] { [STMT ...] }
21       A probe declaration may list multiple comma-separated probe  points  in
22       order  to  attach  a handler to all of the named events.  Normally, the
23       handler statements are run whenever any of events occur.  Depending  on
24       the  type  of  probe point, the handler statements may refer to context
25       variables (denoted with a dollar-sign prefix  like  $foo)  to  read  or
26       write state.  This may include function parameters for function probes,
27       or local variables for statement probes.
29       The syntax of a single probe point is a general dotted-symbol sequence.
30       This  allows  a  breakdown  of the event namespace into parts, somewhat
31       like the Domain Name System does on the Internet.  Each component iden‐
32       tifier may be parametrized by a string or number literal, with a syntax
33       like a function call.  A component may include a "*" character, to  ex‐
34       pand  to  a  set of matching probe points.  It may also include "**" to
35       match multiple sequential components at once.  Probe  aliases  likewise
36       expand to other probe points.
38       Probe  aliases  can be given on their own, or with a suffix. The suffix
39       attaches to the underlying probe point that the alias is  expanded  to.
40       For example,
42              syscall.read.return.maxactive(10)
44       expands to
46              kernel.function("sys_read").return.maxactive(10)
48       with the component maxactive(10) being recognized as a suffix.
50       Normally,  each  and  every  probe  point  resulting from wildcard- and
51       alias-expansion must be resolved to some low-level system  instrumenta‐
52       tion  facility  (e.g.,  a kprobe address, marker, or a timer configura‐
53       tion), otherwise the elaboration phase will fail.
55       However, a probe point may be followed by a "?" character, to  indicate
56       that it is optional, and that no error should result if it fails to re‐
57       solve.  Optionalness passes down through all levels  of  alias/wildcard
58       expansion.  Alternately, a probe point may be followed by a "!" charac‐
59       ter, to indicate that it  is  both  optional  and  sufficient.   (Think
60       vaguely  of  the Prolog cut operator.) If it does resolve, then no fur‐
61       ther probe points in the same comma-separated list  will  be  resolved.
62       Therefore,  the  "!"   sufficiency  mark  only makes sense in a list of
63       probe point alternatives.
65       Additionally, a probe point may be followed by a "if (expr)" statement,
66       in  order  to  enable/disable the probe point on-the-fly. With the "if"
67       statement, if the "expr" is false when the  probe  point  is  hit,  the
68       whole  probe  body  including alias's body is skipped. The condition is
69       stacked up through all levels of alias/wildcard expansion. So the final
70       condition  becomes  the  logical-and  of  conditions  of  all  expanded
71       alias/wildcard.  The expressions are necessarily restricted  to  global
72       variables.
74       These  are  all  syntactically valid probe points.  (They are generally
75       semantically invalid, depending on the contents of the tapsets, and the
76       versions of kernel/user software installed.)
79              kernel.function("foo").return
80              process("/bin/vi").statement(0x2222)
81              end
82              syscall.*
83              syscall.*.return.maxactive(10)
84              syscall.{open,close}
85              sys**open
86              kernel.function("no_such_function") ?
87              module("awol").function("no_such_function") !
88              signal.*? if (switch)
89              kprobe.function("foo")
92       Probes may be broadly classified into "synchronous" and "asynchronous".
93       A "synchronous" event is deemed to occur when any processor executes an
94       instruction  matched  by  the specification.  This gives these probes a
95       reference point (instruction address) from which more  contextual  data
96       may  be  available.  Other families of probe points refer to "asynchro‐
97       nous" events such as timers/counters rolling over, where  there  is  no
98       fixed  reference point that is related.  Each probe point specification
99       may match multiple locations (for example, using wildcards or aliases),
100       and  all  them  are  then probed.  A probe declaration may also contain
101       several comma-separated specifications, all of which are probed.
103       Brace expansion is a mechanism which allows a list of probe  points  to
104       be generated. It is very similar to shell expansion. A component may be
105       surrounded by a pair of curly braces to indicate that  the  comma-sepa‐
106       rated  sequence of one or more subcomponents will each constitute a new
107       probe point. The braces may be arbitrarily nested. The ordering of  ex‐
108       panded results is based on product order.
110       The  question mark (?), exclamation mark (!) indicators and probe point
111       conditions may not be placed in any expansions that are before the last
112       component.
114       The following is an example of brace expansion.
117              syscall.{write,read}
118              # Expands to
119              syscall.write, syscall.read
121              {kernel,module("nfs")}.function("nfs*")!
122              # Expands to
123              kernel.function("nfs*")!, module("nfs").function("nfs*")!


128       Resolving some probe points requires DWARF debuginfo or "debug symbols"
129       for the specific program being instrumented.  For some others, DWARF is
130       automatically  synthesized  on  the  fly from source code header files.
131       For others, it is not needed at all.  Since a systemtap script may  use
132       any mixture of probe points together, the union of their DWARF require‐
133       ments has to be met on the computer where  script  compilation  occurs.
134       (See the --use-server option and the stap-server(8) man page for infor‐
135       mation about the remote compilation facility, which  allows  these  re‐
136       quirements to be met on a different machine.)
138       The  following  point lists many of the available probe point families,
139       to classify them with respect to their need for DWARF debuginfo for the
140       specific program for that probe point.
143       DWARF                          NON-DWARF                    SYMBOL-TABLE
145       kernel.function, .statement    kernel.mark                  kernel.function*
146       module.function, .statement    process.mark, process.plt    module.function*
147       process.function, .statement   begin, end, error, never     process.function*
148       process.mark*                  timer
149       .function.callee               perf
150       python2, python3               procfs
151                                      kernel.statement.absolute
152       AUTO-GENERATED-DWARF           kernel.data
153                                      kprobe.function
154       kernel.trace                   process.statement.absolute
155                                      process.begin, .end
156                                      netfilter
157                                      java
160       The probe types marked with * asterisks mark fallbacks, where systemtap
161       can sometimes infer subset or substitute information.  In general,  the
162       more  symbolic  /  debugging  information available, the higher quality
163       probing will be available.


168       The following types of probe points may be armed/disarmed on-the-fly to
169       save  overheads during uninteresting times.  Arming conditions may also
170       be added to other types of probes, but will be treated  as  a  wrapping
171       conditional and won't benefit from overhead savings.
174       DISARMABLE                                exceptions
175       kernel.function, kernel.statement
176       module.function, module.statement
177       process.*.function, process.*.statement
178       process.*.plt, process.*.mark
179       timer.                                    timer.profile
180       java


185       The  probe  points begin and end are defined by the translator to refer
186       to the time of session startup and shutdown.  All  "begin"  probe  han‐
187       dlers  are  run,  in  some sequence, during the startup of the session.
188       All global variables will have been initialized prior  to  this  point.
189       All  "end" probes are run, in some sequence, during the normal shutdown
190       of a session, such as in the aftermath of an exit () function call,  or
191       an interruption from the user.  In the case of an error-triggered shut‐
192       down, "end" probes are not run.  There are no target  variables  avail‐
193       able in either context.
195       If the order of execution among "begin" or "end" probes is significant,
196       then an optional sequence number may be provided:
199              begin(N)
200              end(N)
203       The number N may be positive or negative.  The probe handlers  are  run
204       in  increasing  order, and the order between handlers with the same se‐
205       quence number is unspecified.  When "begin" or "end" are given  without
206       a sequence, they are effectively sequence zero.
208       The  error  probe  point  is similar to the end probe, except that each
209       such probe handler run when the session  ends  after  errors  have  oc‐
210       curred.   In  such  cases,  "end"  probes are skipped, but each "error"
211       probe is still attempted.  This kind of probe can be used to  clean  up
212       or emit a "final gasp".  It may also be numerically parametrized to set
213       a sequence.
216   NEVER
217       The probe point never is specially defined by the  translator  to  mean
218       "never".  Its probe handler is never run, though its statements are an‐
219       alyzed for symbol / type correctness as usual.  This probe point may be
220       useful in conjunction with optional probes.
224       The  syscall.* and nd_syscall.*  aliases define several hundred probes,
225       too many to detail here.  They are of the general form:
228              syscall.NAME
229              nd_syscall.NAME
230              syscall.NAME.return
231              nd_syscall.NAME.return
234       Generally, a pair of probes are defined for each normal system call  as
235       listed  in  the  syscalls(2) manual page, one for entry and one for re‐
236       turn.  Those system calls that never return do not have a corresponding
237       .return probe.  The nd_* family of probes are about the same, except it
238       uses non-DWARF based searching mechanisms, which may result in a  lower
239       quality of symbolic context data (parameters), and may miss some system
240       calls.  You may want to try them first, in case kernel debugging infor‐
241       mation is not immediately available.
243       Each probe alias provides a variety of variables. Looking at the tapset
244       source code is the most reliable way.  Generally, each variable  listed
245       in  the  standard manual page is made available as a script-level vari‐
246       able, so syscall.open exposes filename, flags, and mode.  In  addition,
247       a standard suite of variables is available at most aliases:
249       argstr A  pretty-printed  form  of  the  entire  argument list, without
250              parentheses.
252       name   The name of the system call.
254       retval For return probes, the raw numeric system-call result.
256       retstr For return probes, a pretty-printed string form of  the  system-
257              call result.
259       As  usual  for  probe aliases, these variables are all initialized once
260       from the underlying $context variables, so that later changes to  $con‐
261       text  variables are not automatically reflected.  Not all probe aliases
262       obey all of these general guidelines.   Please  report  any  bothersome
263       ones you encounter as a bug.  Note that on some kernel/userspace archi‐
264       tecture combinations (e.g., 32-bit userspace on 64-bit kernel), the un‐
265       derlying $context variables may need explicit sign extension / masking.
266       When this is an issue, consider using the tapset-provided variables in‐
267       stead of raw $context variables.
269       If debuginfo availability is a problem, you may try using the non-DWARF
270       syscall probe aliases instead.  Use the nd_syscall.  prefix instead  of
271       syscall.  The same context variables are available, as far as possible.
274   TIMERS
275       There  are  two  main types of timer probes: "jiffies" timer probes and
276       time interval timer probes.
278       Intervals defined by the standard kernel "jiffies" timer may be used to
279       trigger  probe  handlers  asynchronously.  Two probe point variants are
280       supported by the translator:
283              timer.jiffies(N)
284              timer.jiffies(N).randomize(M)
287       The probe handler is run every N  jiffies  (a  kernel-defined  unit  of
288       time,  typically between 1 and 60 ms).  If the "randomize" component is
289       given, a linearly distributed random value in  the  range  [-M..+M]  is
290       added to N every time the handler is run.  N is restricted to a reason‐
291       able range (1 to around a million), and M is restricted to  be  smaller
292       than  N.  There are no target variables provided in either context.  It
293       is possible for such probes to be run concurrently on a multi-processor
294       computer.
296       Alternatively,  intervals may be specified in units of time.  There are
297       two probe point variants similar to the jiffies timer:
300              timer.ms(N)
301              timer.ms(N).randomize(M)
304       Here, N and M are specified in milliseconds, but the full  options  for
305       units   are   seconds  (s/sec),  milliseconds  (ms/msec),  microseconds
306       (us/usec), nanoseconds (ns/nsec), and hertz (hz).  Randomization is not
307       supported for hertz timers.
309       The  actual resolution of the timers depends on the target kernel.  For
310       kernels prior to 2.6.17, timers are limited to jiffies  resolution,  so
311       intervals  are  rounded  up  to  the  nearest  jiffies interval.  After
312       2.6.17, the implementation uses hrtimers for tighter precision,  though
313       the  actual  resolution will be arch-dependent.  In either case, if the
314       "randomize" component is given, then the random value will be added  to
315       the interval before any rounding occurs.
317       Profiling  timers  are also available to provide probes that execute on
318       all CPUs at the rate of the system tick (CONFIG_HZ) or at a given  fre‐
319       quency  (hz).  On  some  kernels, this is a one-concurrent-user-only or
320       disabled facility, resulting in error -16 (EBUSY) during  probe  regis‐
321       tration.
324              timer.profile.tick
325              timer.profile.freq.hz(N)
328       Full  context information of the interrupted process is available, mak‐
329       ing this probe suitable for a time-based sampling profiler.
331       It is recommended to use the tapset  probe  timer.profile  rather  than
332       timer.profile.tick.  This probe point behaves identically to timer.pro‐
333       file.tick when the underlying functionality  is  available,  and  falls
334       back  to  using perf.sw.cpu_clock on some recent kernels which lack the
335       corresponding profile timer facility.
337       Profiling timers with specified frequencies are  only  accurate  up  to
338       around  100  hz.  You may need to provide a larger value to achieve the
339       desired rate.
341       Note that if a timer probe is set to fire at a very high  rate  and  if
342       the  probe  body  is  complex, succeeding timer probes can get skipped,
343       since the time for them to run has already passed.  Normally  systemtap
344       reports missed probes, but it will not report these skipped probes.
347   DWARF
348       This family of probe points uses symbolic debugging information for the
349       target kernel/module/program, as may be found  in  unstripped  executa‐
350       bles,  or  the  separate  debuginfo  packages.  They allow placement of
351       probes logically into the execution path  of  the  target  program,  by
352       specifying a set of points in the source or object code.  When a match‐
353       ing statement executes on any processor, the probe handler  is  run  in
354       that context.
356       Probe points in the DWARF family can be identified by the target kernel
357       module (or user process), source file, line number, function  name,  or
358       some combination of these.
360       Here is a list of DWARF probe points currently supported:
362              kernel.function(PATTERN)
363              kernel.function(PATTERN).call
364              kernel.function(PATTERN).callee(PATTERN)
365              kernel.function(PATTERN).callee(PATTERN).return
366              kernel.function(PATTERN).callee(PATTERN).call
367              kernel.function(PATTERN).callees(DEPTH)
368              kernel.function(PATTERN).return
369              kernel.function(PATTERN).inline
370              kernel.function(PATTERN).label(LPATTERN)
371              module(MPATTERN).function(PATTERN)
372              module(MPATTERN).function(PATTERN).call
373              module(MPATTERN).function(PATTERN).callee(PATTERN)
374              module(MPATTERN).function(PATTERN).callee(PATTERN).return
375              module(MPATTERN).function(PATTERN).callee(PATTERN).call
376              module(MPATTERN).function(PATTERN).callees(DEPTH)
377              module(MPATTERN).function(PATTERN).return
378              module(MPATTERN).function(PATTERN).inline
379              module(MPATTERN).function(PATTERN).label(LPATTERN)
380              kernel.statement(PATTERN)
381              kernel.statement(PATTERN).nearest
382              kernel.statement(ADDRESS).absolute
383              module(MPATTERN).statement(PATTERN)
384              process("PATH").function("NAME")
385              process("PATH").statement("*@FILE.c:123")
386              process("PATH").library("PATH").function("NAME")
387              process("PATH").library("PATH").statement("*@FILE.c:123")
388              process("PATH").library("PATH").statement("*@FILE.c:123").nearest
389              process("PATH").function("*").return
390              process("PATH").function("myfun").label("foo")
391              process("PATH").function("foo").callee("bar")
392              process("PATH").function("foo").callee("bar").return
393              process("PATH").function("foo").callee("bar").call
394              process("PATH").function("foo").callees(DEPTH)
395              process(PID).function("NAME")
396              process(PID).function("myfun").label("foo")
397              process(PID).plt("NAME")
398              process(PID).plt("NAME").return
399              process(PID).statement("*@FILE.c:123")
400              process(PID).statement("*@FILE.c:123").nearest
401              process(PID).statement(ADDRESS).absolute
403       (See  the  USER-SPACE section below for more information on the process
404       probes.)
406       The list above includes multiple variants and modifiers  which  provide
407       additional functionality or filters. They are:
409              .function
410                     Places  a probe near the beginning of the named function,
411                     so that parameters are available as context variables.
413              .return
414                     Places a probe at the moment after the  return  from  the
415                     named  function,  so the return value is available as the
416                     "$return" context variable.
418              .inline
419                     Filters the results to include only instances of  inlined
420                     functions.  Note  that  inlined  functions do not have an
421                     identifiable return point, so .return is not supported on
422                     .inline probes.
424              .call  Filters the results to include only non-inlined functions
425                     (the opposite set of .inline)
427              .exported
428                     Filters the results to include only exported functions.
430              .statement
431                     Places a probe at the exact spot,  exposing  those  local
432                     variables that are visible there.
434              .statement.nearest
435                     Places  a  probe at the nearest available line number for
436                     each line number given in the statement.
438              .callee
439                     Places a probe  on  the  callee  function  given  in  the
440                     .callee  modifier,  where  the  callee must be a function
441                     called by the target function given in .function. The ad‐
442                     vantage  of  doing  this over directly probing the callee
443                     function is that this probe point is run  only  when  the
444                     callee  is  called  from  the  target  function  (add the
445                     -DSTAP_CALLEE_MATCHALL directive to  override  this  when
446                     calling stap(1)).
448                     Note  that only callees that can be statically determined
449                     are  available.   For  example,  calls  through  function
450                     pointers are not available.  Additionally, calls to func‐
451                     tions located in other objects (e.g.  libraries) are  not
452                     available (instead use another probe point). This feature
453                     will only work for code compiled with GCC 4.7+.
455              .callees
456                     Shortcut for .callee("*"), which places a  probe  on  all
457                     callees of the function.
459              .callees(DEPTH)
460                     Recursively   places  probes  on  callees.  For  example,
461                     .callees(2) will probe both callees of the  target  func‐
462                     tion,   as   well   as  callees  of  those  callees.  And
463                     .callees(3) goes one level deeper, etc...  A callee probe
464                     at  depth  N  is only triggered when the N callers in the
465                     callstack match those  that  were  statically  determined
466                     during  analysis  (this  also  may  be  overridden  using
467                     -DSTAP_CALLEE_MATCHALL).
469       In the above list of probe points, MPATTERN stands for a string literal
470       that aims to identify the loaded kernel module of interest. For in-tree
471       kernel modules, the name suffices (e.g. "btrfs"). The name may also in‐
472       clude  the  "*", "[]", and "?" wildcards to match multiple in-tree mod‐
473       ules. Out-of-tree modules are also supported  by  specifying  the  full
474       path  to the ko file. Wildcards are not supported. The file must follow
475       the convention of being named <module_name>.ko (characters ',' and  '-'
476       are replaced by '_').
478       LPATTERN  stands  for  a source program label. It may also contain "*",
479       "[]", and "?" wildcards. PATTERN stands for a string literal that  aims
480       to identify a point in the program.  It is made up of three parts:
482       ·   The first part is the name of a function, as would appear in the nm
483           program's output.  This part may use the "*"  and  "?"  wildcarding
484           operators to match multiple names.
486       ·   The  second part is optional and begins with the "@" character.  It
487           is followed by the path to the source file containing the function,
488           which may include a wildcard pattern, such as mm/slab*.  If it does
489           not match as is, an implicit "*/" is optionally  added  before  the
490           pattern, so that a script need only name the last few components of
491           a possibly long source directory path.
493       ·   Finally, the third part is optional if the file name part was  giv‐
494           en, and identifies the line number in the source file preceded by a
495           ":" or a "+".  The line number is assumed to be  an  absolute  line
496           number if preceded by a ":", or relative to the declaration line of
497           the function if preceded by a "+".  All the lines in  the  function
498           can  be  matched  with  ":*".   A range of lines x through y can be
499           matched with ":x-y". Ranges and specific lines can be  mixed  using
500           commas, e.g. ":x,y-z".
502       As an alternative, PATTERN may be a numeric constant, indicating an ad‐
503       dress.  Such an address may be found from symbol tables of  the  appro‐
504       priate  kernel  /  module  object  file.   It is verified against known
505       statement code boundaries, and will be relocated for use at run time.
507       In guru mode only, absolute kernel-space  addresses  may  be  specified
508       with the ".absolute" suffix.  Such an address is considered already re‐
509       located, as if it came from /proc/kallsyms, so  it  cannot  be  checked
510       against statement/instruction boundaries.
513       Many  of  the  source-level context variables, such as function parame‐
514       ters, locals, globals visible in the compilation unit, may  be  visible
515       to  probe  handlers.   They  may  refer to these variables by prefixing
516       their name with "$" within the scripts.  In addition, a special  syntax
517       allows  limited  traversal  of  structures, pointers, and arrays.  More
518       syntax allows pretty-printing of individual variables or their  groups.
519       See  also  @cast.   Note that variables may be inaccessible due to them
520       being paged out, or  for  a  few  other  reasons.   See  also  man  er‐
521       ror::fault(7stap).
524       $var   refers  to  an in-scope variable "var".  If it's an integer-like
525              type, it will be cast to a 64-bit int for systemtap script  use.
526              String-like  pointers (char *) may be copied to systemtap string
527              values using the kernel_string or user_string functions.
529       @var("varname")
530              an alternative syntax for $varname
532       @var("varname@src/file.c")
533              refers to the global (either file local  or  external)  variable
534              varname defined when the file src/file.c was compiled. The CU in
535              which the variable is resolved is the first CU in the module  of
536              the probe point which matches the given file name at the end and
537              has    the    shortest    file    name    path    (e.g.    given
538              @var("foo@bar/baz.c")  and CUs with file name paths src/sub/mod‐
539              ule/bar/baz.c and src/bar/baz.c the second CU will be chosen  to
540              resolve the (file) global variable foo
542       $var->field traversal via a structure's or a pointer's field.  This
543              generalized  indirection operator may be repeated to follow more
544              levels.  Note that the .  operator is not used for plain  struc‐
545              ture  members,  only -> for both purposes.  (This is because "."
546              is reserved for string concatenation.) Also note that for direct
547              dereferencing of $var pointer {kernel,user}_{char,int,...}($var)
548              should be used. (Refer to stapfuncs(5) for more details.)
550       $return
551              is available in return probes only for functions  that  are  de‐
552              clared  with  a return value, which can be determined using @de‐
553              fined($return).
555       $var[N]
556              indexes into an array.  The index given with a literal number or
557              even an arbitrary numeric expression.
559       A  number  of  operators  exist for such basic context variable expres‐
560       sions:
562       $$vars expands to a character string that is equivalent to
564              sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x",
565                      parm1, ..., parmN, var1, ..., varN)
567              for each variable in scope at the probe point.  Some values  may
568              be printed as =?  if their run-time location cannot be found.
570       $$locals
571              expands to a subset of $$vars for only local variables.
573       $$parms
574              expands to a subset of $$vars for only function parameters.
576       $$return
577              is available in return probes only.  It expands to a string that
578              is equivalent to sprintf("return=%x",  $return)  if  the  probed
579              function has a return value, or else an empty string.
581       & $EXPR
582              expands to the address of the given context variable expression,
583              if it is addressable.
585       @defined($EXPR)
586              expands to 1 or 0 iff the given context variable  expression  is
587              resolvable, for use in conditionals such as
589              @defined($foo->bar) ? $foo->bar : 0
592       $EXPR$ expands to a string with all of $EXPR's members, equivalent to
594              sprintf("{.a=%i, .b=%u, .c={...}, .d=[...]}",
595                       $EXPR->a, $EXPR->b)
598       $EXPR$$
599              expands  to  a string with all of $var's members and submembers,
600              equivalent to
602              sprintf("{.a=%i, .b=%u, .c={.x=%p, .y=%c}, .d=[%i, ...]}",
603                      $EXPR->a, $EXPR->b, $EXPR->c->x, $EXPR->c->y, $EXPR->d[0])
608       For the kernel ".return" probes, only a certain fixed number of returns
609       may  be  outstanding.  The default is a relatively small number, on the
610       order of a few times the number of physical CPUs.   If  many  different
611       threads  concurrently call the same blocking function, such as futex(2)
612       or read(2), this limit could  be  exceeded,  and  skipped  "kretprobes"
613       would be reported by "stap -t".  To work around this, specify a
615              probe FOO.return.maxactive(NNN)
617       suffix,  with  a  large  enough  NNN to cover all expected concurrently
618       blocked threads.  Alternately, use the
620              stap -DKRETACTIVE=NNNN
622       stap command line macro setting to override the default for  all  ".re‐
623       turn" probes.
626       For ".return" probes, context variables other than the "$return" may be
627       accessible, as a convenience for a script programmer wishing to  access
628       function  parameters.   These values are snapshots taken at the time of
629       function entry.  (Local variables within the function are not generally
630       accessible,  since  those variables did not exist in allocated/initial‐
631       ized form at the  snapshot  moment.)   These  entry-snapshot  variables
632       should be accessed via @entry($var).
634       In  addition,  arbitrary  entry-time  expressions can also be saved for
635       ".return" probes using the @entry(expr) operator.  For example, one can
636       compute the elapsed time of a function:
638              probe kernel.function("do_filp_open").return {
639                  println( get_timeofday_us() - @entry(get_timeofday_us()) )
640              }
644       The following table summarizes how values related to a function parame‐
645       ter context variable, a pointer named addr, may be accessed from a .re‐
646       turn probe.
648       at-entry value   past-exit value
650       $addr            not available
651       $addr->x->y      @cast(@entry($addr),"struct zz")->x->y
652       $addr[0]         {kernel,user}_{char,int,...}(& $addr[0])
657       In  absence  of  debugging information, entry & exit points of kernel &
658       module functions can be probed using the  "kprobe"  family  of  probes.
659       However, these do not permit looking up the arguments / local variables
660       of the function.  Following constructs are supported :
662              kprobe.function(FUNCTION)
663              kprobe.function(FUNCTION).call
664              kprobe.function(FUNCTION).return
665              kprobe.module(NAME).function(FUNCTION)
666              kprobe.module(NAME).function(FUNCTION).call
667              kprobe.module(NAME).function(FUNCTION).return
668              kprobe.statement(ADDRESS).absolute
671       Probes of type function are recommended for kernel  functions,  whereas
672       probes  of  type  module  are  recommended for probing functions of the
673       specified module.  In case the absolute address of a kernel  or  module
674       function is known, statement probes can be utilized.
676       Note  that FUNCTION and MODULE names must not contain wildcards, or the
677       probe will not be registered.  Also, statement probes must be run under
678       guru-mode only.
683       Support  for  user-space probing is available for kernels that are con‐
684       figured with the utrace extensions, or have  the  uprobes  facility  in
685       linux  3.5.  (Various kernel build configuration options need to be en‐
686       abled; systemtap will advise if these are missing.)
689       There are several forms.  First, a non-symbolic probe point:
691              process(PID).statement(ADDRESS).absolute
693       is analogous to kernel.statement(ADDRESS).absolute in that both use raw
694       (unverified)  virtual  addresses and provide no $variables.  The target
695       PID parameter must identify a running process, and ADDRESS should iden‐
696       tify  a valid instruction address.  All threads of that process will be
697       probed.
699       Second, non-symbolic user-kernel interface events handled by utrace may
700       be probed:
702              process(PID).begin
703              process("FULLPATH").begin
704              process.begin
705              process(PID).thread.begin
706              process("FULLPATH").thread.begin
707              process.thread.begin
708              process(PID).end
709              process("FULLPATH").end
710              process.end
711              process(PID).thread.end
712              process("FULLPATH").thread.end
713              process.thread.end
714              process(PID).syscall
715              process("FULLPATH").syscall
716              process.syscall
717              process(PID).syscall.return
718              process("FULLPATH").syscall.return
719              process.syscall.return
720              process(PID).insn
721              process("FULLPATH").insn
722              process(PID).insn.block
723              process("FULLPATH").insn.block
727       A  process.begin probe gets called when new process described by PID or
728       FULLPATH gets created.  In addition, it is called once from the context
729       of each preexisting process, at systemtap script startup.  This is use‐
730       ful to track live processes.  A process.thread.begin probe gets  called
731       when  a  new  thread  described  by  PID  or  FULLPATH gets created.  A
732       process.end probe gets called when process described by PID or FULLPATH
733       dies.   A  process.thread.end probe gets called when a thread described
734       by PID or FULLPATH dies.  A process.syscall probe gets  called  when  a
735       thread  described  by  PID or FULLPATH makes a system call.  The system
736       call number is available in the  $syscall  context  variable,  and  the
737       first  6  arguments  of the system call are available in the $argN (ex.
738       $arg1, $arg2, ...) context variable.   A  process.syscall.return  probe
739       gets  called  when a thread described by PID or FULLPATH returns from a
740       system call.  The system call number is available in the $syscall  con‐
741       text  variable, and the return value of the system call is available in
742       the $return context variable.  A process.insn probe gets called for ev‐
743       ery single-stepped instruction of the process described by PID or FULL‐
744       PATH.  A process.insn.block probe gets called for  every  block-stepped
745       instruction of the process described by PID or FULLPATH.
748       If  a  process  probe  is specified without a PID or FULLPATH, all user
749       threads will be probed.  However, if systemtap was invoked with the  -c
750       or  -x options, then process probes are restricted to the process hier‐
751       archy associated with the target process.  If a process  probe  is  un‐
752       specified (i.e. without a PID or FULLPATH), but with the -c option, the
753       PATH of the -c cmd will be heuristically filled into the process  PATH.
754       In  that  case,  only  command parameters are allowed in the -c command
755       (i.e. no command substitution allowed and  no  occurrences  of  any  of
756       these characters: '|&;<>(){}').
759       Third,  symbolic  static  instrumentation  compiled  into  programs and
760       shared libraries may be probed:
762              process("PATH").mark("LABEL")
763              process("PATH").provider("PROVIDER").mark("LABEL")
764              process(PID).mark("LABEL")
765              process(PID).provider("PROVIDER").mark("LABEL")
768       A .mark probe gets called via a static probe which is  defined  in  the
769       application  by  STAP_PROBE1(PROVIDER,LABEL,arg1), which are macros de‐
770       fined in sys/sdt.h.  The PROVIDER is an arbitrary application identifi‐
771       er,  LABEL is the marker site identifier, and arg1 is the integer-typed
772       argument.  STAP_PROBE1 is used for probes with 1 argument,  STAP_PROBE2
773       is  used  for probes with 2 arguments, and so on.  The arguments of the
774       probe are available in the context variables $arg1, $arg2, ...  An  al‐
775       ternative to using the STAP_PROBE macros is to use the dtrace script to
776       create  custom  macros.   Additionally,  the   variables   $$name   and
777       $$provider  are  available  as  parts  of  the  probe  point name.  The
778       sys/sdt.h macro  names  DTRACE_PROBE*  are  available  as  aliases  for
779       STAP_PROBE*.
782       Finally,  full  symbolic source-level probes in user-space programs and
783       shared libraries are supported.  These are  exactly  analogous  to  the
784       symbolic DWARF-based kernel/module probes described above.  They expose
785       the same sorts of context $variables  for  function  parameters,  local
786       variables, and so on.
788              process("PATH").function("NAME")
789              process("PATH").statement("*@FILE.c:123")
790              process("PATH").plt("NAME")
791              process("PATH").library("PATH").plt("NAME")
792              process("PATH").library("PATH").function("NAME")
793              process("PATH").library("PATH").statement("*@FILE.c:123")
794              process("PATH").function("*").return
795              process("PATH").function("myfun").label("foo")
796              process("PATH").function("foo").callee("bar")
797              process("PATH").plt("NAME").return
798              process(PID).function("NAME")
799              process(PID).statement("*@FILE.c:123")
800              process(PID).plt("NAME")
804       Note  that for all process probes, PATH names refer to executables that
805       are searched the same way shells do: relative to the working  directory
806       if they contain a "/" character, otherwise in $PATH.  If PATH names re‐
807       fer to scripts, the actual interpreters (specified in the script in the
808       first line after the #! characters) are probed.
811       Tapset   process   probes   placed   in  the  special  directory  $pre‐
812       fix/share/systemtap/tapset/PATH/ with relative paths  will  have  their
813       process  parameter  prefixed with the location of the tapset. For exam‐
814       ple,
817              process("foo").function("NAME")
820       expands to
822              process("/usr/bin/foo").function("NAME")
826       when placed in $prefix/share/systemtap/tapset/PATH/usr/bin/
829       If PATH is a process component parameter referring to shared  libraries
830       then  all  processes that map it at runtime would be selected for prob‐
831       ing.  If PATH is a library component parameter referring to shared  li‐
832       braries  then  the  process specified by the process component would be
833       selected.  Note that the PATH pattern in a library component  will  al‐
834       ways  apply  to  libraries  statically  determined  to be in use by the
835       process. However, you may also specify the full  path  to  any  library
836       file even if not statically needed by the process.
839       A  .plt  probe will probe functions in the program linkage table corre‐
840       sponding to the rest of the probe point.  .plt can be  specified  as  a
841       shorthand for .plt("*").  The symbol name is available as a $$name con‐
842       text variable; function arguments are not  available,  since  PLTs  are
843       processed without debuginfo.  A .plt.return probe places a probe at the
844       moment after the return from the named function.
847       If the PATH string contains wildcards as in  the  MPATTERN  case,  then
848       standard  globbing  is  performed  to find all matching paths.  In this
849       case, the $PATH environment variable is not used.
852       If systemtap was invoked with the -c or -x options, then process probes
853       are  restricted  to  the  process  hierarchy associated with the target
854       process.
857   JAVA
858       Support for probing Java methods is available using Byteman as a  back‐
859       end.  Byteman  is  an instrumentation tool from the JBoss project which
860       systemtap can use to monitor invocations for a specific method or  line
861       in a Java program.
863       Systemtap  does so by generating a Byteman script listing the probes to
864       instrument and then invoking the Byteman bminstall utility.
866       This Java instrumentation support is currently a prototype feature with
867       major  limitations.   Moreover,  Java  probing  currently does not work
868       across users; the stap script must run (with  appropriate  permissions)
869       under  the  same  user that the Java process being probed. (Thus a stap
870       script under root currently cannot probe Java methods in a non-root-us‐
871       er Java process.)
874       The  first  probe type refers to Java processes by the name of the Java
875       process:
877              java("PNAME").class("CLASSNAME").method("PATTERN")
878              java("PNAME").class("CLASSNAME").method("PATTERN").return
880       The PNAME argument must be a pre-existing jvm pid, and be  identifiable
881       via a jps listing.
883       The  PATTERN  parameter  specifies  the signature of the Java method to
884       probe. The signature must consist of the exact name of the method, fol‐
885       lowed  by  a bracketed list of the types of the arguments, for instance
886       "myMethod(int,double,Foo)". Wildcards are not supported.
888       The probe can be set to trigger at a specific line within the method by
889       appending  a  line number with colon, just as in other types of probes:
890       "myMethod(int,double,Foo):245".
892       The CLASSNAME parameter identifies the Java class  the  method  belongs
893       to,  either  with or without the package qualification. By default, the
894       probe only triggers on descendants of the class that  do  not  override
895       the  method  definition  of  the original class. However, CLASSNAME can
896       take an optional caret prefix, as in ^org.my.MyClass,  which  specifies
897       that  the  probe should also trigger on all descendants of MyClass that
898       override the original method. For instance, every method with signature
899       foo(int) in program org.my.MyApp can be probed at once using
901              java("org.my.MyApp").class("^java.lang.Object").method("foo(int)")
904       The  second  probe type works analogously, but refers to Java processes
905       by PID:
907              java(PID).class("CLASSNAME").method("PATTERN")
908              java(PID).class("CLASSNAME").method("PATTERN").return
910       (PIDs for an already running process can be obtained using  the  jps(1)
911       utility.)
913       Context  variables  defined  within  java  probes include $arg1 through
914       $arg10 (for up to the first 10 arguments of a method),  represented  as
915       character-pointers  for  the  toString()  form of each actual argument.
916       The arg1 through arg10 script variables provide access to these as  or‐
917       dinary strings, fetched via user_string_warn().
919       Prior  to systemtap version 3.1, $arg1 through $arg10 could contain ei‐
920       ther integers or character pointers, depending on the types of the  ob‐
921       jects  being  passed to each particular java method.  This previous be‐
922       haviour may be invoked with the stap --compatible=3.0 flag.
925   PROCFS
926       These probe points allow procfs "files" in  /proc/systemtap/MODNAME  to
927       be  created,  read  and written using a permission that may be modified
928       using the proper umask value. Default permissions  are  0400  for  read
929       probes,  and  0200 for write probes. If both a read and write probe are
930       being used on the same file, a default permission of 0600 will be used.
931       Using procfs.umask(0040).read would result in a 0404 permission set for
932       the file.  (MODNAME is the name of  the  systemtap  module).  The  proc
933       filesystem is a pseudo-filesystem which is used as an interface to ker‐
934       nel data structures. There are several probe point  variants  supported
935       by the translator:
938              procfs("PATH").read
939              procfs("PATH").umask(UMASK).read
940              procfs("PATH").read.maxsize(MAXSIZE)
941              procfs("PATH").umask(UMASK).maxsize(MAXSIZE)
942              procfs("PATH").write
943              procfs("PATH").umask(UMASK).write
944              procfs.read
945              procfs.umask(UMASK).read
946              procfs.read.maxsize(MAXSIZE)
947              procfs.umask(UMASK).read.maxsize(MAXSIZE)
948              procfs.write
949              procfs.umask(UMASK).write
952       PATH  is the file name (relative to /proc/systemtap/MODNAME) to be cre‐
953       ated.  If no PATH is specified (as in the  last  two  variants  above),
954       PATH  defaults to "command". The file name "__stdin" is used internally
955       by systemtap for input probes and should not be  used  as  a  PATH  for
956       procfs probes; see the input probe section below.
958       When  a  user  reads  /proc/systemtap/MODNAME/PATH,  the  corresponding
959       procfs read probe is triggered.  The string data to be read  should  be
960       assigned to a variable named $value, like this:
963              procfs("PATH").read { $value = "100\n" }
966       When a user writes into /proc/systemtap/MODNAME/PATH, the corresponding
967       procfs write probe is triggered.  The data the user wrote is  available
968       in the string variable named $value, like this:
971              procfs("PATH").write { printf("user wrote: %s", $value) }
974       MAXSIZE  is the size of the procfs read buffer.  Specifying MAXSIZE al‐
975       lows larger procfs output.  If no MAXSIZE is specified, the procfs read
976       buffer  defaults to STP_PROCFS_BUFSIZE (which defaults to MAXSTRINGLEN,
977       the maximum length of a string).  If setting the  procfs  read  buffers
978       for  more  than  one  file is needed, it may be easiest to override the
979       STP_PROCFS_BUFSIZE definition.  Here's an example of using MAXSIZE:
982              procfs.read.maxsize(1024) {
983                  $value = "long string..."
984                  $value .= "another long string..."
985                  $value .= "another long string..."
986                  $value .= "another long string..."
987              }
991   INPUT
992       These probe points make input from stdin available to the script during
993       runtime.   The translator currently supports two variants of this fami‐
994       ly:
996              input.char
997              input.line
1000       input.char is triggered each time a character is read from  stdin.  The
1001       current  character  is  available  in  the  string variable named char.
1002       There is no newline buffering; the next character is read from stdin as
1003       soon as it becomes available.
1005       input.line causes all characters read from stdin to be buffered until a
1006       newline is read, at which point the probe will be triggered.  The  cur‐
1007       rent  line of characters (including the newline) is made available in a
1008       string variable named line.  Note that no more than MAXSTRINGLEN  char‐
1009       acters will be buffered. Any additional characters will not be included
1010       in line.
1013       Input probes are aliases for procfs("__stdin").write.  Systemtap recon‐
1014       figures  stdin if the presence of this procfs probe is detected, there‐
1015       fore "__stdin" should not be used as a path argument for procfs probes.
1016       Additionally,  input  probes will not work with the -F and --remote op‐
1017       tions.
1021       These probe points allow observation of network packets using the  net‐
1022       filter  mechanism. A netfilter probe in systemtap corresponds to a net‐
1023       filter hook function in the original netfilter probes API. It is proba‐
1024       bly  more  convenient  to use tapset::netfilter(3stap), which wraps the
1025       primitive netfilter hooks and does the work of extracting useful infor‐
1026       mation from the context variables.
1029       There are several probe point variants supported by the translator:
1032              netfilter.hook("HOOKNAME").pf("PROTOCOL_F")
1033              netfilter.pf("PROTOCOL_F").hook("HOOKNAME")
1034              netfilter.hook("HOOKNAME").pf("PROTOCOL_F").priority("PRIORITY")
1035              netfilter.pf("PROTOCOL_F").hook("HOOKNAME").priority("PRIORITY")
1039       PROTOCOL_F  is  the protocol family to listen for, currently one of NF‐
1043       HOOKNAME is the point, or 'hook', in the protocol stack at which to in‐
1044       tercept  the  packet. The available hook names for each protocol family
1045       are taken from the kernel header files <linux/netfilter_ipv4.h>,  <lin‐
1046       ux/netfilter_ipv6.h>,    <linux/netfilter_arp.h>   and   <linux/netfil‐
1047       ter_bridge.h>. For instance, allowable hook names for NFPROTO_IPV4  are
1052       PRIORITY is an integer priority giving the order  in  which  the  probe
1053       point  should  be  triggered relative to any other netfilter hook func‐
1054       tions which trigger on the same packet. Hook functions execute on  each
1055       packet  in order from smallest priority number to largest priority num‐
1056       ber. If no PRIORITY is specified (as in the first two probe point vari‐
1057       ants above), PRIORITY defaults to "0".
1059       There are a number of predefined priority names of the form NF_IP_PRI_*
1060       and NF_IP6_PRI_* which are defined in the  kernel  header  files  <lin‐
1061       ux/netfilter_ipv4.h>  and  <linux/netfilter_ipv6.h>  respectively.  The
1062       script is permitted to use these instead of specifying an integer  pri‐
1063       ority.  (The  probe points for NFPROTO_ARP and NFPROTO_BRIDGE currently
1064       do not expose any named hook priorities to the script  writer.)   Thus,
1065       allowable ways to specify the priority include:
1068              priority("255")
1069              priority("NF_IP_PRI_SELINUX_LAST")
1072       A script using guru mode is permitted to specify any identifier or num‐
1073       ber as the parameter for hook, pf, and priority. This feature should be
1074       used  with  caution,  as  the parameter is inserted verbatim into the C
1075       code generated by systemtap.
1077       The netfilter probe points define the following context variables:
1079       $hooknum
1080              The hook number.
1082       $skb   The address of the sk_buff struct representing the  packet.  See
1083              <linux/skbuff.h>  for  details on how to use this struct, or al‐
1084              ternatively use the tapset tapset::netfilter(3stap) for easy ac‐
1085              cess to key information.
1088       $in    The  address  of  the net_device struct representing the network
1089              device on which the packet was received (if any). May  be  0  if
1090              the device is unknown or undefined at that stage in the protocol
1091              stack.
1094       $out   The address of the net_device struct  representing  the  network
1095              device  on  which  the packet will be sent (if any). May be 0 if
1096              the device is unknown or undefined at that stage in the protocol
1097              stack.
1100       $verdict
1101              (Guru mode only.) Assigning one of the verdict values defined in
1102              <linux/netfilter.h> to this variable alters the further progress
1103              of the packet through the protocol stack. For instance, the fol‐
1104              lowing guru mode script forces all ipv6 network  packets  to  be
1105              dropped:
1108              probe netfilter.pf("NFPROTO_IPV6").hook("NF_IP6_PRE_ROUTING") {
1109                $verdict = 0 /* nf_drop */
1110              }
1113              For  convenience,  unlike  the  primitive probe points discussed
1114              here, the probes defined in tapset::netfilter(3stap) export  the
1115              lowercase  names  of the verdict constants (e.g. NF_DROP becomes
1116              nf_drop) as local variables.
1120       This family of probe points hooks up to static probing tracepoints  in‐
1121       serted  into the kernel or modules.  As with markers, these tracepoints
1122       are special macro calls inserted by kernel developers to  make  probing
1123       faster and more reliable than with DWARF-based probes, and DWARF debug‐
1124       ging information is not required  to  probe  tracepoints.   Tracepoints
1125       have an extra advantage of more strongly-typed parameters than markers.
1127       Tracepoint probes look like: kernel.trace("name").  The tracepoint name
1128       string, which may contain the usual  wildcard  characters,  is  matched
1129       against  the  names  defined by the kernel developers in the tracepoint
1130       header files. To restrict  the  search  to  specific  subsystems  (e.g.
1131       sched,   ext3,   etc...),  the  following  syntax  can  be  used:  ker‐
1132       nel.trace("system:name").  The tracepoint system string may  also  con‐
1133       tain the usual wildcard characters.
1135       The  handler  associated with a tracepoint-based probe may read the op‐
1136       tional parameters specified at the macro call site.   These  are  named
1137       according  to  the  declaration by the tracepoint author.  For example,
1138       the tracepoint probe  kernel.trace("sched:sched_switch")  provides  the
1139       parameters  $prev and $next.  If the parameter is a complex type, as in
1140       a struct pointer, then a script can access fields with the same  syntax
1141       as DWARF $target variables.  Also, tracepoint parameters cannot be mod‐
1142       ified, but in guru-mode a script may modify fields of parameters.
1144       The subsystem and name of the tracepoint are available in $$system  and
1145       $$name  and a string of name=value pairs for all parameters of the tra‐
1146       cepoint is available in $$vars or $$parms.
1150       This family of probe points hooks up to an older style of static  prob‐
1151       ing  markers inserted into older kernels or modules.  These markers are
1152       special STAP_MARK macro calls inserted by  kernel  developers  to  make
1153       probing  faster  and  more reliable than with DWARF-based probes.  Fur‐
1154       ther, DWARF debugging information is not required to probe markers.
1156       Marker probe points begin with kernel.  The next part names the  marker
1157       itself:  mark("name").   The  marker name string, which may contain the
1158       usual wildcard characters, is matched against the names  given  to  the
1159       marker  macros when the kernel and/or module was compiled.    Optional‐
1160       ly, you can specify format("format").   Specifying  the  marker  format
1161       string  allows  differentiation  between two markers with the same name
1162       but different marker format strings.
1164       The handler associated with a marker-based probe may read the  optional
1165       parameters  specified  at  the  macro call site.  These are named $arg1
1166       through $argNN, where NN is the number of parameters  supplied  by  the
1167       macro.  Number and string parameters are passed in a type-safe manner.
1169       The marker format string associated with a marker is available in $for‐
1170       mat.  And also the marker name string is available in $name.
1174       This family of probes is used to set hardware watchpoints for a given
1175        (global) kernel symbol. The probes take three components as inputs :
1177       1. The virtual address / name of the kernel symbol to be traced is sup‐
1178       plied  as argument to this class of probes. ( Probes for only data seg‐
1179       ment variables are supported. Probing local  variables  of  a  function
1180       cannot be done.)
1182       2. Nature of access to be probed : a.  .write probe gets triggered when
1183       a write happens at the specified address/symbol name.  b.  rw probe  is
1184       triggered when either a read or write happens.
1186       3.   .length (optional) Users have the option of specifying the address
1187       interval to be probed using  "length"  constructs.  The  user-specified
1188       length  gets  approximated  to the closest possible address length that
1189       the architecture can support. If the specified length exceeds the  lim‐
1190       its imposed by architecture, an error message is flagged and probe reg‐
1191       istration fails.  Wherever 'length' is not  specified,  the  translator
1192       requests  a  hardware  breakpoint probe of length 1. It should be noted
1193       that the "length" construct is not valid with symbol names.
1195       Following constructs are supported :
1197              probe kernel.data(ADDRESS).write
1198              probe kernel.data(ADDRESS).rw
1199              probe kernel.data(ADDRESS).length(LEN).write
1200              probe kernel.data(ADDRESS).length(LEN).rw
1201              probe kernel.data("SYMBOL_NAME").write
1202              probe kernel.data("SYMBOL_NAME").rw
1205       This set of probes make use of the debug registers  of  the  processor,
1206       which  is  a  scarce  resource.  (4  on x86 , 1 on powerpc ) The script
1207       translation flags a warning if a user requests more hardware breakpoint
1208       probes  than the limits set by architecture. For example,a pass-2 warn‐
1209       ing is flashed when an input  script  requests  5  hardware  breakpoint
1210       probes  on an x86 system while x86 architecture supports a maximum of 4
1211       breakpoints.  Users are cautioned to set probes judiciously.
1214   PERF
1215       This family of probe points interfaces to the kernel "perf  event"  in‐
1216       frastructure for controlling hardware performance counters.  The events
1217       being attached to are described by the "type", "config" fields  of  the
1218       perf_event_attr  structure,  and are sampled at an interval governed by
1219       the "sample_period" and "sample_freq" fields.
1221       These fields are made available to systemtap scripts using the  follow‐
1222       ing syntax:
1224              probe perf.type(NN).config(MM).sample(XX)
1225              probe perf.type(NN).config(MM).hz(XX)
1226              probe perf.type(NN).config(MM)
1227              probe perf.type(NN).config(MM).process("PROC")
1228              probe perf.type(NN).config(MM).counter("COUNTER")
1229              probe perf.type(NN).config(MM).process("PROC").counter("NAME")
1231       The systemtap probe handler is called once per XX increments of the un‐
1232       derlying performance counter when using the .sample field or at a  fre‐
1233       quency  in  hertz when using the .hz field. When not specified, the de‐
1234       fault behavior is to sample at a count of 1000000.  The range of  valid
1235       type/config  is described by the perf_event_open(2) system call, and/or
1236       the linux/perf_event.h file.  Invalid combinations or  exhausted  hard‐
1237       ware  counter resources result in errors during systemtap script start‐
1238       up.  Systemtap does not sanity-check the values: it merely passes  them
1239       through  to  the kernel for error- and safety-checking.  By default the
1240       perf event probe is systemwide unless .process is specified, which will
1241       bind  the  probe to a specific task.  If the name is omitted then it is
1242       inferred from the stap -c argument.   A perf event can be read  on  de‐
1243       mand  using  .counter.   The body of the perf probe handler will not be
1244       invoked for a .counter probe; instead, the counter is read  in  a  user
1245       space probe via:
1247          process("PROC").statement("func@file") {stat <<< @perf("NAME")}
1251   PYTHON
1252       Support  for  probing  python 2 and python 3 function is available with
1253       the help of an extra python support module. Note that the debuginfo for
1254       the  version of python being probed is required. To run a python script
1255       with the extra python support module you'd add the '-m  HelperSDT'  op‐
1256       tion to your python command, like this:
1258              stap foo.stp -c "python -m HelperSDT foo.py"
1260       Python probes look like the following:
1262              python2.module("MPATTERN").function("PATTERN")
1263              python2.module("MPATTERN").function("PATTERN").call
1264              python2.module("MPATTERN").function("PATTERN").return
1265              python3.module("MPATTERN").function("PATTERN")
1266              python3.module("MPATTERN").function("PATTERN").call
1267              python3.module("MPATTERN").function("PATTERN").return
1269       The  list  above includes multiple variants and modifiers which provide
1270       additional functionality or filters. They are:
1272              .function
1273                     Places a probe at the beginning of the named function  by
1274                     default,  unless  modified  by  PATTERN.  Parameters  are
1275                     available as context variables.
1277              .call  Places a probe at the beginning of  the  named  function.
1278                     Parameters are available as context variables.
1280              .return
1281                     Places  a  probe at the moment before the return from the
1282                     named function. Parameters and local/global python  vari‐
1283                     ables are available as context variables.
1285       PATTERN  stands  for  a string literal that aims to identify a point in
1286       the python program.  It is made up of three parts:
1288       ·   The first part is the name of a  function  (e.g.  "foo")  or  class
1289           method  (e.g.  "bar.baz").  This part may use the "*" and "?" wild‐
1290           carding operators to match multiple names.
1292       ·   The second part is optional and begins with the "@" character.   It
1293           is followed by the path to the source file containing the function,
1294           which may include a wildcard pattern. The python path  is  searched
1295           for a matching filename.
1297       ·   Finally,  the third part is optional if the file name part was giv‐
1298           en, and identifies the line number in the source file preceded by a
1299           ":"  or  a  "+".  The line number is assumed to be an absolute line
1300           number if preceded by a ":", or relative to the declaration line of
1301           the  function  if preceded by a "+".  All the lines in the function
1302           can be matched with ":*".  A range of lines  x  through  y  can  be
1303           matched  with  ":x-y". Ranges and specific lines can be mixed using
1304           commas, e.g. ":x,y-z".
1306       In the above list of probe points, MPATTERN stands for a python  module
1307       or  script name that names the python module of interest. This part may
1308       use the "*" and "?" wildcarding operators to match multiple names.  The
1309       python path is searched for a matching filename.


1314       Here are some example probe points, defining the associated events.
1316       begin, end, end
1317              refers  to  the  startup and normal shutdown of the session.  In
1318              this case, the handler would run once during startup  and  twice
1319              during shutdown.
1321       timer.jiffies(1000).randomize(200)
1322              refers to a periodic interrupt, every 1000 +/- 200 jiffies.
1324       kernel.function("*init*"), kernel.function("*exit*")
1325              refers  to  all  kernel  functions  with "init" or "exit" in the
1326              name.
1328       kernel.function("*@kernel/time.c:240")
1329              refers to any functions within  the  "kernel/time.c"  file  that
1330              span  line 240.   Note that this is not a probe at the statement
1331              at that line number.  Use the kernel.statement probe instead.
1333       kernel.trace("sched_*")
1334              refers to all scheduler-related (really,  prefixed)  tracepoints
1335              in the kernel.
1337       kernel.mark("getuid")
1338              refers  to  an obsolete STAP_MARK(getuid, ...) macro call in the
1339              kernel.
1341       module("usb*").function("*sync*").return
1342              refers to the moment of return from all functions with "sync" in
1343              the name in any of the USB drivers.
1345       kernel.statement(0xc0044852)
1346              refers  to  the  first  byte of the statement whose compiled in‐
1347              structions include the given address in the kernel.
1349       kernel.statement("*@kernel/time.c:296")
1350              refers to the statement of line 296 within "kernel/time.c".
1352       kernel.statement("bio_init@fs/bio.c+3")
1353              refers to the statement at line bio_init+3 within "fs/bio.c".
1355       kernel.data("pid_max").write
1356              refers to a hardware breakpoint of type "write" set on pid_max
1358       syscall.*.return
1359              refers to the group of probe aliases with any name in the  third
1360              position


1364       stap(1),
1365       probe::*(3stap),
1366       tapset::*(3stap)
1371                                                             STAPPROBES(3stap)