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.3 print

General syntax:

print:unknown ()

This function prints a single value of any type.

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:

Table 1: printf specifier values

Specifier	Output	Example d or i

The tag can also contain flags, width, .precision and modifiers sub-specifiers, which are optional and follow these specifications:

Table 2: printf flag values

Flags	Description - (minus sign)

Table 3: printf width values

Width	Description (number)

Table 4: printf precision values

Precision	Description .number

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.

9.1.10 system

General syntax:

system (cmd:string)

The system function runs a command on the system. The specified command runs in the background once the current probe completes.

9.1.11 warn

General syntax:

warn:unknown (msg:string)

This function sends a warning message immediately to staprun. It is also sent over the bulk transport (relayfs) if it is being used. If the last character is not a newline, then one is added.

9.2 Context at the probe point

The following functions provide ways to access the current task context at a probe point. Note that these may not return correct values when a probe is hit in interrupt context.

9.2.1 backtrace

General syntax:

backtrace:string ()

Returns a string of hex addresses that are a backtrace of the stack. The output is truncated to MAXSTRINGLEN.

9.2.2 caller

General syntax:

caller:string()

Returns the address and name of the calling function. It works only for return probes.

9.2.3 caller_addr

General syntax:

caller_addr:long ()

Returns the address of the calling function. It works only for return probes.

9.2.4 cpu

General syntax:

cpu:long ()

Returns the current cpu number.

9.2.5 egid

General syntax:

egid:long ()

Returns the effective group ID of the current process.

9.2.6 euid

General syntax:

euid:long ()

Returns the effective user ID of the current process.

9.2.7 execname

General syntax:

execname:string ()

Returns the name of the current process.

9.2.8 gid

General syntax:

gid:long ()

Returns the group ID of the current process.

9.2.9 is_return

General syntax:

is_return:long ()

Returns 1 if the probe point is a return probe, else it returns zero.

DEPRECATED.

9.2.10 pexecname

General syntax:

pexecname:string ()

Returns the name of the parent process.

9.2.11 pid

General syntax:

pid:long ()

Returns the process ID of the current process.

9.2.12 ppid

General syntax:

ppid:long ()

Returns the process ID of the parent process.

9.2.13 tid

General syntax:

tid:long ()

Returns the ID of the current thread.

9.2.14 uid

General syntax:

uid:long ()

Returns the user ID of the current task.

9.2.15 print_backtrace

General syntax:

print_backtrace:unknown ()

This function is equivalent to print_stack(backtrace()), except that deeper stack nesting is supported. The function does not return a value.

9.2.16 print_regs

General syntax:

print_regs:unknown ()

This function prints a register dump.

9.2.17 print_stack

General syntax:

print_stack:unknown (stk:string)

This function performs a symbolic lookup of the addresses in the given string, which is assumed to be the result of a prior call to backtrace(). It prints one line per address. Each printed line includes the address, the name of the function containing the address, and an estimate of its position within that function. The function does not return a value.

9.2.18 stack_size

General syntax:

stack_size:long ()

Returns the size of the stack.

9.2.19 stack_unused

General syntax:

stack_unused:long ()

Returns how many bytes are currently unused in the stack.

9.2.20 stack_used

General syntax:

stack_used:long ()

Returns how many bytes are currently used in the stack.

9.2.21 stp_pid

stp_pid:long ()

Returns the process ID of the of the staprun process.

9.2.22 target

General syntax:

target:long ()

Returns the process ID of the target process. This is useful in conjunction with the -x PID or -c CMD command-line options to stap. An example of its use is to create scripts that filter on a specific process.

-x <pid>

target() returns the pid specified by -x

-c <command>

target() returns the pid for the executed command specified by -c.

9.3 Task data

These functions return data about a task. They all require a task handle as input, such as the value return by task_current() or the variables prev_task and next_task in the scheduler.ctxswitch probe alias.

9.3.1 task_cpu

General syntax:

task_cpu:long (task:long)

Returns the scheduled cpu for the given task.

9.3.2 task_current

General syntax:

task_current:long ()

Returns the address of the task_struct representing the current process. This address can be passed to the various task_*() functions to extract more task-specific data.

9.3.3 task_egid

General syntax:

task_egid:long (task:long)

Returns the effective group ID of the given task.

9.3.4 task_execname

General syntax:

task_execname:string (task:long)

Returns the name of the given task.

