SystemTap Language Reference

This document was derived from other documents contributed to the SystemTap project by employees of Red Hat,IBM and Intel.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU FreeDocumentation License, Version 1.2 or any later version published by the Free Software Foundation; with noInvariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

The GNU Free Documentation License is available from

http://www.gnu.org/licenses/fdl_html or bywriting to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,USA.

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.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.3 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.2 Built-in probe point types (DWARF probes)
4.3 Function return probes
4.4 DWARF-less probing
4.5 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
5 Language elements
5.1 Identifiers
5.2 Data types
5.3 Semicolons
5.4 Comments
5.5 Whitespace
5.6 Expressions
5.7 Literals passed in from the stap command line
5.8 Conditional compilation
5.9 Preprocessor 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.4 Histogram extractors
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