[
This guide is a comprehensive reference of SystemTap’s language constructs and syntax. The contentsborrow heavily from existing SystemTap documentation found in manual pages and the tutorial. Thepresentation of information here provides the reader with a single place to find language syntax andrecommended usage. In order to successfully use this guide, you should be familiar with the generaltheory and operation of SystemTap. If you are new to SystemTap, you will find the tutorial to be anexcellent place to start learning. For detailed information about tapsets, see the manual pages providedwith the distribution. For information about the entire collection of SystemTap reference material, seeSection SystemTap provides infrastructure to simplify the gathering of information about a running Linux kernel so that itmay be further analyzed. This analysis assists in identifying the underlying cause of a performanceor functional problem. SystemTap was designed to eliminate the need for a developer to go throughthe tedious instrument, recompile, install, and reboot sequence normally required to collect this kindof data. To do this, it provides a simple command-line interface and scripting language for writinginstrumentation for both kernel and user space. With SystemTap, developers, system administrators, andusers can easily write scripts that gather and manipulate system data that is otherwise unavailablefrom standard Linux tools. Users of SystemTap will find it to be a significant improvement over oldermethods. SystemTap’s language is strictly typed, declaration free, procedural, and inspired by dtrace and awk.Source code points or events in the kernel are associated with handlers, which are subroutines that areexecuted synchronously. These probes are conceptually similar to ”breakpoint command lists” in the GDBdebugger. There are two main outermost constructs: probes and functions. Within these, statements and expressions use C-likeoperator syntax and precedence. Following are some example scripts that illustrate the basic operation of SystemTap. For moreexamples, see the examples/small_demos/ directory in the source directory, the SystemTap wikiat The following code examples demonstrate SystemTap syntax and control structures. This prints: Note that all variable types are inferred, and that all locals and globals are initialized. Integers are set to 0 andstrings are set to the empty string. This prints: This prints: Any larger number input to the function may exceed the MAXACTION or MAXNESTING limits, which will becaught at run time and result in an error. For more about limits see Section The stap program is the front-end to the SystemTap tool. It accepts probing instructions written in its scriptinglanguage, translates those instructions into C code, compiles this C code, and loads the resulting kernel module intoa running Linux kernel to perform the requested system trace or probe functions. You can supply the script in anamed file, from standard input, or from the command line. The SystemTap script runs until one of the followingconditions occurs: The user interrupts the script with a CTRL-C. The script executes the exit() function. The script encounters a sufficient number of soft errors. The monitored command started with the stap program’s The stap command does the following: Translates the script Generates and compiles a kernel module Inserts the module; output to stap’s stdout CTRL-C unloads the module and terminates stap For a full list of options to the stap command, see the stap(1) manual page. SystemTap is an administrative tool. It exposes kernel internal data structures and potentially private userinformation. It requires root privileges to actually run the kernel objects it builds using the staprun is a part of the SystemTap package, dedicated to module loading and unloading and kernel-to-user datatransfer. Since staprun does not perform any additional security checks on the kernel objects it is given, do not giveelevated privileges via sudo to untrusted users. The translator asserts certain safety constraints. It ensures that no handler routine can run for too long, allocatememory, perform unsafe operations, or unintentionally interfere with the kernel. Use of script global variables islocked to protect against manipulation by concurrent probe handlers. Use of The resource use limits are set by macros in the generated C code. These may be overridden with the -D flag. Thefollowing list describes a selection of these macros: If something goes wrong with stap or staprun after a probe has started running, you may safely kill both userprocesses, and remove the active probe kernel module with the rmmod command. Any pending trace messages maybe lost. [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
global odds, evens probe begin { # "no" and "ne" are local integers for (i = 0; i < 10; i++) { if (i % 2) odds [no++] = i else evens [ne++] = i } delete odds[2] delete evens[3] exit() } probe end { foreach (x+ in odds) printf ("odds[%d] = %d", x, odds[x]) foreach (x in evens-) printf ("evens[%d] = %d", x, evens[x]) } odds[0] = 1 odds[1] = 3 odds[3] = 7 odds[4] = 9 evens[4] = 8 evens[2] = 4 evens[1] = 2 evens[0] = 0
1.4.2 Primes between 0 and 49
function isprime (x) { if (x < 2) return 0 for (i = 2; i < x; i++) { if (x % i == 0) return 0 if (i * i > x) break } return 1 } probe begin { for (i = 0; i < 50; i++) if (isprime (i)) printf("%d\n", i) exit() } 2 3 5 7 11 13 17 19 23 29 31 37 41 43 47
1.4.3 Recursive functions
function fibonacci(i) { if (i < 1) error ("bad number") if (i == 1) return 1 if (i == 2) return 2 return fibonacci (i-1) + fibonacci (i-2) } probe begin { printf ("11th fibonacci number: %d", fibonacci (11)) exit () } 11th fibonacci number: 118
1.5 The stap command
1.6 Safety and security