SystemTap Language Reference


March 1, 2021

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

Copyright 2007-2013 Red Hat Inc.
Copyright 2007-2009 IBM Corp.
Copyright 2007 Intel Corporation.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant 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 by writing 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