DTRACE(1)

💅 DTRACE(1) — General Commands Manual ✨

okay bestie, sit down, hydrate, and let me tell you about dtrace — the Dtrace compatible user application static probe generation tool. yes that's a mouthful. it's fine. she's iconic and she knows it. 🫶

---

🌸 NAME 🌸

dtrace — the Dtrace compatible user application static probe generation tool. that's it, that's her whole job, and she does it flawlessly. 💅

---

🦋 SYNOPSIS 🦋

dtrace -s file [OPTIONS]

literally that's the shape of it. -s gives her the file, and then [OPTIONS] is where you get to be a little extra. 🌈

---

✨ DESCRIPTION ✨

so here's the tea: the dtrace command takes probe descriptions that you defined over in file.d and converts them into… something useful. specifically:

• a probe header file, if you pass the -h option 💖
• a probe description file, if you pass the -G option 🎀

that's the whole vibe. you write the probes, she does the translating. main character energy fr fr.

---

👑 OPTIONS 👑

• -h — generate a systemtap header file. slay.
• -G — generate a systemtap probe definition object file. she invokes the C compiler with a sensible set of compiler flags, because she's thoughtful like that. need to add more? flags chillin' in the CFLAGS environment variable get transcribed over to the compiler. and if that's still not enough control for you (valid, love that for you), use the -k option to capture the generated C file and compile it however you need. 💜
• -o file — this is the name of the output file. and here's the cute part: if you gave -G, the output file will be called file.o; if you gave -h, the output file will be called file.h. ✨
• -C — run the cpp preprocessor on the input file when the -h option is given.
• -I file — give this include path to cpp when the -C option is given.
• -k — keep temporary files, for example the C language source for the -G option. no takebacks, no cleanup, we keep the receipts. 🎀

---

🔥 EXAMPLES 🔥

Systemtap is source compatible with dtrace user application static probe support. ngl that's the whole point.

so say you've got a file test.d containing this:

provider sdt_probes
{
  probe test_0 (int type);
  probe test_1 (struct astruct node);
};
struct astruct {int a; int b;};

then boom:

• the command dtrace -s test.d -G will create the probe definition file test.o 🔥
• the command dtrace -stest.d -h will create the probe header file test.h ✨

subsequently (love that word, very fancy) the application can use the generated macros this way:

#include "test.h"
 ...
struct astruct s;
 ...
SDT_PROBES_TEST_0(value);
 ...
if (SDT_PROBES_TEST_1_ENABLED())
    SDT_PROBES_TEST_1(expensive_function(s));

look at those macros go. we love a generated-macro moment. 💖

---

🧚 SEMAPHORES 🧚

okay so semaphores. they're flag variables that probes use as a way of bypassing potentially costly processing — specifically, the work of preparing arguments for probes that may not even be active. why do all that cooking if nobody's eating, right? 😭

they are automatically set/cleared by systemtap when a relevant script is running, so the argument setup cost is only paid when it's actually necessary. those semaphore variables are defined within the test.o object file — which means that object file must therefore be linked into an application. no test.o, no semaphores. periodt. 💅

but sometimes? semaphore variables are not necessary nor helpful. and skipping them can simplify the build process, by omitting the extra test.o file. to skip dependence upon semaphore variables, include <sys/sdt.h> within the application before test.h:

#include <sys/sdt.h>
#include "test.h"
 ...
struct astruct s;
 ...
SDT_PROBES_TEST_0(value);
 ...
if (SDT_PROBES_TEST_1_ENABLED())
   SDT_PROBES_TEST_1(cheap_function(s));

heads up bestie: in this mode, the ENABLED() test is fixed at 1. so yeah. it's giving "always on." 🫶

---

🌈 SEE ALSO 🌈

• stap(1)
• stappaths(7)

go read them, i'll wait. 💜

---

💀 BUGS 💀

found a bug? use the Bugzilla link of the project web page or our mailing list:

• http://sourceware.org/systemtap/
• <systemtap@sourceware.org>
• error::reporting(7stap)
• https://sourceware.org/systemtap/wiki/HowToReportBugs

please actually report it and don't just suffer in silence, that's not the vibe. 🙈

---

and that's the whole page, bestie! this one came out of the General Commands Manual under the name DTRACE(1) — so yeah, dtrace(1), section 1, general commands, that's our girl. no date or version stamp on this footer, just her name in lights. k bye, go write some probes 💖✨🎀🦋🌸💅🫶