Chapter 9. Predefined functions
Unlike built-in functions, predefined functions are implemented in tapsets.
9.1. Output functions
The following sections describe the functions you can use to output data.
9.1.1. error
General syntax:
error:unknown (msg:string)
This function logs the given string to the error stream. It appends an implicit end-of-line. It blocks any further execution of statements in this probe. If the number of errors exceeds the MAXERRORS parameter, it triggers an
exit.
9.1.2. log
General syntax:
log:unknown (msg:string) log (const char *fmt, )
This function logs data.
log sends the message immediately to staprun and to the bulk transport (relayfs) if it is being used. If the last character given is not a newline, then one is added.
This function is not as efficient as printf and should only be used for urgent messages.
9.1.4. printf
General syntax:
printf:unknown (fmt:string, )
The printf function takes a formatting string as an argument, and a number of values of corresponding types, and prints them all. The format must be a literal string constant. The printf formatting directives are similar to those of C, except that they are fully checked for type by the translator.
The formatting string can contain tags that are defined as follows:
%[flags][width][.precision][length]specifier
Where
specifier is required and defines the type and the interpretation of the value of the corresponding argument. The following table shows the details of the specifier parameter:
Specifier | Output | Example |
| d or i | Signed decimal | 392 |
| o | Unsigned octal | 610 |
| s | String | sample |
| u | Unsigned decimal | 7235 |
| x | Unsigned hexadecimal (lowercase letters) | 7fa |
| X | Unsigned hexadecimal (uppercase letters) | 7FA |
| p | Pointer address | 0x0000000000bc614e |
| b | Writes a binary value as text. The field width specifies the number of bytes to write. Valid specifications are %b, %1b, %2b, %4b and %8b. The default width is 8 (64-bits). | See below |
| % | A % followed by another % character will write % to stdout. | % |
The tag can also contain
flags, width, .precision and modifiers sub-specifiers, which are optional and follow these specifications:
Flags | Description | |
| - (minus sign) | Left-justify within the given field width. Right justification is the default (see width sub-specifier). | |
| + (plus sign) | Precede the result with a plus or minus sign even for positive numbers. By default, only negative numbers are preceded with a minus sign. | |
| (space) | If no sign is going to be written, a blank space is inserted before the value. | |
| # | Used with o, x or X specifiers the value is preceded with 0, 0x or 0X respectively for non-zero values. | |
| 0 | Left-pads the number with zeroes instead of spaces, where padding is specified (see width sub-specifier). |
Width | Description | |
| (number) | Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger. |
Precision | Description | |
| .number | For integer specifiers (d, i, o, u, x, X): precision specifies the minimum number of digits to be written. If the value to be written is shorter than this number, the result is padded with leading zeros. The value is not truncated even if the result is longer. A precision of 0 means that no character is written for the value 0. For s: this is the maximum number of characters to be printed. By default all characters are printed until the ending null character is encountered. When no precision is specified, the default is 1. If the period is specified without an explicit value for precision, 0 is assumed. |
Binary Write Examples
The following is an example of using the binary write functions:
probe begin {
for (i = 97; i < 110; i++)
printf("%3d: %1b%1b%1b\n", i, i, i-32, i-64)
exit()
}
This prints:
97: aA! 98: bB" 99: cC# 100: dD$ 101: eE% 102: fF& 103: gG' 104: hH( 105: iI) 106: jJ* 107: kK+ 108: lL, 109: mM-
Another example:
stap -e 'probe begin{printf("%b%b", 0xc0dedbad, \
0x12345678);exit()}' | hexdump -C
This prints:
00000000 ad db de c0 00 00 00 00 78 56 34 12 00 00 00 00 |........xV4.....| 00000010
Another example:
probe begin{
printf("%1b%1b%1blo %1b%1brld\n", 72,101,108,87,111)
exit()
}
This prints:
Hello World
9.1.5. printd
General syntax:
printd:unknown (delimiter:string, )
This function takes a string delimiter and two or more values of any type, then prints the values with the delimiter interposed. The delimiter must be a literal string constant.
For example:
printd("/", "one", "two", "three", 4, 5, 6)
prints:
one/two/three/4/5/6
9.1.6. printdln
General syntax:
printdln:unknown ()
This function operates like
printd, but also appends a newline.
9.1.7. println
General syntax:
println:unknown ()
This function operates like
print, but also appends a newline.
9.1.8. sprint
General syntax:
sprint:unknown ()
This function operates like
print, but returns the string rather than printing it.
9.1.9. sprintf
General syntax:
sprintf:unknown (fmt:string, )
This function operates like
printf, but returns the formatted string rather than printing it.
