2 .TH STAP 1 @DATE@ "Red Hat"
4 stap \- systemtap script translator/driver
71 program is the front-end to the Systemtap tool. It accepts probing
72 instructions (written in a simple scripting language), translates
73 those instructions into C code, compiles this C code, and loads the
74 resulting kernel module into a running Linux kernel to perform the
75 requested system trace/probe functions. You can supply the script in
76 a named file, from standard input, or from the command line. The
77 program runs until it is interrupted by the user, or if the script
78 voluntarily invokes the
80 function, or by sufficient number of soft errors.
82 The language, which is described in a later section, is strictly typed,
83 declaration free, procedural, and inspired by
85 It allows source code points or events in the kernel to be associated
86 with handlers, which are subroutines that are executed synchronously. It is
87 somewhat similar conceptually to "breakpoint command lists" in the
91 This manual corresponds to version @VERSION@.
94 The systemtap translator supports the following options. Any other option
95 prints a list of supported options.
101 Show version message.
104 Stop after pass NUM. The passes are numbered 1-5: parse, elaborate,
105 translate, compile, run. See the
110 Increase verbosity for all passes. Produce a larger volume of
111 informative (?) output each time option repeated.
114 Increase verbosity on a per-pass basis. For example, "\-\-vp\ 002"
115 adds 2 units of verbosity to pass 3 only. The combination "\-v\ \-\-vp\ 00004"
116 adds 1 unit of verbosity for all passes, and 4 more for pass 5.
119 Keep the temporary directory after all processing. This may be useful
120 in order to examine the generated C code, or to reuse the compiled
124 Guru mode. Enable parsing of unsafe expert-level constructs like
128 Prologue-searching mode. Activate heuristics to work around incorrect
129 debugging information for $target variables.
132 Unoptimized mode. Disable unused code elision during elaboration.
135 Suppressed warnings mode. Disable warning messages for elided code in user script.
138 Use bulk mode (percpu files) for kernel-to-user data transfer.
141 Collect timing information on the number of times probe executes
142 and average amount of time spent in each probe.
145 Use NUM megabyte buffers for kernel-to-user data transfer. On a
146 multiprocessor in bulk mode, this is a per-processor amount.
149 Add the given directory to the tapset search directory. See the
150 description of pass 2 for details.
152 .BI \-D " NAME=VALUE"
153 Add the given C preprocessor directive to the module Makefile. These can
154 be used to override limit parameters described below.
157 Look for the systemtap runtime sources in the given directory.
160 Build for kernel in given build tree. Can also be set with the
162 environment variable.
165 Build for kernel in build tree
166 .BR /lib/modules/RELEASE/build .
167 Can also be set with the
169 environment variable.
172 Use the given name for the generated kernel object module, instead
173 of a unique randomized name. The generated kernel object module is
174 copied to the current directory.
177 Add symbol/unwind information for the given module into the kernel object
178 module. This may enable symbolic tracebacks from those modules/programs,
179 even if they do not have an explicit probe placed into them.
182 Send standard output to named file. In bulk mode, percpu files will
183 start with FILE_ (FILE_cpu with -F) followed by the cpu number.
184 This supports strftime(3) formats for FILE.
187 Start the probes, run CMD, and exit when CMD finishes.
190 Sets target() to PID. This allows scripts to be written that filter on
194 Instead of running a probe script, just list all available probe
195 points matching the given pattern. The pattern may include wildcards
199 Similar to "-l", but list probe points and script-level local variables.
202 Without -o option, load module and start probes, then detach from the module
203 leaving the probes running.
204 With -o option, run staprun in background as a daemon and show its pid.
207 Sets the maximum size of output file and the maximum number of output files.
208 If the size of output file will exceed
210 , systemtap switches output file to the next file. And if the number of
213 , systemtap removes the oldest output file. You can omit the second argument.
216 For names and addresses of functions to probe,
217 consult the symbol tables in the kernel and modules.
218 This can be useful if your kernel and/or modules were compiled
219 without debugging information, or the function you want to probe
220 is in an assembly-language file built without debugging information.
222 .B "MAKING DO WITH SYMBOL TABLES"
223 section for more information.
226 For names and addresses of kernel functions to probe,
227 consult the symbol table in the indicated text file.
228 The default is /boot/System.map-VERSION.
229 The contents of this file should be in the form of the default output from
231 Only symbols of type T or t are used.
232 If you specify /proc/kallsyms or some other file in that format,
233 where lines for module symbols contain a fourth column,
234 reading of the symbol table stops with the first module symbol
235 (which should be right after the last kernel symbol).
238 the symbol table in each module's .ko file will also be consulted.
240 .B "MAKING DO WITH SYMBOL TABLES"
241 section for more information.
243 .B \-\-ignore\-vmlinux
244 For testing, act as though neither the uncompressed kernel (vmlinux)
245 nor the kernel debugging information can be found.
248 For testing, act as though vmlinux and modules lack debugging information.
251 Ignore out of context variables and substitute with literal 0.
255 Any additional arguments on the command line are passed to the script
256 parser for substitution. See below.
260 The systemtap script language resembles
262 There are two main outermost constructs: probes and functions. Within
263 these, statements and expressions use C-like operator syntax and
267 Whitespace is ignored. Three forms of comments are supported:
270 .BR # " ... shell style, to the end of line, except for $# and @#"
272 .BR // " ... C++ style, to the end of line"
274 .BR /* " ... C style ... " */
276 Literals are either strings enclosed in double-quotes (passing through
277 the usual C escape codes with backslashes), or integers (in decimal,
278 hexadecimal, or octal, using the same notation as in C). All strings
279 are limited in length to some reasonable value (a few hundred bytes).
280 Integers are 64-bit signed quantities, although the parser also accepts
281 (and wraps around) values above positive 2**63.
283 In addition, script arguments given at the end of the command line may
286 for insertion unquoted,
288 for insertion as a string literal. The number of arguments may be accessed
291 (as an unquoted number) or through
293 (as a quoted number). These may be used at any place a token may begin,
294 including within the preprocessing stage. Reference to an argument
295 number beyond what was actually given is an error.
298 A simple conditional preprocessing stage is run as a part of parsing.
299 The general form is similar to the
300 .RB cond " ? " exp1 " : " exp2
303 .BR %( " CONDITION " %? " TRUE-TOKENS " %)
304 .BR %( " CONDITION " %? " TRUE-TOKENS " %: " FALSE-TOKENS " %)
306 The CONDITION is either an expression whose format is determined by its
307 first keyword, or a string literals comparison or a numeric literals
310 If the first part is the identifier
311 .BR kernel_vr " or " kernel_v
312 to refer to the kernel version number, with ("2.6.13\-1.322FC3smp") or
313 without ("2.6.13") the release code suffix, then
314 the second part is one of the six standard numeric comparison operators
315 .BR < ", " <= ", " == ", " != ", " > ", and " >= ,
316 and the third part is a string literal that contains an RPM-style
317 version-release value. The condition is deemed satisfied if the
318 version of the target kernel (as optionally overridden by the
320 option) compares to the given version string. The comparison is
321 performed by the glibc function
323 As a special case, if the operator is for simple equality
327 and the third part contains any wildcard characters
328 .RB ( * " or " ? " or " [ "),"
329 then the expression is treated as a wildcard (mis)match as evaluated
333 If, on the other hand, the first part is the identifier
335 to refer to the processor architecture, then the second part
336 then the second part is one of the two string comparison operators
338 and the third part is a string literal for matching it. This
339 comparison is a wildcard (mis)match.
341 Otherwise, the CONDITION is expected to be a comparison between two string
342 literals or two numeric literals. In this case, the arguments are the only
345 The TRUE-TOKENS and FALSE-TOKENS are zero or more general parser
346 tokens (possibly including nested preprocessor conditionals), and are
347 pasted into the input stream if the condition is true or false. For
348 example, the following code induces a parse error unless the target
349 kernel version is newer than 2.6.5:
351 %( kernel_v <= "2.6.5" %? **ERROR** %) # invalid token sequence
353 The following code might adapt to hypothetical kernel version drift:
355 probe kernel.function (
356 %( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
357 %( kernel_vr == "2.6.13*smp" %? "do_page_fault" %:
362 probe syscall.vliw = kernel.function("vliw_widget") {}
367 Identifiers for variables and functions are an alphanumeric sequence,
368 and may include "_" and "$" characters. They may not start with a
369 plain digit, as in C. Each variable is by default local to the probe
370 or function statement block within which it is mentioned, and therefore
371 its scope and lifetime is limited to a particular probe or function
373 .\" XXX add statistics type here once it's supported
375 Scalar variables are implicitly typed as either string or integer.
376 Associative arrays also have a string or integer value, and a
377 a tuple of strings and/or integers serving as a key. Here are a
378 few basic expressions.
382 array1 [pid()] = "name" # single numeric key
383 array2 ["foo",4,i++] += 5 # vector of string/num/num keys
384 if (["hello",5,4] in array2) println ("yes") # membership test
387 The translator performs
389 on all identifiers, including array indexes and function parameters.
390 Inconsistent type-related use of identifiers signals an error.
392 Variables may be declared global, so that they are shared amongst all
393 probes and live as long as the entire systemtap session. There is one
394 namespace for all global variables, regardless of which script file
395 they are found within. A global declaration may be written at the
396 outermost level anywhere, not within a block of code. Global
397 variables which are written but never read will be displayed
398 automatically at session shutdown. The following
399 declaration marks a few variables as global. The translator will
400 infer for each its value type, and if it is used as an array, its key
401 types. Optionally, scalar globals may be initialized with a string
404 .BR global " var1" , " var2" , " var3=4"
407 Arrays are limited in size by the MAXMAPENTRIES variable -- see the
408 .B SAFETY AND SECURITY
409 section for details. Optionally, global arrays may be declared with a
410 maximum size in brackets, overriding MAXMAPENTRIES for that array only.
411 Note that this doesn't indicate the type of keys for the array, just the
414 .BR global " tiny_array[10]" , " normal_array" , " big_array[50000]"
416 .\" XXX add statistics type here once it's supported
419 Statements enable procedural control flow. They may occur within
420 functions and probe handlers. The total number of statements executed
421 in response to any single probe event is limited to some number
422 defined by a macro in the translated C code, and is in the
423 neighbourhood of 1000.
426 Execute the string- or integer-valued expression and throw away
429 .BR { " STMT1 STMT2 ... " }
430 Execute each statement in sequence in this block. Note that
431 separators or terminators are generally not necessary between statements.
434 Null statement, do nothing. It is useful as an optional separator between
435 statements to improve syntax-error detection and to handle certain
438 .BR if " (EXP) STMT1 [ " else " STMT2 ]"
439 Compare integer-valued EXP to zero. Execute the first (non-zero)
440 or second STMT (zero).
442 .BR while " (EXP) STMT"
443 While integer-valued EXP evaluates to non-zero, execute STMT.
445 .BR for " (EXP1; EXP2; EXP3) STMT"
446 Execute EXP1 as initialization. While EXP2 is non-zero, execute
447 STMT, then the iteration expression EXP3.
449 .BR foreach " (VAR " in " ARRAY [ "limit " EXP ]) STMT"
450 Loop over each element of the named global array, assigning current
451 key to VAR. The array may not be modified within the statement.
454 operator after the VAR or the ARRAY identifier, the iteration will
455 proceed in a sorted order, by ascending or descending index or value.
458 keyword limits the number of loop iterations to EXP times. EXP is
459 evaluted once at the beginning of the loop.
461 .BR foreach " ([VAR1, VAR2, ...] " in " ARRAY [ "limit " EXP ]) STMT"
462 Same as above, used when the array is indexed with a tuple of keys.
463 A sorting suffix may be used on at most one VAR or ARRAY identifier.
465 .BR break ", " continue
466 Exit or iterate the innermost nesting loop
467 .RB ( while " or " for " or " foreach )
471 Return EXP value from enclosing function. If the function's value is
472 not taken anywhere, then a return statement is not needed, and the
473 function will have a special "unknown" type with no return value.
476 Return now from enclosing probe handler.
478 .BR delete " ARRAY[INDEX1, INDEX2, ...]"
479 Remove from ARRAY the element specified by the index tuple. The value will no
480 longer be available, and subsequent iterations will not report the element.
481 It is not an error to delete an element that does not exist.
484 Remove all elements from ARRAY.
487 Removes the value of SCALAR. Integers and strings are cleared to 0 and ""
488 respectively, while statistics are reset to the initial empty state.
491 Systemtap supports a number of operators that have the same general syntax,
492 semantics, and precedence as in C and awk. Arithmetic is performed as per
493 typical C rules for signed integers. Division by zero or overflow is
494 detected and results in an error.
496 binary numeric operators
497 .B * / % + \- >> << & ^ | && ||
499 binary string operators
501 (string concatenation)
503 numeric assignment operators
504 .B = *= /= %= += \-= >>= <<= &= ^= |=
506 string assignment operators
509 unary numeric operators
512 binary numeric or string comparison operators
516 .RB cond " ? " exp1 " : " exp2
522 .RB "fn " ( "[ arg1, arg2, ... ]" )
524 array membership check
527 .BR "[" exp1 ", " exp2 ", " ... "] in " array
530 The main construct in the scripting language identifies probes.
531 Probes associate abstract events with a statement block ("probe
532 handler") that is to be executed when any of those events occur. The
533 general syntax is as follows:
535 .BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " }
538 Events are specified in a special syntax called "probe points". There
539 are several varieties of probe points defined by the translator, and
540 tapset scripts may define further ones using aliases. These are
542 .IR stapprobes (3stap)
545 The probe handler is interpreted relative to the context of each
546 event. For events associated with kernel code, this context may
551 at that spot. These "target variables" are presented to the script as
552 variables whose names are prefixed with "$". They may be accessed
553 only if the kernel's compiler preserved them despite optimization.
554 This is the same constraint that a debugger user faces when working
555 with optimized code. Some other events have very little context.
557 New probe points may be defined using "aliases". Probe point aliases
558 look similar to probe definitions, but instead of activating a probe
559 at the given point, it just defines a new probe point name as an alias
560 to an existing one. There are two types of alias, i.e. the prologue
561 style and the epilogue style which are identified by "=" and "+="
564 For prologue style alias, the statement block that follows an alias
565 definition is implicitly added as a prologue to any probe that refers
566 to the alias. While for the epilogue style alias, the statement block
567 that follows an alias definition is implicitly added as an epilogue to
568 any probe that refers to the alias. For example:
571 probe syscall.read = kernel.function("sys_read") {
573 if (execname == "init") next # skip rest of probe
576 defines a new probe point
582 .IR kernel.function("sys_read") ,
584 with the given statement as a prologue, which is useful to predefine
585 some variables for the alias user and/or to skip probe processing
586 entirely based on some conditions. And
588 probe syscall.read += kernel.function("sys_read") {
589 if (tracethis) println ($fd)
592 defines a new probe point with the given statement as an epilogue, which
593 is useful to take actions based upon variables set or left over by the
596 An alias is used just like a built-in probe type.
599 printf("reading fd=%d\n", fildes)
600 if (fildes > 10) tracethis = 1
605 Systemtap scripts may define subroutines to factor out common work.
606 Functions take any number of scalar (integer or string) arguments, and
607 must return a single scalar (integer or string). An example function
608 declaration looks like this:
610 function thisfn (arg1, arg2) {
614 Note the general absence of type declarations, which are instead
615 inferred by the translator. However, if desired, a function
616 definition may include explicit type declarations for its return value
617 and/or its arguments. This is especially helpful for embedded-C
618 functions. In the following example, the type inference engine need
619 only infer type type of arg2 (a string).
621 function thatfn:string (arg1:long, arg2) {
622 return sprint(arg1) . arg2
625 Functions may call others or themselves
626 recursively, up to a fixed nesting limit. This limit is defined by
627 a macro in the translated C code and is in the neighbourhood of 10.
630 There are a set of function names that are specially treated by the
631 translator. They format values for printing to the standard systemtap
632 output stream in a more convenient way. The
634 variants return the formatted string instead of printing it.
636 .BR print ", " sprint
637 Print one or more values of any type, concatenated directly together.
639 .BR println ", " sprintln
641 .IR print " and " sprint ,
642 but also append a newline.
644 .BR printd ", " sprintd
645 Take a string delimiter and two or more values of any type, and print the
646 values with the delimiter interposed. The delimiter must be a literal
649 .BR printdln ", " sprintdln
650 Print values with a delimiter like
651 .IR printd " and " sprintd ,
652 but also append a newline.
654 .BR printf ", " sprintf
655 Take a formatting string and a number of values of corresponding types,
656 and print them all. The format must be a literal string constant.
660 formatting directives similar to those of C, except that they are
661 fully type-checked by the translator:
665 Writes a binary blob of the value given, instead of ASCII text. The width specifier determines the number of bytes to write; valid specifiers are %b %1b %2b %4b %8b. Default (%b) is 8 bytes.
674 Safely reads kernel memory at the given address, outputs its content. The precision specifier determines the number of bytes to read. Default is 1 byte.
677 Same as %m, but outputs in hexadecimal. The precision specifier determines the number of hexadecimal digits to output. Default is 1 digit.
683 Unsigned pointer address.
692 Unsigned hex value, in all lower-case.
695 Unsigned hex value, in all upper-case.
703 a = "alice", b = "bob", p = 0x1234abcd, i = 123, j = -1, id[a] = 1234, id[b] = 4567
708 println(a . " is " . sprint(16))
710 foreach (name in id) printdln("|", strlen(name), name, id[name])
711 Prints: 5|alice|1234\\n3|bob|4567
712 printf("%c is %s; %x or %X or %p; %d or %u\\n",97,a,p,p,p,j,j)
713 Prints: a is alice; 1234abcd or 1234ABCD or 0x1234abcd; -1 or 18446744073709551615\\n
714 printf("2 bytes of kernel buffer at address %p: %2m", p, p)
715 Prints: 2 byte of kernel buffer at address 0x1234abcd: <binary data>
717 Prints (these values as binary data): 0x1234abcd
721 It is often desirable to collect statistics in a way that avoids the
722 penalties of repeatedly exclusive locking the global variables those
723 numbers are being put into. Systemtap provides a solution using a
724 special operator to accumulate values, and several pseudo-functions to
725 extract the statistical aggregates.
727 The aggregation operator is
729 and resembles an assignment, or a C++ output-streaming operation.
730 The left operand specifies a scalar or array-index lvalue, which must
731 be declared global. The right operand is a numeric expression. The
732 meaning is intuitive: add the given number to the pile of numbers to
733 compute statistics of. (The specific list of statistics to gather
734 is given separately, by the extraction functions.)
737 stats[pid()] <<< memsize
740 The extraction functions are also special. For each appearance of a
741 distinct extraction function operating on a given identifier, the
742 translator arranges to compute a set of statistics that satisfy it.
743 The statistics system is thereby "on-demand". Each execution of
744 an extraction function causes the aggregation to be computed for
745 that moment across all processors.
747 Here is the set of extractor functions. The first argument of each is
748 the same style of lvalue used on the left hand side of the accumulate
750 .IR @count(v) ", " @sum(v) ", " @min(v) ", " @max(v) ", " @avg(v)
751 extractor functions compute the number/total/minimum/maximum/average
752 of all accumulated values. The resulting values are all simple
755 Histograms are also available, but are more complicated because they
756 have a vector rather than scalar value.
757 .I @hist_linear(v,start,stop,interval)
758 represents a linear histogram from "start" to "stop" by increments
759 of "interval". The interval must be positive. Similarly,
761 represents a base-2 logarithmic histogram. Printing a histogram
764 family of functions renders a histogram object as a tabular
765 "ASCII art" bar chart.
771 printf ("avg %d = sum %d / count %d\\n",
772 @avg(x), @sum(x), @count(x))
778 Once a pointer has been saved into a script integer variable, the
779 translator loses the type information necessary to access members from
780 that pointer. Using the
782 operator tells the translator how to read a pointer.
784 @cast(p, "type_name"[, "module"])->member
789 as a pointer to a struct/union named
795 tells the translator where to look for information about that type.
796 Multiple modules may be specified as a list with
798 separators. If the module is not specified, it will default either to
799 the probe module for dwarf probes, or to "kernel" for functions and all
802 The translator can create its own module with type information from a header
803 surrounded by angle brackets, in case normal debuginfo is not available. For
804 kernel headers, prefix it with "kernel" to use the appropriate build system.
805 All other headers are build with default GCC parameters into a user module.
807 @cast(tv, "timeval", "<sys/time.h>")->tv_sec
808 @cast(task, "task_struct", "kernel<linux/sched.h>")->tgid
811 When in guru mode, the translator will also allow scripts to assign new
812 values to members of typecasted pointers.
814 Typecasting is also useful in the case of
816 members whose type may be determinable at runtime.
819 if ($var->type == 1) {
820 value = @cast($var->data, "type1")->bar
822 value = @cast($var->data, "type2")->baz
829 When in guru mode, the translator accepts embedded code in the
830 script. Such code is enclosed between
834 markers, and is transcribed verbatim, without analysis, in some
835 sequence, into the generated C code. At the outermost level, this may
838 instructions, and any auxiliary definitions for use by other embedded
841 The other place where embedded code is permitted is as a function body.
842 In this case, the script language body is replaced entirely by a piece
843 of C code enclosed again between
846 This C code may do anything reasonable and safe. There are a number
847 of undocumented but complex safety constraints on atomicity,
848 concurrency, resource consumption, and run time limits, so this
849 is an advanced technique.
851 The memory locations set aside for input and output values
852 are made available to it using a macro
854 Here are some examples:
856 function add_one (val) %{
857 THIS\->__retvalue = THIS\->val + 1;
859 function add_one_str (val) %{
860 strlcpy (THIS\->__retvalue, THIS\->val, MAXSTRINGLEN);
861 strlcat (THIS\->__retvalue, "one", MAXSTRINGLEN);
864 The function argument and return value types have to be inferred by
865 the translator from the call sites in order for this to work. The
866 user should examine C code generated for ordinary script-language
867 functions in order to write compatible embedded-C ones.
870 A set of builtin functions and probe point aliases are provided
871 by the scripts installed under the
873 .IR @prefix@/share/systemtap/tapset
875 directory. These are described in the
876 .IR stapfuncs "(3stap) and " stapprobes (3stap)
880 The translator begins pass 1 by parsing the given input script,
881 and all scripts (files named
883 found in a tapset directory. The directories listed
886 are processed in sequence, each processed in "guru mode". For each
887 directory, a number of subdirectories are also searched. These
888 subdirectories are derived from the selected kernel version (the
891 in order to allow more kernel-version-specific scripts to override less
892 specific ones. For example, for a kernel version
894 the following patterns would be searched, in sequence:
895 .IR 2.6.12\-23.FC3/*.stp ,
900 Stopping the translator after pass 1 causes it to print the parse trees.
903 In pass 2, the translator analyzes the input script to resolve symbols
904 and types. References to variables, functions, and probe aliases that
905 are unresolved internally are satisfied by searching through the
906 parsed tapset scripts. If any tapset script is selected because it
907 defines an unresolved symbol, then the entirety of that script is
908 added to the translator's resolution queue. This process iterates
909 until all symbols are resolved and a subset of tapset scripts is
912 Next, all probe point descriptions are validated
913 against the wide variety supported by the translator. Probe points that
914 refer to code locations ("synchronous probe points") require the
915 appropriate kernel debugging information to be installed. In the
916 associated probe handlers, target-side variables (whose names begin
917 with "$") are found and have their run-time locations decoded.
919 Next, all probes and functions are analyzed for optimization
920 opportunities, in order to remove variables, expressions, and
921 functions that have no useful value and no side-effect. Embedded-C
922 functions are assumed to have side-effects unless they include the
925 Since this optimization can hide latent code errors such as type
926 mismatches or invalid $target variables, it sometimes may be useful
927 to disable the optimizations with the
931 Finally, all variable, function, parameter, array, and index types are
932 inferred from context (literals and operators). Stopping the
933 translator after pass 2 causes it to list all the probes, functions,
934 and variables, along with all inferred types. Any inconsistent or
935 unresolved types cause an error.
938 In pass 3, the translator writes C code that represents the actions
939 of all selected script files, and creates a
941 to build that into a kernel object. These files are placed into a
942 temporary directory. Stopping the translator at this point causes
943 it to print the contents of the C file.
946 In pass 4, the translator invokes the Linux kernel build system to
947 create the actual kernel object file. This involves running
949 in the temporary directory, and requires a kernel module build
950 system (headers, config and Makefiles) to be installed in the usual
952 .IR /lib/modules/VERSION/build .
953 Stopping the translator after pass 4 is the last chance before
954 running the kernel object. This may be useful if you want to
958 In pass 5, the translator invokes the systemtap auxiliary program
960 program for the given kernel object. This program arranges to load
961 the module then communicates with it, copying trace data from the
962 kernel into temporary files, until the user sends an interrupt signal.
963 Any run-time error encountered by the probe handlers, such as running
964 out of memory, division by zero, exceeding nesting or runtime limits,
965 results in a soft error indication. Soft errors in excess of
966 MAXERRORS block of all subsequent probes, and terminate the session.
969 unloads the module, and cleans up.
974 manual page for a collection of samples.
977 The systemtap translator caches the pass 3 output (the generated C
978 code) and the pass 4 output (the compiled kernel module) if pass 4
979 completes successfully. This cached output is reused if the same
980 script is translated again assuming the same conditions exist (same kernel
981 version, same systemtap version, etc.). Cached files are stored in
983 .I $SYSTEMTAP_DIR/cache
984 directory. The cache can be limited by having the file
986 placed in the cache directory (shown above) containing only an ASCII
987 integer representing how many MiB the cache should not exceed. Note that
988 this is a 'soft' limit in that the cache will be cleaned after a new entry
989 is added, so the total cache size may temporarily exceed this limit. In the
990 absence of this file, a default will be created with the limit set to 64MiB.
992 .SH SAFETY AND SECURITY
993 Systemtap is an administrative tool. It exposes kernel internal data
994 structures and potentially private user information.
996 either root privileges
998 To actually run the kernel objects it builds, a user must be one of
1009 group. Members of the
1011 group can only use modules located in
1012 the /lib/modules/VERSION/systemtap directory. This directory
1013 must be owned by root and not be world writable.
1015 The kernel modules generated by
1017 program are run by the
1019 program. The latter is a part of the Systemtap package, dedicated to
1020 module loading and unloading (but only in the white zone), and
1021 kernel-to-user data transfer. Since
1023 does not perform any additional security checks on the kernel objects
1024 it is given, it would be unwise for a system administrator to add
1025 untrusted users to the
1031 The translator asserts certain safety constraints. It aims to ensure
1032 that no handler routine can run for very long, allocate memory,
1033 perform unsafe operations, or in unintentionally interfere with the
1034 kernel. Use of script global variables is suitably locked to protect
1035 against manipulation by concurrent probe handlers. Use of guru mode
1036 constructs such as embedded C can violate these constraints, leading
1037 to kernel crash or data corruption.
1039 The resource use limits are set by macros in the generated C code.
1040 These may be overridden with the
1042 flag. A selection of these is as follows:
1045 Maximum number of recursive function call levels, default 10.
1048 Maximum length of strings, default 128.
1051 Maximum number of iterations to wait for locks on global variables
1052 before declaring possible deadlock and skipping the probe, default 1000.
1055 Maximum number of statements to execute during any single probe hit
1056 (with interrupts disabled),
1059 MAXACTION_INTERRUPTIBLE
1060 Maximum number of statements to execute during any single probe hit
1061 which is executed with interrupts enabled (such as begin/end probes),
1062 default (MAXACTION * 10).
1065 Maximum number of rows in any single global array, default 2048.
1068 Maximum number of soft errors before an exit is triggered, default 0, which
1069 means that the first error will exit the script.
1072 Maximum number of skipped probes before an exit is triggered, default 100.
1073 Running systemtap with \-t (timing) mode gives more details about skipped
1074 probes. With the default \-DINTERRUPTIBLE=1 setting, probes skipped due to
1075 reentrancy are not accumulated against this limit.
1078 Minimum number of free kernel stack bytes required in order to
1079 run a probe handler, default 1024. This number should be large enough
1080 for the probe handler's own needs, plus a safety margin.
1083 Maximum number of concurrently armed user-space probes (uprobes), default
1084 100 times the number of user-space probe points named in the script. This
1085 pool is large because individual uprobe objects are allocated for each
1086 process for each script-level probe.
1089 With scripts that contain probes on any interrupt path, it is possible that
1090 those interrupts may occur in the middle of another probe handler. The probe
1091 in the interrupt handler would be skipped in this case to avoid reentrance.
1092 To work around this issue, execute stap with the option
1093 .BR \-DINTERRUPTIBLE=0
1094 to mask interrupts throughout the probe handler. This does add some extra
1095 overhead to the probes, but it may prevent reentrance for common problem
1096 cases. However, probes in NMI handlers and in the callpath of the stap
1097 runtime may still be skipped due to reentrance.
1100 Multiple scripts can write data into a relay buffer concurrently. A host
1101 script provides an interface for accessing its relay buffer to guest scripts.
1102 Then, the output of the guests are merged into the output of the host.
1103 To run a script as a host, execute stap with
1104 .BR \-DRELAYHOST[=name]
1107 identifies your host script among several hosts.
1108 While running the host, execute stap with
1109 .BR \-DRELAYGUEST[=name]
1110 to add a guest script to the host.
1111 Note that you must unload guests before unloading a host. If there are some
1112 guests connected to the host, unloading the host will be failed.
1115 In case something goes wrong with
1116 .IR stap " or " staprun
1117 after a probe has already started running, one may safely kill both
1118 user processes, and remove the active probe kernel module with
1120 Any pending trace messages may be lost.
1123 In addition to the methods outlined above, the generated kernel module
1124 also uses overload processing to make sure that probes can't run for
1125 too long. If more than STP_OVERLOAD_THRESHOLD cycles (default
1126 500000000) have been spent in all the probes on a single cpu during
1127 the last STP_OVERLOAD_INTERVAL cycles (default 1000000000), the probes
1128 have overloaded the system and an exit is triggered.
1130 By default, overload processing is turned on for all modules. If you
1131 would like to disable overload processing, define STP_NO_OVERLOAD.
1133 .SH MAKING DO WITH SYMBOL TABLES
1134 Systemtap performs best when it has access to the debugging information
1135 associated with your kernel and modules.
1136 However, if this information is not available,
1137 systemtap can still support probing of function entries and returns
1138 using symbols read from vmlinux and/or the modules in /lib/modules.
1139 Systemtap can also read the kernel symbol table from a text file
1140 such as /boot/System.map or /proc/kallsyms.
1147 If systemtap finds relevant debugging information,
1148 it will use it even if you specify
1153 Without debugging information, systemtap cannot support the
1154 following types of language constructs:
1156 probe specifications that refer to source files or line numbers
1158 probe specifications that refer to inline functions
1160 statements that refer to $target variables
1162 statements that refer to @cast() variables
1164 tapset-defined variables defined using any of the above constructs.
1165 In particular, at this writing,
1166 the prologue blocks for certain aliases in the syscall tapset
1167 (e.g., syscall.open) contain "if" statements that refer to $target variables.
1168 If your script refers to any such aliases,
1169 systemtap must have access to the kernel's debugging information.
1171 Most T and t symbols correspond to function entry points, but some do not.
1172 Based only on the symbol table, systemtap cannot tell the difference.
1173 Placing return probes on symbols that aren't entry points
1174 will most likely lead to kernel stack corruption.
1177 .\" consider autoconf-substituting these directories
1180 Systemtap data directory for cached systemtap files, unless overridden
1183 environment variable.
1186 Temporary directory for systemtap files, including translated C code
1189 @prefix@/share/systemtap/tapset
1190 The automatic tapset search directory, unless overridden by
1193 environment variable.
1195 @prefix@/share/systemtap/runtime
1196 The runtime sources, unless overridden by the
1197 .I SYSTEMTAP_RUNTIME
1198 environment variable.
1200 /lib/modules/VERSION/build
1201 The location of kernel module building infrastructure.
1203 @prefix@/lib/debug/lib/modules/VERSION
1204 The location of kernel debugging information when packaged into the
1205 .IR kernel\-debuginfo
1206 RPM, unless overridden by the
1207 .I SYSTEMTAP_DEBUGINFO_PATH
1208 environment variable. The default value for this variable is
1209 .IR \+:.debug:/usr/lib/debug:build .
1210 Elfutils searches vmlinux in this path and it interprets the path as a base
1211 directory of which various subdirectories will be searched for finding modules.
1213 @prefix@/bin/staprun
1214 The auxiliary program supervising module loading, interaction, and
1218 .IR stapprobes (3stap),
1219 .IR stapfuncs (3stap),
1220 .IR stapvars (3stap),
1226 Use the Bugzilla link off of the project web page or our mailing list.
1228 .BR http://sources.redhat.com/systemtap/ , <systemtap@sources.redhat.com> .
git://sourceware.org / systemtap.git / blob