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.
Substituted 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
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
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, 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
/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