9.3.5 task_euid

General syntax:

task_euid:long (task:long)

Returns the effective user ID of the given task.

9.3.6 task_gid

General syntax:

task_gid:long (task:long)

Returns the group ID of the given task.

9.3.7 task_nice

General syntax:

task_nice:long (task:long)

Returns the nice value of the given task.

9.3.8 task_parent

General syntax:

task_parent:long (task:long)

Returns the address of the parent task_struct of the given task. This address can be passed to the various task_*() functions to extract more task-specific data.

9.3.9 task_pid

General syntax:

task_pid:long (task:long)

Returns the process ID of the given task.

9.3.10 task_prio

General syntax:

task_prio:long (task:long)

Returns the priority value of the given task.

9.3.11 task_state

General syntax:

task_state:long (task:long)

Returns the state of the given task. Possible states are:

TASK_RUNNING           0
TASK_INTERRUPTIBLE     1
TASK_UNINTERRUPTIBLE   2
TASK_STOPPED           4
TASK_TRACED            8
EXIT_ZOMBIE           16
EXIT_DEAD             32

9.3.12 task_tid

General syntax:

task_tid:long (task:long)

Returns the thread ID of the given task.

9.3.13 task_uid

General syntax:

task_uid:long (task:long)

Returns the user ID of the given task.

9.3.14 task_open_file_handles

General syntax:

task_open_file_handles:long(task:long)

Returns the number of open file handles for the given task.

9.3.15 task_max_file_handles

General syntax:

task_max_file_handles:long(task:long)

Returns the maximum number of file handles for the given task.

9.4 Accessing string data at a probe point

The following functions provide methods to access string data at a probe point.

9.4.1 kernel_string

General syntax:

kernel_string:string (addr:long)

Copies a string from kernel space at a given address. The validation of this address is only partial.

9.4.2 user_string

General syntax:

user_string:string (addr:long)

This function copies a string from user space at a given address. The validation of this address is only partial. In rare cases when userspace data is not accessible, this function returns the string <unknown>.

9.4.3 user_string2

General syntax:

user_string2:string (addr:long, err_msg:string)

This function is similar to user_string, (Section 9.4.2) but allows passing an error message as an argument to be returned if userspace data is not available.

9.4.4 user_string_warn

General syntax:

user_string_warn:string (addr:long)

This function copies a string from userspace at given address. It prints a verbose error message on failure.

9.4.5 user_string_quoted

General syntax:

user_string_quoted:string (addr:long)

This function copies a string from userspace at given address. Any ASCII characters that are not printable are replaced by the corresponding escape sequence in the returned string.

9.5 Initializing queue statistics

The queue_stats tapset provides functions that, when given notification of queuing events like wait, run, or done, track averages such as queue length, service and wait times, and utilization. Call the following three functions from appropriate probes, in sequence.

9.5.1 qs_wait

General syntax:

qs_wait:unknown (qname:string)

This function records that a new request was enqueued for the given queue name.

9.5.2 qs_run

General syntax:

qs_run:unknown (qname:string)

This function records that a previously enqueued request was removed from the given wait queue and is now being serviced.

9.5.3 qs_done

General syntax:

qs_done:unknown (qname:string)

This function records that a request originally from the given queue has completed being serviced.

9.6 Using queue statistics

Functions with the qsq_ prefix query the statistics averaged since the first queue operation or when qsq_start was called. Since statistics are often fractional, a scale parameter multiplies the result to a more useful scale. For some fractions, a scale of 100 returns percentage numbers.

9.6.1 qsq_blocked

General syntax:

qsq_blocked:long (qname:string, scale:long)

This function returns the fraction of elapsed time during which one or more requests were on the wait queue.

9.6.2 qsq_print

General syntax:

qsq_print:unknown (qname:string)

This function prints a line containing the following statistics for the given queue:

• queue name
• average rate of requests per second
• average wait queue length
• average time on the wait queue
• average time to service a request
• percentage of time the wait queue was used
• percentage of time any request was being serviced

9.6.3 qsq_service_time

General syntax:

qsq_service_time:long (qname:string, scale:long)

This function returns the average time in microseconds required to service a request once it is removed from the wait queue.

9.6.4 qsq_start

General syntax:

qsq_start:unknown (qname:string)

This function resets the statistics counters for the given queue, and restarts tracking from the moment the function was called. This command is used to create a queue.

