DTRACE(1) General Commands Manual DTRACE(1)

# [NAME](#NAME)

dtrace - Dtrace compatible user application static probe generation tool.

# [SYNOPSIS](#SYNOPSIS)

**dtrace -s *file* \[OPTIONS]**

# [DESCRIPTION](#DESCRIPTION)

The dtrace command converts probe descriptions defined in *file.d* into a probe header file via the **-h** option or a probe description file via the **-G** option.

# [OPTIONS](#OPTIONS)

[**-h**](#h)

generate a systemtap header file.

[**-G**](#G)

generate a systemtap probe definition object file. This invokes the C compiler with a sensible set of compiler flags. If you need to add more, flags found in the **CFLAGS** environment variable will be transcribed to the compiler. If this is not enough control, use the -k option to capture the generated C file and compile as needed.

[**-o *file***](#o)

is the name of the output file. If the **-G** option is given then the output file will be called *file.o*; if the **-h** option is given then the output file will be called *file.h*.

[**-C**](#C)

run the cpp preprocessor on the input file when the **-h** option is given.

[**-I *file***](#I)

give this include path to cpp when the **-C** option is given.

[**-k**](#k)

keep temporary files, for example the C language source for the **-G** option.

# [EXAMPLES](#EXAMPLES)

Systemtap is source compatible with dtrace user application static probe support. Given a file *test.d* containing:

```
provider sdt_probes 
{


  probe test_0 (int type);


  probe test_1 (struct astruct node);
};
struct astruct {int a; int b;};
```

Then the command *"dtrace -s test.d -G"* will create the probe definition file *test.o* and the command *"dtrace -stest.d -h"* will create the probe header file *test.h* Subsequently 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));
```

# [SEMAPHORES](#SEMAPHORES)

Semaphores are flag variables used by probes as a way of bypassing potentially costly processing to prepare arguments for probes that may not even be active. They are automatically set/cleared by systemtap when a relevant script is running, so the argument setup cost is only paid when necessary. These semaphore variables are defined within the the *"test.o"* object file, which must therefore be linked into an application.

Sometimes, semaphore variables are not necessary nor helpful. 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));
```

In this mode, the ENABLED() test is fixed at 1.

# [SEE ALSO](#SEE_ALSO)

```
stap(1),
stappaths(7)
```

# [BUGS](#BUGS)

Use the Bugzilla link of the project web page or our mailing list. **http://sourceware.org/systemtap/**, **&lt;systemtap@sourceware.org&gt;**.

[*error::reporting*(7stap)](/man/enterprise-packages/systemtap/error::reporting.7stap), **https://sourceware.org/systemtap/wiki/HowToReportBugs**

---

Document: dtrace(1) from systemtap 5.6-r1 (Chainguard OS)
Source: https://sourceware.org/git/systemtap.git