Red Hat Enterprise Linux 5

SystemTap Language Reference

A guide to the constructs and syntax used in SystemTap scripts

Edition 1

Logo

IBM Documentation

Robb Romans

IBM ID Team

Legal Notice

Copyright © 2009 Red Hat Inc., Copyright © 2009 IBM Corp., Copyright © 2009 Intel Corporation.
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 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.
Red Hat, Red Hat Enterprise Linux, and the Shadowman logo are trademarks of Red Hat, Inc., registered in the U.S. and other countries. Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

Abstract

The SystemTap Language Reference is a comprehensive reference of the language constructs and syntax used in SystemTap scripts. It is suitable for users who have intermediate to advanced knowledge of SystemTap.
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. Unused alias variables
3.3. Variables
3.4. Auxiliary functions
3.5. Embedded C
3.6. Embedded C functions
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.2. Built-in probe point types (DWARF probes)
4.2.1. kernel.function, module().function
4.2.2. kernel.statement, module().statement
4.3. DWARF-less probing
4.4. Marker probes
4.5. Timer probes
4.6. Return probes
4.7. Special probe points
4.7.1. begin
4.7.2. end
4.7.3. begin and end probe sequence
4.7.4. never
4.8. Probes to monitor performance
4.8.1. $counter
4.8.2. read_counter
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. Binary numeric or string comparison operators
5.6.7. Ternary operator
5.6.8. Grouping operator
5.6.9. Function call
5.6.10. $ptr->member
5.6.11. <value> in <array_name>
5.6.12. [ <value>, … ] in <array_name>
5.7. Literals passed in from the stap command line
5.7.1. $1 … $<NN> for integers
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 kernel version: kernel_v, kernel_vr
5.8.3. Conditions based on architecture: arch
5.8.4. True and False Tokens
6. Statement types
6.1. break and continue
6.2. delete
6.3. do
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. Iteration, foreach
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
9. Predefined functions
9.1. Output functions
9.1.1. error
9.1.2. log
9.1.3. print
9.1.4. printf
9.1.5. printd
9.1.6. printdln
9.1.7. println
9.1.8. sprint
9.1.9. sprintf
9.1.10. system
9.1.11. warn
9.2. Context at the probe point
9.2.1. backtrace
9.2.2. caller
9.2.3. caller_addr
9.2.4. cpu
9.2.5. egid
9.2.6. euid
9.2.7. execname
9.2.8. gid
9.2.9. is_return
9.2.10. pexecname
9.2.11. pid
9.2.12. ppid
9.2.13. tid
9.2.14. uid
9.2.15. print_backtrace
9.2.16. print_regs
9.2.17. print_stack
9.2.18. stack_size
9.2.19. stack_unused
9.2.20. stack_used
9.2.21. stp_pid
9.2.22. target
9.3. Task data
9.3.1. task_cpu
9.3.2. task_current
9.3.3. task_egid
9.3.4. task_execname
9.3.5. task_euid
9.3.6. task_gid
9.3.7. task_nice
9.3.8. task_parent
9.3.9. task_pid
9.3.10. task_prio
9.3.11. task_state
9.3.12. task_tid
9.3.13. task_uid
9.3.14. task_open_file_handles
9.3.15. task_max_file_handles
9.4. Accessing string data at a probe point
9.4.1. kernel_string
9.4.2. user_string
9.4.3. user_string2
9.4.4. user_string_warn
9.4.5. user_string_quoted
9.5. Initializing queue statistics
9.5.1. qs_wait
9.5.2. qs_run
9.5.3. qs_done
9.6. Using queue statistics
9.6.1. qsq_blocked
9.6.2. qsq_print
9.6.3. qsq_service_time
9.6.4. qsq_start
9.6.5. qsq_throughput
9.6.6. qsq_utilization
9.6.7. qsq_wait_queue_length
9.6.8. qsq_wait_time
9.6.9. A queue example
9.7. Probe point identification
9.7.1. pp
9.7.2. probefunc
9.7.3. probemod
9.8. Formatting functions
9.8.1. ctime
9.8.2. errno_str
9.8.3. returnstr
9.8.4. thread_indent
9.8.5. thread_timestamp
9.9. String functions
9.9.1. isinstr
9.9.2. strlen
9.9.3. strtol
9.9.4. substr
9.9.5. text_str
9.9.6. text_strn
9.9.7. tokenize
9.10. Timestamps
9.10.1. get_cycles
9.10.2. gettimeofday_ms
9.10.3. gettimeofday_ns
9.10.4. gettimeofday_s
9.10.5. gettimeofday_us
9.11. Miscellaneous tapset functions
9.11.1. addr_to_node
9.11.2. exit
9.11.3. system
10. For Further Reference
Index