9.6.5 qsq_throughput

General syntax:

qsq_throughput:long (qname:string, scale:long)

This function returns the average number of requests served per microsecond.

9.6.6 qsq_utilization

General syntax:

qsq_utilization:long (qname:string, scale:long)

This function returns the average time in microseconds that at least one request was being serviced.

9.6.7 qsq_wait_queue_length

General syntax:

qsq_wait_queue_length:long (qname:string, scale:long)

This function returns the average length of the wait queue.

9.6.8 qsq_wait_time

General syntax:

qsq_wait_time:long (qname:string, scale:long)

This function returns the average time in microseconds that it took for a request to be serviced (qs_wait() to qs_done()).

9.6.9 A queue example

What follows is an example from src/testsuite/systemtap.samples/queue_demo.stp. It uses the randomize feature of the timer probe to simulate queuing activity.

probe begin {
    qsq_start ("block-read")
    qsq_start ("block-write")
}

probe timer.ms(3500), end {
    qsq_print ("block-read")
    qsq_start ("block-read")
    qsq_print ("block-write")
    qsq_start ("block-write")
}

probe timer.ms(10000) {
    exit ()
}

# synthesize queue work/service using three randomized "threads" for each queue.
global tc

function qs_doit (thread, name) {
    n = tc[thread] = (tc[thread]+1) % 3 # per-thread state counter
    if (n==1) qs_wait (name)
    else if (n==2) qs_run (name)
    else if (n==0) qs_done (name)
}

probe timer.ms(100).randomize(100) { qs_doit (0, "block-read") }
probe timer.ms(100).randomize(100) { qs_doit (1, "block-read") }
probe timer.ms(100).randomize(100) { qs_doit (2, "block-read") }
probe timer.ms(100).randomize(100) { qs_doit (3, "block-write") }
probe timer.ms(100).randomize(100) { qs_doit (4, "block-write") }
probe timer.ms(100).randomize(100) { qs_doit (5, "block-write") }

This prints:

block-read: 9 ops/s, 1.090 qlen, 215749 await, 96382 svctm, 69% wait, 64% util
block-write: 9 ops/s, 0.992 qlen, 208485 await, 103150 svctm, 69% wait, 61% util
block-read: 9 ops/s, 0.968 qlen, 197411 await, 97762 svctm, 63% wait, 63% util
block-write: 8 ops/s, 0.930 qlen, 202414 await, 93870 svctm, 60% wait, 56% util
block-read: 8 ops/s, 0.774 qlen, 192957 await, 99995 svctm, 58% wait, 62% util
block-write: 9 ops/s, 0.861 qlen, 193857 await, 101573 svctm, 56% wait, 64% util

9.7 Probe point identification

The following functions help you identify probe points.

9.7.1 pp

General syntax:

pp:string ()

This function returns the probe point associated with a currently running probe handler, including alias and wild-card expansion effects.

9.7.2 probefunc

General syntax:

probefunc:string ()

This function returns the name of the function being probed.

9.7.3 probemod

General syntax:

probemod:string ()

This function returns the name of the module containing the probe point.

9.8 Formatting functions

The following functions help you format output.

9.8.1 ctime

General syntax:

ctime:string(epochsecs:long)

This function accepts an argument of seconds since the epoch as returned by gettimeofday_s(). It returns a date string in UTC of the form:

"Wed Jun 30 21:49:008 2006"

This function does not adjust for timezones. The returned time is always in GMT. Your script must manually adjust epochsecs before passing it to ctime() if you want to print local time.

9.8.2 errno_str

General syntax:

errno_str:string (err:long)

This function returns the symbolic string associated with the given error code, such as ENOENT for the number 2, or E#3333 for an out-of-range value such as 3333.

9.8.3 returnstr

General syntax:

returnstr:string (returnp:long)

This function is used by the syscall tapset, and returns a string. Set returnp equal to 1 for decimal, or 2 for hex.

9.8.4 thread_indent

General syntax:

thread_indent:string (delta:long)

This function returns a string with appropriate indentation for a thread. Call it with a small positive or matching negative delta. If this is the outermost, initial level of indentation, then the function resets the relative timestamp base to zero.

The following example uses thread_indent() to trace the functions called in the drivers/usb/core kernel source. It prints a relative timestamp and the name and ID of the current process, followed by the appropriate indent and the function name. Note that "swapper(0)" indicates the kernel is running in interrupt context and there is no valid current process.

