Passing Parameters to Systemtap

There are several ways of passing parameters to a systemtap script in order to generalize it. Any combination of these methods may be used together, but they are not interchangeable. They operate at different times on different types of parameters.

Substituted stap/translator command line options

Extra arguments given to stap are made available to the parser for substitution into the script for the $N (token-pasted) and @N (stringified) syntax, similar to shell script arguments. The argv tapset makes the same values available with a C-like array syntax.

# stap -e 'probe kernel.$1 { if (execname() == @2 || pid()==$3) log("yo") }' \
          'function("*open*") . return'  ls  444
...
# stap -e 'probe begin {if (argc>=2) println(argv[2]) exit()}'  'foo' 'bar'
bar

One drawback of this technique is that different command line arguments require recompilation of the script. The corresponding advantage is that these arguments can be used in places where compile-time literals are required, like probe point parameters, or larger blocks of parsed text.

Target processes

When systemtap is run with a given target process (with the -c COMMAND or -x PID option), all utrace-related process.* probes are constrained to the process hierarchy corresponding to the given target process. (Other processes on the system will not be affected.) The PID of the target process is also available to the script at runtime as the target() function.

# stap -e 'probe kernel.function("sys_open") { if (pid()==target()) log(argstr) }' -c ls
# stap -e 'probe process.begin, process.end { printf("%s %s %d\n", pp(), execname(), pid() }' -x 999

staprun module options for global script variables

A compiled script results in a .ko compiled probe module file. Running stap -p4 stops script processing at this stage and prints the module's file name. One can normally run staprun FOO.ko to launch the probe module as if it had been started by stap directly. While the the script code becomes fixed, some of the data is available for custom startup-time initialization.

When using staprun (or stap's -G option), it is possible to pass extra module parameters to the kernel and the probe module. Normal scalar global variables (strings and numbers) in the script are given a corresponding module option with which their script-initialized values may be overridden.

% stap -p4 -e '
    global foo
    probe begin {log("he" . foo . "ld") exit()}'
FOO.ko
# staprun FOO.ko
held
# staprun FOO.ko foo=llowor
helloworld
# stap -e SAME_SCRIPT -G foo=llowor
helloworld

As of systemtap 2.5, the argv tapset also permits run-time positional assignment to argc and argv_NNN.

% stap -e 'probe oneshot { println(argv[1]) }' -G argv_1=hello

/proc inputs

Using the procfs("FILE").write probe, a systemtap script may receive textual commands from userspace at run time. It can do anything necessary, including activating or deactivating probes, setting internal mode variables, or printing a report.

# stap -m NAME -e 'probe procfs("mailbox").write { log("received command " . $value) }' &
# echo yo > /proc/systemtap/NAME/mailbox
received command yo

Tips