5 Language elements

5.1 Identifiers

Identifiers are used to name variables and functions. They are an alphanumeric sequence that may include the underscore (_) and dollar sign ($) characters. They have the same syntax as C identifiers, except that the dollar sign is also a legal character. Identifiers that begin with a dollar sign are interpreted as references to variables in the target software, rather than to SystemTap script variables. Identifiers may not start with a plain digit.

5.2 Data types

The SystemTap language includes a small number of data types, but no type declarations. A variable's type is inferred from its use. To support this inference, the translator enforces consistent typing of function arguments and return values, array indices and values. There are no implicit type conversions between strings and numbers. Inconsistent type-related use of identifiers signals an error.

5.2.1 Literals

Literals are either strings or integers. Literals can be expressed as decimal, octal, or hexadecimal, using C notation. Type suffixes (e.g., L or U) are not used.

5.2.2 Integers

Integers are decimal, hexadecimal, or octal, and use the same notation as in C. Integers are 64-bit signed quantities, although the parser also accepts (and wraps around) values above positive $2^{63}$ but below $2^{64}$.

5.2.3 Strings

Strings are enclosed in quotation marks (``string''), and pass through standard C escape codes with backslashes. Strings are limited in length to MAXSTRINGLEN. For more information about this and other limits, see Section .

5.2.4 Associative arrays

See Section 

5.2.5 Statistics

See Section 

5.3 Semicolons

The semicolon is the null statement, or do nothing statement. It is optional, and useful as a separator between statements to improve detection of syntax errors and to reduce ambiguities in grammar.

5.4 Comments

Three forms of comments are supported, as follows.

# ... shell style, to the end of line
// ... C++ style, to the end of line
/* ... C style ... */

5.5 Whitespace

As in C, spaces, tabs, returns, newlines, and comments are treated as whitespace. Whitespace is ignored by the parser.

5.6 Expressions

SystemTap supports a number of operators that use the same general syntax, semantics, and precedence as in C and awk. Arithmetic is performed per C rules for signed integers. If the parser detects division by zero or an overflow, it generates an error. The following subsections list these operators.

5.6.1 Binary numeric operators

* / % + - >> << & ^ | && ||

5.6.2 Binary string operators

. (string concatenation)

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

cond ? exp1 : exp2

5.6.8 Grouping operator

( exp )

5.6.9 Function call

General syntax:

fn ([ arg1, arg2, ... ])

5.6.10 $ptr->member

ptr is a kernel pointer available in a probed context.

5.6.11 <value> in <array_name>

This expression evaluates to true if the array contains an element with the specified index.

5.6.12 [ <value>, ... ] in <array_name>

The number of index values must match the number of indexes previously specified.

5.7 Literals passed in from the stap command line

Literals are either strings enclosed in double quotes ('' '') or integers. For information about integers, see Section . For information about strings, see Section .

Script arguments at the end of a command line are expanded as literals. You can use these in all contexts where literals are accepted. A reference to a nonexistent argument number is an error.

5.7.1 $1 ... $<NN> for integers

Use $1 ... $<NN> for casting as a numeric literal.

5.7.2 @1 ... @<NN> for strings

Use @1 ... @<NN> for casting as a string literal.

5.7.3 Examples

For example, if the following script named example.stp

probe begin { printf("%d, %s\n", $1, @2) }

is invoked as follows

# stap example.stp 10 mystring

then 10 is substituted for $1 and "mystring" for @2. The output will be

10, mystring

5.8 Conditional compilation

5.8.1 Conditions

One of the steps of parsing is a simple conditional preprocessing stage. The general form of this is similar to the ternary operator (Section ).

%( CONDITION %? TRUE-TOKENS %)
%( CONDITION %? TRUE-TOKENS %: FALSE-TOKENS %)

The CONDITION is a limited expression whose format is determined by its first keyword. The following is the general syntax.

%( <condition> %? <code> [ %: <code> ] %)

5.8.2 Conditions based on kernel version: kernel_v, kernel_vr

If the first part of a conditional expression is the identifier kernel_v or kernel_vr, the second part must be one of six standard numeric comparison operators ``<'', ``<='', ``=='', ``!='', ``>'', or ``>='', and the third part must be a string literal that contains an RPM-style version-release value. The condition returns true if the version of the target kernel (as optionally overridden by the -r option) matches the given version string. The comparison is performed by the glibc function strverscmp.

kernel_v refers to the kernel version number only, such as ``2.6.13".

kernel_vr refers to the kernel version number including the release code suffix, such as ``2.6.13-1.322FC3smp''.

5.8.3 Conditions based on architecture: arch

If the first part of the conditional expression is the identifier arch which refers to the processor architecture, then the second part is a string comparison operator ''=='' or ''!='', and the third part is a string literal for matching it. This comparison is a simple string equality or inequality. The currently supported architecture strings are i386, i686, x86_64, ia64, s390x and ppc64.

5.8.4 True and False Tokens

TRUE-TOKENS and FALSE-TOKENS are zero or more general parser tokens, possibly including nested preprocessor conditionals, that are pasted into the input stream if the condition is true or false. For example, the following code induces a parse error unless the target kernel version is newer than 2.6.5.

%( kernel_v <= "2.6.5" %? **ERROR** %) # invalid token sequence

The following code adapts to hypothetical kernel version drift.

probe kernel.function (
    %( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
        %( kernel_vr == "2.6.13-1.8273FC3smp" %? "do_page_fault" %: UNSUPPORTED %)
    %)) { /* ... */ }

%( arch == "ia64" %?
    probe syscall.vliw = kernel.function("vliw_widget") {}
%)