probe kernel.function("*@drivers/usb/core/*") {
    printf ("%s -> %s\n", thread_indent(1), probefunc())
}
probe kernel.function("*@drivers/usb/core/*").return {
    printf ("%s <- %s\n", thread_indent(-1), probefunc())
}

This prints:

 0 swapper(0): -> usb_hcd_irq
 8 swapper(0): <- usb_hcd_irq
 0 swapper(0): -> usb_hcd_irq
10 swapper(0):  -> usb_hcd_giveback_urb
16 swapper(0):   -> urb_unlink
22 swapper(0):   <- urb_unlink
29 swapper(0):   -> usb_free_urb
35 swapper(0):   <- usb_free_urb
39 swapper(0):  <- usb_hcd_giveback_urb
45 swapper(0): <- usb_hcd_irq
 0 usb-storage(1338): -> usb_submit_urb
 6 usb-storage(1338):  -> usb_hcd_submit_urb
12 usb-storage(1338):   -> usb_get_urb
18 usb-storage(1338):   <- usb_get_urb
25 usb-storage(1338):  <- usb_hcd_submit_urb
29 usb-storage(1338): <- usb_submit_urb
 0 swapper(0): -> usb_hcd_irq
 7 swapper(0): <- usb_hcd_irq

9.8.5 thread_timestamp

General syntax:

thread_timestamp:long ()

This function returns an absolute timestamp value for use by the indentation function. The default function uses gettimeofday_us.

9.9 String functions

The following are string functions you can use.

9.9.1 isinstr

General syntax:

isinstr:long (s1:string, s2:string)

This function returns 1 if string s1 contains string s2, otherwise zero.

9.9.2 strlen

General syntax:

strlen:long (str:string)

This function returns the number of characters in str.

9.9.3 strtol

General syntax:

strtol:long (str:string, base:long)

This function converts the string representation of a number to an integer. The base parameter indicates the number base to assume for the string (e.g. 16 for hex, 8 for octal, 2 for binary).

9.9.4 substr

General syntax:

substr:string (str:string, start:long, stop:long)

This function returns the substring of str starting from character position start and ending at character position stop.

9.9.5 text_str

General syntax:

text_str:string (input:string)

This function accepts a string argument. Any ASCII characters in the string that are not printable are replaced by a corresponding escape sequence in the returned string.

9.9.6 text_strn

General syntax:

text_strn:string (input:string, len:long, quoted:long)

This function accepts a string of length len. Any ASCII characters that are not printable are replaced by a corresponding escape sequence in the returned string. If quoted is not null, the function adds a backslash character to the output.

9.9.7 tokenize

General syntax:

tokenize:string (input:string, delim:string)

This function returns the next non-empty token in the given input string, where the tokens are delimited by characters in the delim string. If the input string is non-NULL, it returns the first token. If the input string is NULL, it returns the next token in the string passed in the previous call to tokenize. If no delimiter is found, the entire remaining input string is returned. It returns NULL when no more tokens are available.

9.10 Timestamps

The following functions provide methods to extract time data.

9.10.1 get_cycles

General syntax:

get_cycles:long ()

This function returns the processor cycle counter value if available, else it returns zero.

9.10.2 gettimeofday_ms

General syntax:

gettimeofday_ms:long ()

This function returns the number of milliseconds since the UNIX epoch.

9.10.3 gettimeofday_ns

General syntax:

gettimeofday_ns:long ()

This function returns the number of nanoseconds since the UNIX epoch.

9.10.4 gettimeofday_s

General syntax:

gettimeofday_s:long ()

This function returns the number of seconds since the UNIX epoch.

9.10.5 gettimeofday_us

General syntax:

gettimeofday_us:long ()

This function returns the number of microseconds since the UNIX epoch.

9.11 Miscellaneous tapset functions

The following are miscellaneous functions.

9.11.1 addr_to_node

General syntax:

addr_to_node:long (addr:long)

This function accepts an address, and returns the node that the given address belongs to in a NUMA system.

9.11.2 exit

General syntax:

exit:unknown ()

This function enqueues a request to shut down the SystemTap session. It does not unwind the current probe handler, nor block new probe handlers. The stap daemon will respond to the request and initiate an ordered shutdown.

9.11.3 system

General syntax:

system (cmd:string)

This function runs a command on the system. The command will run in the background when the current probe completes.