1STAPDYN(8) System Manager's Manual STAPDYN(8)
2
6 stapdyn - systemtap dyninst runtime
7
10 stapdyn [ OPTIONS ] MODULE [ MODULE-OPTIONS ]
11
14 The stapdyn program is the dyninst back-end of the Systemtap tool. It
15 expects a shared library produced by the front-end stap tool, when run
16 with --dyninst.
17 Splitting the systemtap tool into a front-end and a back-end allows a
20 user to compile a systemtap script on a development machine that has
21 the debugging information (need to compile the script) and then trans‐
22 fer the resulting shared object to a production machine that doesn't
23 have any development tools or debugging information installed.
24 Please refer to stappaths (7) for the version number, or run rpm -q
26 systemtap (fedora/red hat) apt-get -v systemtap (ubuntu)
27
30 The stapdyn program supports the following options. Any other option
31 prints a list of supported options.
32 -v Verbose mode.
34 -V Print version number and exit.
36 -w Suppress warnings from the script.
38 -c CMD Command CMD will be run and the stapdyn program will exit when
40 CMD does. The '_stp_target' variable will contain the pid for
41 CMD.
42 -x PID The '_stp_target' variable will be set to PID.
44 -o FILE
46 Send output to FILE. If the module uses bulk mode, the output
47 will be in percpu files FILE_x(FILE_cpux in background and bulk
48 mode) where 'x' is the cpu number. This supports strftime(3)
49 formats for FILE.
50 -C WHEN
52 Control coloring of error messages. WHEN must be either "never",
53 "always", or "auto" (i.e. enable only if at a terminal). If the
54 option is missing, then "auto" is assumed. Colors can be modi‐
55 fied using the SYSTEMTAP_COLORS environment variable. See the
56 stap(1) manual page for more information on syntax and behav‐
57 iour.
58 var1=val
60 Sets the value of global variable var1 to val. Global variables
61 contained within a script are treated as options and can be set
62 from the stapdyn command line.
63
66 MODULE is either a module path or a module name. If it is a module
67 name, the module will be looked for in the following directory (where
68 'VERSION' is the output of "uname -r"):
69 /lib/modules/VERSION/systemtap
71 $ stap --dyninst -p4 -m mod1 -e 'global var1="foo"; probe be‐
73 gin{printf("%s\n", var1); exit()}'
74 Running this with an additional module argument:
76 $ stapdyn mod1.so var1="HelloWorld"
78 HelloWorld
79 Spaces and exclamation marks currently cannot be passed into global
81 variables this way.
82
85 See the stapex(3stap) manual page for a collection of sample scripts.
86 Here is a very basic example of how to use stapdyn. First, use stap to
88 compile a script. The stap program will report the pathname to the re‐
89 sulting module.
90 $ stap --dyninst -p4 -e 'probe begin { printf("Hello World!\n"); ex‐
92 it() }'
93 /home/user/.systemtap/cache/85/stap_8553d83f78c_265.so
94 Run stapdyn with the pathname to the module as an argument.
96 $ stapdyn /home/user/.systemtap/cache/85/stap_8553d83f78c_265.so
98 Hello World!
99
102 Systemtap, in DynInst mode, is a developer tool, and runs completely
103 unprivileged. The Linux kernel will only permit one's own processes to
104 be accessed, which is enforced by the ptrace(2) system call. See the
105 stap(1) manual page for additional information on safety and security.
106
109 stap(1), stapprobes(3stap), stap-server(8), staprun(8), stapex(3stap)
110
113 Use the Bugzilla link of the project web page or our mailing list.
114 http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
115 STAPDYN(8)