Debian Codegraph @

stapbpf/stapbpf.8

raw
1 .\" -*- nroff -*-
2 .TH STAPBPF 8
3 .SH NAME
4 stapbpf \- systemtap bpf runtime
5
6 .\" macros
7 .de SAMPLE
8
9 .nr oldin \\n(.i
10 .br
11 .RS
12 .nf
13 .nh
14 ..
15 .de ESAMPLE
16 .hy
17 .fi
18 .RE
19 .in \\n[oldin]u
20
21 ..
22
23
24 .SH SYNOPSIS
25
26 .br
27 .B stapbpf
28 [
29 .I OPTIONS
30 ]
31 .I MODULE
32
33 .SH DESCRIPTION
34
35 The
36 .I stapbpf
37 program is the BPF back-end of the Systemtap tool. It expects a
38 bpf-elf file produced by the front-end
39 .I stap
40 tool, when run with
41 .IR \-\-runtime=bpf .
42
43 .PP
44 Splitting the systemtap tool into a front-end and a back-end allows a
45 user to compile a systemtap script on a development machine that has
46 the debugging information needed to compile the script and then
47 transfer the resulting shared object to a production machine that
48 doesn't have any development tools or debugging information installed.
49 .PP
50 Please refer to
51 .IR stappaths (7)
52 for the version number, or run
53 .PP
54 \& $ rpm \-q systemtap # (for Fedora/RHEL)
55 .br
56 \& $ apt\-get \-v systemtap # (for Ubuntu)
57
58 .SH OPTIONS
59 The
60 .I stapbpf
61 program supports the following options. Any other option
62 prints a list of supported options.
63 .TP
64 .B \-v
65 Verbose mode.
66 .TP
67 .B \-V
68 Print version number and exit.
69 .TP
70 .B \-w
71 Suppress warnings from the script.
72 .TP
73 .B \-h
74 Print help message.
75 .TP
76 .B \-x PID
77 The '_stp_target' variable will be set to PID.
78 .TP
79 .B \-o FILE
80 Send output to FILE.
81
82 .SH ARGUMENTS
83 .B MODULE
84 is the path of a bpf-elf file produced by the front-end
85 .I stap
86 tool, when run with
87 .IR \-\-runtime=bpf .
88
89 .SH EXAMPLES
90 Here is a very basic example of how to generate a
91 .IR stapbpf
92 module.
93 First, use
94 .I stap
95 to compile a script. The
96 .I stap
97 program will report the name of the resulting module in the current
98 working directory.
99 .PP
100 \& $ stap \-\-runtime=bpf \-p4 \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
101 .br
102 \& stap_28784.bo
103 .PP
104 Run
105 .I stapbpf
106 with the pathname to the module as an argument.
107 .PP
108 \& $ stapbpf ./stap_28784.bo
109 .br
110 \& Hello World!
111 .PP
112 If the
113 .I \-p4
114 option is omitted,
115 .I stap
116 will invoke
117 .I stapbpf
118 automatically.
119
120 .SH LIMITATIONS
121 This runtime is in an early stage of development and it currently lacks
122 support for a number of features available in the default runtime.
123 A subset of the following probe points is supported:
124
125 .SAMPLE
126 begin
127 end
128 kernel.*
129 process.*
130 timer.*
131 perf.*
132 procfs.*
133 .ESAMPLE
134
135 In general, probes based on the kprobes, uprobes, tracepoint and perf
136 infrastructures are supported. See
137 .IR stapprobes (3stap)
138 for more information on the probe points and which tracing infrastructures
139 they are based on.
140
141 .B for
142 loops,
143 .B foreach
144 loops and
145 .B while
146 loops are usable only in
147 .B begin
148 and
149 .B end
150 probes.
151 .B try
152 statements are not supported.
153
154 There is limited support for string
155 operations. String variables and literals are limited to
156 64 characters, except for
157 .B printf
158 format strings, which are limited to 256 characters.
159
160 A subset of the statistical aggregate functionality is available,
161 with support only for the
162 .IR @count() ", " @sum() ", " @avg()
163 extractor functions.
164
165 The name
166 of the bpf-elf file produced by the front-end
167 .I stap
168 tool should not be changed.
169
170 .SH SAFETY AND SECURITY
171 See the
172 .IR stap (1)
173 manual page for additional information on safety and security.
174
175 .SH SEE ALSO
176 .IR stap (1),
177 .IR stapprobes (3stap),
178 .IR staprun (8),
179 .IR stapex (3stap)
180
181 .SH BUGS
182 Use the Bugzilla link of the project web page or our mailing list.
183 .nh
184 .BR http://sourceware.org/systemtap/ ", " <[email protected]> .
185 .hy