STAPDYN(8)

💖 STAPDYN(8) — the systemtap dyninst runtime, bestie edition 💖

okay so. this is stapdyn, from the System Manager's Manual, section 8 (the big-girl system admin section, periodt). it's the dyninst back-end of Systemtap, and honestly? she's a whole vibe. let's get into it 🫶

---

✨ NAME ✨

stapdyn — systemtap dyninst runtime 💅

---

🎀 SYNOPSIS 🎀

stapdyn [ OPTIONS ] MODULE [ MODULE-OPTIONS ]

that's it. that's the shape of it. options, then a module, then optionally some module-options. no notes. ⭐

---

🦋 DESCRIPTION 🦋

so stapdyn is the dyninst back-end of the Systemtap tool. what she's expecting is a shared library that the front-end stap tool made, when you ran stap with --dyninst. that's the whole deal. 💜

now, why is the tool split into a front-end and a back-end, you ask? because that split is genuinely iconic:

• you can compile a systemtap script on a development machine that actually has the debugging information (you need that to compile the script, fr fr)
• then you just transfer the resulting shared object over to a production machine that has literally no development tools and no debugging information installed

it's giving "do the messy work at home, show up cute to the party". ✨

oh and if you need the version number, please refer to stappaths (7), or just run rpm -q systemtap (on fedora / red hat) or apt-get -v systemtap (on ubuntu). pick your fighter. 🍓

---

👑 OPTIONS 👑

stapdyn supports the following options. any other option just prints you a list of supported options, which is honestly her way of saying "bestie, that's not a thing". 😭

• -v — verbose mode. she will tell you everything. 💬
• -V — print the version number and exit. short and sweet, love that for her.
• -w — suppress warnings coming from the script. shhh. 🤫
• -c CMD — command CMD will be run, and stapdyn will exit when CMD does. the '_stp_target' variable will contain the pid for CMD. 💫
• -x PID — the '_stp_target' variable will be set to PID. that's it, that's the whole job.
• -o FILE — send output to FILE. but WAIT — if the module uses bulk mode, the output goes into percpu files FILE_x (FILE_cpux in background and bulk mode), where 'x' is the cpu number. also this supports strftime(3) formats for FILE, so you can get cute with timestamps. 🌸
• -C WHEN — control the coloring of error messages. WHEN must be either "never", "always", or "auto" (i.e. only enable it if you're at a terminal). if the option is missing, then "auto" is assumed. you can also modify colors using the SYSTEMTAP_COLORS environment variable — see the stap(1) manual page for more info on the syntax and behaviour. 🎨
• var1=val — sets the value of the global variable var1 to val. global variables contained within a script are treated as options and can be set right from the stapdyn command line. so yes, you can just pass them in like that. 💅

---

🧚 ARGUMENTS 🧚

MODULE is either a module path or a module name. if it's a module name, the module will be looked for in the following directory (where 'VERSION' is the output of "uname -r"):

/lib/modules/VERSION/systemtap

so for example, bestie:

 $ stap --dyninst -p4 -m mod1 -e 'global var1="foo"; probe begin{printf("%s\n", var1); exit()}'

and running this with an additional module argument:

 $ stapdyn mod1.so var1="HelloWorld"
 HelloWorld

look at her go. 😭🫶

ngl, spaces and exclamation marks currently cannot be passed into global variables this way. that's just how it is rn. 💀

---

🌈 EXAMPLES 🌈

for a whole collection of sample scripts, go see the stapex(3stap) manual page. but here's a very basic example of how to use stapdyn, step by step. 💖

first, use stap to compile a script. the stap program will report the pathname to the resulting module:

 $ stap --dyninst -p4 -e 'probe begin { printf("Hello World!\n"); exit() }'
 /home/user/.systemtap/cache/85/stap_8553d83f78c_265.so

then run stapdyn with the pathname to the module as an argument:

 $ stapdyn /home/user/.systemtap/cache/85/stap_8553d83f78c_265.so
 Hello World!

and that's it. iconic behavior, honestly. ⭐

---

🛡️ SAFETY AND SECURITY 🛡️

Systemtap, in DynInst mode, is a developer tool, and she runs completely unprivileged. the Linux kernel will only permit one's own processes to be accessed, and that's enforced by the ptrace(2) system call. 🔒

see the stap(1) manual page for additional information on safety and security. please actually read it, bestie. 🙈

---

💜 SEE ALSO 💜

stap(1), stapprobes(3stap), stap-server(8), staprun(8), stapex(3stap)

go read the whole friend group, they all ate. 👑

---

🐛 BUGS 🐛

use the Bugzilla link of the project web page, or hit up the mailing list:

http://sourceware.org/systemtap/, <systemtap@sourceware.org>

she wants to hear from you. fr fr. 🫶

---

and that's the whole page, bestie — STAPDYN(8) from the System Manager's Manual, section 8, and yeah the footer says the same thing because that's just how manpages do. no date on this one, she's timeless. mwah. 💅✨💖