Contents

1 SystemTap overview
 1.1 About this guide
 1.2 Reasons to use SystemTap
 1.3 Event-action language
 1.4 Sample SystemTap scripts
  1.4.1 Basic SystemTap syntax and control structures
  1.4.2 Primes between 0 and 49
  1.4.3 Recursive functions
 1.5 The stap command
 1.6 Safety and security
2 Types of SystemTap scripts
 2.1 Probe scripts
 2.2 Tapset scripts
3 Components of a SystemTap script
 3.1 Probe definitions
 3.2 Probe aliases
  3.2.1 Prologue-style aliases (=)
  3.2.2 Epilogue-style aliases (+=)
  3.2.3 Probe alias usage
  3.2.4 Alias suffixes
  3.2.5 Alias suffixes and wildcards
 3.3 Variables
  3.3.1 Unused variables
 3.4 Auxiliary functions
 3.5 Embedded C
 3.6 Embedded C functions
 3.7 Embedded C pragma comments
 3.8 Accessing script level global variables
4 Probe points
 4.1 General syntax
  4.1.1 Prefixes
  4.1.2 Suffixes
  4.1.3 Wildcarded file names, function names
  4.1.4 Optional probe points
  4.1.5 Brace expansion
 4.2 Built-in probe point types (DWARF probes)
  4.2.1 kernel.function, module().function
  4.2.2 kernel.statement, module().statement
 4.3 Function return probes
 4.4 DWARF-less probing
 4.5 Userspace probing
  4.5.1 Begin/end variants
  4.5.2 Syscall variants
  4.5.3 Function/statement variants
  4.5.4 Absolute variant
  4.5.5 Process probe paths
  4.5.6 Target process mode
  4.5.7 Instruction probes
  4.5.8 Static userspace probing
 4.6 Java probes
 4.7 PROCFS probes
 4.8 Marker probes
 4.9 Tracepoints
 4.10 Syscall probes
 4.11 Timer probes
 4.12 Special probe points
  4.12.1 begin
  4.12.2 end
  4.12.3 error
  4.12.4 begin, end, and error probe sequence
  4.12.5 never
5 Language elements
 5.1 Identifiers
 5.2 Data types
  5.2.1 Literals
  5.2.2 Integers
  5.2.3 Strings
  5.2.4 Associative arrays
  5.2.5 Statistics
 5.3 Semicolons
 5.4 Comments
 5.5 Whitespace
 5.6 Expressions
  5.6.1 Binary numeric operators
  5.6.2 Binary string operators
  5.6.3 Numeric assignment operators
  5.6.4 String assignment operators
  5.6.5 Unary numeric operators
  5.6.6 Numeric & string comparison, regular expression matching operators
  5.6.7 Ternary operator
  5.6.8 Grouping operator
  5.6.9 Function call
  5.6.10 $ptr->member
  5.6.11 Pointer typecasting
  5.6.12 <value>in <array_name>
  5.6.13 [ <value>, ... ] in <array_name>
 5.7 Literals passed in from the stap command line
  5.7.1 $1 … $<NN>for literal pasting
  5.7.2 @1 … @<NN>for strings
  5.7.3 Examples
 5.8 Conditional compilation
  5.8.1 Conditions
  5.8.2 Conditions based on available target variables
  5.8.3 Conditions based on kernel version: kernel_v, kernel_vr
  5.8.4 Conditions based on architecture: arch
  5.8.5 Conditions based on privilege level: systemtap_privilege
  5.8.6 True and False Tokens
 5.9 Preprocessor macros
  5.9.1 Local macros
  5.9.2 Library macros
6 Statement types
 6.1 break and continue
 6.2 try/catch
 6.3 delete
 6.4 EXP (expression)
 6.5 for
 6.6 foreach
 6.7 if
 6.8 next
 6.9 ; (null statement)
 6.10 return
 6.11 {} (statement block)
 6.12 while
7 Associative arrays
 7.1 Examples
 7.2 Types of values
 7.3 Array capacity
 7.4 Array wrapping
 7.5 Iteration, foreach
 7.6 Deletion
8 Statistics (aggregates)
 8.1 The aggregation (<<<) operator
 8.2 Extraction functions
 8.3 Integer extractors
  8.3.1 @count(s)
  8.3.2 @sum(s)
  8.3.3 @min(s)
  8.3.4 @max(s)
  8.3.5 @avg(s)
 8.4 Histogram extractors
  8.4.1 @hist_linear
  8.4.2 @hist_log
 8.5 Deletion
9 Formatted output
 9.1 print
 9.2 printf
 9.3 printd
 9.4 printdln
 9.5 println
 9.6 sprint
 9.7 sprintf
10 Tapset-defined functions
11 For Further Reference
Index