Debian Codegraph @

stapdyn/stapdyn.8

raw
1 .\" -*- nroff -*-
2 .TH STAPDYN 8
3 .SH NAME
4 stapdyn \- systemtap dyninst runtime
5
6 .SH SYNOPSIS
7
8 .br
9 .B stapdyn
10 [
11 .I OPTIONS
12 ]
13 .I MODULE
14 [
15 .I MODULE-OPTIONS
16 ]
17
18 .SH DESCRIPTION
19
20 The
21 .I stapdyn
22 program is the dyninst back-end of the Systemtap tool. It expects a
23 shared library produced by the front-end
24 .I stap
25 tool, when run with
26 .IR \-\-dyninst .
27
28 .PP
29 Splitting the systemtap tool into a front-end and a back-end allows a
30 user to compile a systemtap script on a development machine that has
31 the debugging information (need to compile the script) and then
32 transfer the resulting shared object to a production machine that
33 doesn't have any development tools or debugging information installed.
34 .PP
35 Please refer to stappaths (7) for the version number, or run
36 rpm \-q systemtap (fedora/red hat)
37 apt\-get \-v systemtap (ubuntu)
38
39 .SH OPTIONS
40 The
41 .I stapdyn
42 program supports the following options. Any other option
43 prints a list of supported options.
44 .TP
45 .B \-v
46 Verbose mode.
47 .TP
48 .B \-V
49 Print version number and exit.
50 .TP
51 .B \-w
52 Suppress warnings from the script.
53 .TP
54 .B \-c CMD
55 Command CMD will be run and the
56 .I stapdyn
57 program will exit when CMD
58 does. The '_stp_target' variable will contain the pid for CMD.
59 .TP
60 .B \-x PID
61 The '_stp_target' variable will be set to PID.
62 .TP
63 .B \-o FILE
64 Send output to FILE. If the module uses bulk mode, the output will
65 be in percpu files FILE_x(FILE_cpux in background and bulk mode)
66 where 'x' is the cpu number. This supports strftime(3) formats
67 for FILE.
68 .TP
69 .B \-C WHEN
70 Control coloring of error messages. WHEN must be either
71 .nh
72 "never", "always", or "auto"
73 .hy
74 (i.e. enable only if at a terminal). If the option is missing, then "auto"
75 is assumed. Colors can be modified using the SYSTEMTAP_COLORS environment
76 variable. See the
77 .IR stap (1)
78 manual page for more information on syntax and behaviour.
79 .TP
80 .B var1=val
81 Sets the value of global variable var1 to val. Global variables contained
82 within a script are treated as options and can be set from the
83 stapdyn command line.
84
85 .SH ARGUMENTS
86 .B MODULE
87 is either a module path or a module name. If it is a module name,
88 the module will be looked for in the following directory
89 (where 'VERSION' is the output of "uname \-r"):
90 .IP
91 /lib/modules/VERSION/systemtap
92 .PP
93
94 \& $ stap \-\-dyninst \-p4 \-m mod1 \-e\ \[aq]global var1="foo"; probe begin{printf("%s\\n", var1); exit()}\[aq]
95 .br
96 .PP
97 Running this with an additional module argument:
98 .PP
99
100 \& $ stapdyn mod1.so var1="HelloWorld"
101 .br
102 \& HelloWorld
103 .PP
104 Spaces and exclamation marks currently cannot be passed into global variables
105 this way.
106
107 .SH EXAMPLES
108 See the
109 .IR stapex (3stap)
110 manual page for a collection of sample scripts.
111 .PP
112 Here is a very basic example of how to use
113 .I stapdyn.
114 First, use
115 .I stap
116 to compile a script. The
117 .I stap
118 program will report the pathname to the resulting module.
119 .PP
120 \& $ stap \-\-dyninst \-p4 \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
121 .br
122 \& /home/user/.systemtap/cache/85/stap_8553d83f78c_265.so
123 .PP
124 Run
125 .I stapdyn
126 with the pathname to the module as an argument.
127 .PP
128 \& $ stapdyn /home/user/.systemtap/cache/85/stap_8553d83f78c_265.so
129 .br
130 \& Hello World!
131
132 .SH SAFETY AND SECURITY
133 Systemtap, in DynInst mode, is a developer tool, and runs completely
134 unprivileged. The Linux kernel will only permit one's own processes
135 to be accessed, which is enforced by the
136 .IR ptrace (2)
137 system call.
138 See the
139 .IR stap (1)
140 manual page for additional information on safety and security.
141
142 .SH SEE ALSO
143 .IR stap (1),
144 .IR stapprobes (3stap),
145 .IR stap\-server (8),
146 .IR staprun (8),
147 .IR stapex (3stap)
148
149 .SH BUGS
150 Use the Bugzilla link of the project web page or our mailing list.
151 .nh
152 .BR http://sourceware.org/systemtap/ ", " <[email protected]> .
153 .hy
154