]>
Commit | Line | Data |
---|---|---|
5f92f126 | 1 | .\" t |
ec1a2239 | 2 | .TH STAPPROBES 3stap |
ba4a90fd FCE |
3 | .SH NAME |
4 | stapprobes \- systemtap probe points | |
5 | ||
6 | .\" macros | |
7 | .de SAMPLE | |
fc6851a6 JL |
8 | |
9 | .nr oldin \\n(.i | |
ba4a90fd FCE |
10 | .br |
11 | .RS | |
12 | .nf | |
13 | .nh | |
14 | .. | |
15 | .de ESAMPLE | |
16 | .hy | |
17 | .fi | |
18 | .RE | |
fc6851a6 JL |
19 | .in \\n[oldin]u |
20 | ||
ba4a90fd FCE |
21 | .. |
22 | ||
23 | .SH DESCRIPTION | |
24 | The following sections enumerate the variety of probe points supported | |
89965a32 FCE |
25 | by the systemtap translator, and some of the additional aliases defined by |
26 | standard tapset scripts. Many are individually documented in the | |
27 | .IR 3stap | |
28 | manual section, with the | |
29 | .IR probe:: | |
30 | prefix. | |
67d1ed18 FCE |
31 | |
32 | .SH SYNTAX | |
33 | ||
34 | .PP | |
35 | .SAMPLE | |
36 | .BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " } | |
37 | .ESAMPLE | |
38 | .PP | |
39 | A probe declaration may list multiple comma-separated probe points in | |
40 | order to attach a handler to all of the named events. Normally, the | |
f5dfa571 FCE |
41 | handler statements are run whenever any of events occur. Depending on |
42 | the type of probe point, the handler statements may refer to context | |
43 | variables (denoted with a dollar-sign prefix like $foo) to read or | |
44 | write state. This may include function parameters for function | |
45 | probes, or local variables for statement probes. | |
ba4a90fd | 46 | .PP |
67d1ed18 FCE |
47 | The syntax of a single probe point is a general dotted-symbol |
48 | sequence. This allows a breakdown of the event namespace into parts, | |
49 | somewhat like the Domain Name System does on the Internet. Each | |
50 | component identifier may be parametrized by a string or number | |
51 | literal, with a syntax like a function call. A component may include | |
52 | a "*" character, to expand to a set of matching probe points. It may | |
53 | also include "**" to match multiple sequential components at once. | |
54 | Probe aliases likewise expand to other probe points. | |
2f5bbffa | 55 | .PP |
67d1ed18 FCE |
56 | Probe aliases can be given on their own, or with a suffix. The suffix |
57 | attaches to the underlying probe point that the alias is expanded | |
58 | to. For example, | |
2f5bbffa SM |
59 | .SAMPLE |
60 | syscall.read.return.maxactive(10) | |
61 | .ESAMPLE | |
62 | expands to | |
63 | .SAMPLE | |
64 | kernel.function("sys_read").return.maxactive(10) | |
65 | .ESAMPLE | |
66 | with the component | |
67 | .IR maxactive(10) | |
68 | being recognized as a suffix. | |
69 | .PP | |
67d1ed18 FCE |
70 | Normally, each and every probe point resulting from wildcard- and |
71 | alias-expansion must be resolved to some low-level system | |
72 | instrumentation facility (e.g., a kprobe address, marker, or a timer | |
73 | configuration), otherwise the elaboration phase will fail. | |
d898100a FCE |
74 | .PP |
75 | However, a probe point may be followed by a "?" character, to indicate | |
76 | that it is optional, and that no error should result if it fails to | |
77 | resolve. Optionalness passes down through all levels of | |
78 | alias/wildcard expansion. Alternately, a probe point may be followed | |
79 | by a "!" character, to indicate that it is both optional and | |
37f6433e | 80 | sufficient. (Think vaguely of the Prolog cut operator.) If it does |
d898100a FCE |
81 | resolve, then no further probe points in the same comma-separated list |
82 | will be resolved. Therefore, the "!" sufficiency mark only makes | |
83 | sense in a list of probe point alternatives. | |
dfd11cc3 MH |
84 | .PP |
85 | Additionally, a probe point may be followed by a "if (expr)" statement, in | |
86 | order to enable/disable the probe point on-the-fly. With the "if" statement, | |
87 | if the "expr" is false when the probe point is hit, the whole probe body | |
88 | including alias's body is skipped. The condition is stacked up through | |
89 | all levels of alias/wildcard expansion. So the final condition becomes | |
67d1ed18 FCE |
90 | the logical-and of conditions of all expanded alias/wildcard. The expressions |
91 | are necessarily restricted to global variables. | |
92 | .PP | |
e904ad95 FCE |
93 | These are all |
94 | .B syntactically | |
95 | valid probe points. (They are generally | |
96 | .B semantically | |
97 | invalid, depending on the contents of the tapsets, and the versions of | |
98 | kernel/user software installed.) | |
ca88561f | 99 | |
ba4a90fd FCE |
100 | .SAMPLE |
101 | kernel.function("foo").return | |
e904ad95 | 102 | process("/bin/vi").statement(0x2222) |
ba4a90fd | 103 | end |
729286d8 | 104 | syscall.* |
2f5bbffa | 105 | syscall.*.return.maxactive(10) |
380d759b | 106 | syscall.{open,close} |
649260f3 | 107 | sys**open |
6e3347a9 | 108 | kernel.function("no_such_function") ? |
d898100a | 109 | module("awol").function("no_such_function") ! |
dfd11cc3 | 110 | signal.*? if (switch) |
94c3c803 | 111 | kprobe.function("foo") |
ba4a90fd FCE |
112 | .ESAMPLE |
113 | ||
6f05b6ab FCE |
114 | Probes may be broadly classified into "synchronous" and |
115 | "asynchronous". A "synchronous" event is deemed to occur when any | |
116 | processor executes an instruction matched by the specification. This | |
117 | gives these probes a reference point (instruction address) from which | |
118 | more contextual data may be available. Other families of probe points | |
119 | refer to "asynchronous" events such as timers/counters rolling over, | |
120 | where there is no fixed reference point that is related. Each probe | |
121 | point specification may match multiple locations (for example, using | |
122 | wildcards or aliases), and all them are then probed. A probe | |
123 | declaration may also contain several comma-separated specifications, | |
124 | all of which are probed. | |
125 | ||
380d759b FL |
126 | Brace expansion is a mechanism which allows a list of probe points to be |
127 | generated. It is very similar to shell expansion. A component may be surrounded | |
128 | by a pair of curly braces to indicate that the comma-separated sequence of | |
129 | one or more subcomponents will each constitute a new probe point. The braces | |
130 | may be arbitrarily nested. The ordering of expanded results is based on | |
131 | product order. | |
132 | ||
133 | The question mark (?), exclamation mark (!) indicators and probe point conditions | |
134 | may not be placed in any expansions that are before the last component. | |
135 | ||
136 | The following is an example of brace expansion. | |
137 | ||
138 | .SAMPLE | |
139 | syscall.{write,read} | |
140 | # Expands to | |
141 | syscall.write, syscall.read | |
142 | ||
143 | {kernel,module("nfs")}.function("nfs*")! | |
144 | # Expands to | |
145 | kernel.function("nfs*")!, module("nfs").function("nfs*")! | |
146 | .ESAMPLE | |
147 | ||
5f92f126 FCE |
148 | .SH DWARF DEBUGINFO |
149 | ||
150 | Resolving some probe points requires DWARF debuginfo or "debug | |
c5ae4566 | 151 | symbols" for the \fIspecific program\fR being instrumented. For some others, |
5f92f126 FCE |
152 | DWARF is automatically synthesized on the fly from source code header |
153 | files. For others, it is not needed at all. Since a systemtap script | |
154 | may use any mixture of probe points together, the union of their DWARF | |
155 | requirements has to be met on the computer where script compilation | |
156 | occurs. (See the \fI\-\-use\-server\fR option and the \fBstap-server\ | |
157 | (8)\fR man page for information about the remote compilation facility, | |
158 | which allows these requirements to be met on a different machine.) | |
159 | .PP | |
160 | The following point lists many of the available probe point families, | |
c5ae4566 FCE |
161 | to classify them with respect to their need for DWARF debuginfo for |
162 | the specific program for that probe point. | |
5f92f126 FCE |
163 | |
164 | .TS | |
165 | l l l. | |
c899cb78 | 166 | \fBDWARF NON-DWARF SYMBOL-TABLE\fP |
5f92f126 | 167 | |
c899cb78 FCE |
168 | kernel.function, .statement kernel.mark kernel.function\fI*\fP |
169 | module.function, .statement process.mark, process.plt module.function\fI*\fP | |
170 | process.function, .statement begin, end, error, never process.function\fI*\fP | |
171 | process.mark\fI*\fP timer | |
172 | \.function.callee perf | |
7bfd1083 | 173 | procfs |
30b02257 | 174 | \fBAUTO-GENERATED-DWARF\fP kernel.statement.absolute |
7bfd1083 TJL |
175 | kernel.data |
176 | kernel.trace kprobe.function | |
177 | process.statement.absolute | |
94fe8dd0 | 178 | process.begin, .end |
30b02257 FCE |
179 | netfilter |
180 | java | |
5f92f126 FCE |
181 | .TE |
182 | ||
c899cb78 FCE |
183 | .PP |
184 | The probe types marked with \fI*\fP asterisks mark fallbacks, where | |
185 | systemtap can sometimes infer subset or substitute information. In | |
186 | general, the more symbolic / debugging information available, the | |
187 | higher quality probing will be available. | |
188 | ||
189 | ||
94fe8dd0 FCE |
190 | .SH ON-THE-FLY ARMING |
191 | ||
192 | The following types of probe points may be armed/disarmed on-the-fly | |
193 | to save overheads during uninteresting times. Arming conditions may | |
194 | also be added to other types of probes, but will be treated as a | |
195 | wrapping conditional and won't benefit from overhead savings. | |
196 | ||
197 | .TS | |
198 | l l. | |
199 | \fBDISARMABLE exceptions\fP | |
94fe8dd0 FCE |
200 | kernel.function, kernel.statement |
201 | module.function, module.statement | |
202 | process.*.function, process.*.statement | |
203 | process.*.plt, process.*.mark | |
85176706 | 204 | timer. timer.profile |
94fe8dd0 FCE |
205 | java |
206 | .TE | |
207 | ||
5f92f126 FCE |
208 | .SH PROBE POINT FAMILIES |
209 | ||
65aeaea0 | 210 | .SS BEGIN/END/ERROR |
ba4a90fd FCE |
211 | |
212 | The probe points | |
213 | .IR begin " and " end | |
214 | are defined by the translator to refer to the time of session startup | |
215 | and shutdown. All "begin" probe handlers are run, in some sequence, | |
216 | during the startup of the session. All global variables will have | |
217 | been initialized prior to this point. All "end" probes are run, in | |
218 | some sequence, during the | |
219 | .I normal | |
220 | shutdown of a session, such as in the aftermath of an | |
221 | .I exit () | |
222 | function call, or an interruption from the user. In the case of an | |
223 | error-triggered shutdown, "end" probes are not run. There are no | |
224 | target variables available in either context. | |
6a256b03 JS |
225 | .PP |
226 | If the order of execution among "begin" or "end" probes is significant, | |
227 | then an optional sequence number may be provided: | |
ca88561f | 228 | |
6a256b03 JS |
229 | .SAMPLE |
230 | begin(N) | |
231 | end(N) | |
232 | .ESAMPLE | |
ca88561f | 233 | |
6a256b03 JS |
234 | The number N may be positive or negative. The probe handlers are run in |
235 | increasing order, and the order between handlers with the same sequence | |
236 | number is unspecified. When "begin" or "end" are given without a | |
237 | sequence, they are effectively sequence zero. | |
ba4a90fd | 238 | |
65aeaea0 FCE |
239 | The |
240 | .IR error | |
241 | probe point is similar to the | |
242 | .IR end | |
d898100a FCE |
243 | probe, except that each such probe handler run when the session ends |
244 | after errors have occurred. In such cases, "end" probes are skipped, | |
37f6433e | 245 | but each "error" probe is still attempted. This kind of probe can be |
d898100a FCE |
246 | used to clean up or emit a "final gasp". It may also be numerically |
247 | parametrized to set a sequence. | |
65aeaea0 | 248 | |
6e3347a9 FCE |
249 | .SS NEVER |
250 | The probe point | |
251 | .IR never | |
252 | is specially defined by the translator to mean "never". Its probe | |
253 | handler is never run, though its statements are analyzed for symbol / | |
254 | type correctness as usual. This probe point may be useful in | |
255 | conjunction with optional probes. | |
256 | ||
bafd76f1 | 257 | .SS SYSCALL and ND_SYSCALL |
1027502b FCE |
258 | |
259 | The | |
bafd76f1 | 260 | .IR syscall.* " and " nd_syscall.* |
1027502b | 261 | aliases define several hundred probes, too many to |
56bd0316 | 262 | detail here. They are of the general form: |
1027502b FCE |
263 | |
264 | .SAMPLE | |
265 | syscall.NAME | |
266 | .br | |
bafd76f1 FCE |
267 | nd_syscall.NAME |
268 | .br | |
1027502b | 269 | syscall.NAME.return |
bafd76f1 FCE |
270 | .br |
271 | nd_syscall.NAME.return | |
1027502b FCE |
272 | .ESAMPLE |
273 | ||
bafd76f1 | 274 | Generally, a pair of probes are defined for each normal system call as listed in the |
1027502b FCE |
275 | .IR syscalls(2) |
276 | manual page, one for entry and one for return. Those system calls that never | |
277 | return do not have a corresponding | |
278 | .IR .return | |
bafd76f1 FCE |
279 | probe. The nd_* family of probes are about the same, except it uses |
280 | .B non-DWARF | |
281 | based searching mechanisms, which may result in a lower quality of symbolic | |
282 | context data (parameters), and may miss some system calls. You may want to | |
283 | try them first, in case kernel debugging information is not immediately available. | |
1027502b | 284 | .PP |
df7f3a01 | 285 | Each probe alias provides a variety of variables. Looking at the tapset source |
1027502b FCE |
286 | code is the most reliable way. Generally, each variable listed in the standard |
287 | manual page is made available as a script-level variable, so | |
288 | .IR syscall.open | |
289 | exposes | |
290 | .IR filename ", " flags ", and " mode . | |
291 | In addition, a standard suite of variables is available at most aliases: | |
292 | .TP | |
293 | .IR argstr | |
294 | A pretty-printed form of the entire argument list, without parentheses. | |
295 | .TP | |
296 | .IR name | |
297 | The name of the system call. | |
298 | .TP | |
299 | .IR retstr | |
300 | For return probes, a pretty-printed form of the system-call result. | |
301 | .PP | |
08d1d743 FCE |
302 | As usual for probe aliases, these variables are all initialized once |
303 | from the underlying $context variables, so that later changes to | |
df7f3a01 FCE |
304 | $context variables are not automatically reflected. Not all probe |
305 | aliases obey all of these general guidelines. Please report any | |
08d1d743 FCE |
306 | bothersome ones you encounter as a bug. Note that on some |
307 | kernel/userspace architecture combinations (e.g., 32-bit userspace on | |
308 | 64-bit kernel), the underlying $context variables may need explicit | |
309 | sign extension / masking. When this is an issue, consider using the | |
310 | tapset-provided variables instead of raw $context variables. | |
c34eceea FCE |
311 | .PP |
312 | If debuginfo availability is a problem, you may try using the | |
313 | non-DWARF syscall probe aliases instead. Use the | |
314 | .IR nd_syscall. | |
315 | prefix instead of | |
316 | .IR syscall. | |
317 | The same context variables are available, as far as possible. | |
1027502b | 318 | |
ba4a90fd FCE |
319 | .SS TIMERS |
320 | ||
42b97387 DS |
321 | There are two main types of timer probes: "jiffies" timer probes and |
322 | time interval timer probes. | |
323 | ||
ba4a90fd FCE |
324 | Intervals defined by the standard kernel "jiffies" timer may be used |
325 | to trigger probe handlers asynchronously. Two probe point variants | |
326 | are supported by the translator: | |
ca88561f | 327 | |
ba4a90fd FCE |
328 | .SAMPLE |
329 | timer.jiffies(N) | |
330 | timer.jiffies(N).randomize(M) | |
331 | .ESAMPLE | |
ca88561f | 332 | |
ba4a90fd FCE |
333 | The probe handler is run every N jiffies (a kernel-defined unit of |
334 | time, typically between 1 and 60 ms). If the "randomize" component is | |
13d2ecdb | 335 | given, a linearly distributed random value in the range [\-M..+M] is |
ba4a90fd FCE |
336 | added to N every time the handler is run. N is restricted to a |
337 | reasonable range (1 to around a million), and M is restricted to be | |
338 | smaller than N. There are no target variables provided in either | |
339 | context. It is possible for such probes to be run concurrently on | |
340 | a multi-processor computer. | |
422d1ceb | 341 | .PP |
197a4d62 | 342 | Alternatively, intervals may be specified in units of time. |
422d1ceb | 343 | There are two probe point variants similar to the jiffies timer: |
ca88561f | 344 | |
422d1ceb FCE |
345 | .SAMPLE |
346 | timer.ms(N) | |
347 | timer.ms(N).randomize(M) | |
348 | .ESAMPLE | |
ca88561f | 349 | |
197a4d62 JS |
350 | Here, N and M are specified in milliseconds, but the full options for units |
351 | are seconds (s/sec), milliseconds (ms/msec), microseconds (us/usec), | |
352 | nanoseconds (ns/nsec), and hertz (hz). Randomization is not supported for | |
353 | hertz timers. | |
354 | ||
355 | The actual resolution of the timers depends on the target kernel. For | |
356 | kernels prior to 2.6.17, timers are limited to jiffies resolution, so | |
357 | intervals are rounded up to the nearest jiffies interval. After 2.6.17, | |
358 | the implementation uses hrtimers for tighter precision, though the actual | |
359 | resolution will be arch-dependent. In either case, if the "randomize" | |
360 | component is given, then the random value will be added to the interval | |
361 | before any rounding occurs. | |
39e57ce0 | 362 | .PP |
ab8b5560 | 363 | Profiling timers are also available to provide probes that execute on |
07c818a0 FL |
364 | all CPUs at the rate of the system tick (CONFIG_HZ) or at a given |
365 | frequency (hz). On some kernels, this is a one-concurrent-user-only or | |
e996e76a | 366 | disabled facility, resulting in error \-16 (EBUSY) during probe |
ab8b5560 | 367 | registration. |
ca88561f | 368 | |
39e57ce0 | 369 | .SAMPLE |
acf7bde9 | 370 | timer.profile.tick |
07c818a0 | 371 | timer.profile.freq.hz(N) |
39e57ce0 | 372 | .ESAMPLE |
ca88561f | 373 | |
39e57ce0 FCE |
374 | Full context information of the interrupted process is available, making |
375 | this probe suitable for a time-based sampling profiler. | |
acf7bde9 SM |
376 | .PP |
377 | It is recommended to use the tapset probe | |
378 | .IR timer.profile | |
379 | rather than timer.profile.tick. This probe point behaves identically | |
380 | to timer.profile.tick when the underlying functionality is available, | |
381 | and falls back to using perf.sw.cpu_clock on some recent kernels which | |
382 | lack the corresponding profile timer facility. | |
07c818a0 FL |
383 | .PP |
384 | Profiling timers with specified frequencies are only accurate up to around | |
385 | 100 hz. You may need to provide a larger value to achieve the desired | |
386 | rate. | |
42b97387 DS |
387 | .PP |
388 | Note that if a timer probe is set to fire at a very high rate | |
389 | and if the probe body is complex, succeeding timer probes can get | |
390 | skipped, since the time for them to run has already passed. Normally | |
391 | systemtap reports missed probes, but it will not report these skipped | |
392 | probes. | |
ba4a90fd FCE |
393 | |
394 | .SS DWARF | |
395 | ||
396 | This family of probe points uses symbolic debugging information for | |
397 | the target kernel/module/program, as may be found in unstripped | |
398 | executables, or the separate | |
399 | .I debuginfo | |
400 | packages. They allow placement of probes logically into the execution | |
401 | path of the target program, by specifying a set of points in the | |
402 | source or object code. When a matching statement executes on any | |
403 | processor, the probe handler is run in that context. | |
404 | .PP | |
7c86df9f JL |
405 | Probe points in the DWARF family can be identified by the target kernel |
406 | module (or user process), source file, line number, function name, or | |
407 | some combination of these. | |
408 | .PP | |
409 | Here is a list of DWARF probe points currently supported: | |
ba4a90fd FCE |
410 | .SAMPLE |
411 | kernel.function(PATTERN) | |
b8da0ad1 | 412 | kernel.function(PATTERN).call |
7c86df9f | 413 | kernel.function(PATTERN).callee(PATTERN) |
f0e06c0d FL |
414 | kernel.function(PATTERN).callee(PATTERN).return |
415 | kernel.function(PATTERN).callee(PATTERN).call | |
7c86df9f | 416 | kernel.function(PATTERN).callees(DEPTH) |
ba4a90fd | 417 | kernel.function(PATTERN).return |
b8da0ad1 | 418 | kernel.function(PATTERN).inline |
592470cd | 419 | kernel.function(PATTERN).label(LPATTERN) |
ba4a90fd | 420 | module(MPATTERN).function(PATTERN) |
b8da0ad1 | 421 | module(MPATTERN).function(PATTERN).call |
7c86df9f | 422 | module(MPATTERN).function(PATTERN).callee(PATTERN) |
f0e06c0d FL |
423 | module(MPATTERN).function(PATTERN).callee(PATTERN).return |
424 | module(MPATTERN).function(PATTERN).callee(PATTERN).call | |
7c86df9f | 425 | module(MPATTERN).function(PATTERN).callees(DEPTH) |
ba4a90fd | 426 | module(MPATTERN).function(PATTERN).return |
b8da0ad1 | 427 | module(MPATTERN).function(PATTERN).inline |
2cab6244 | 428 | module(MPATTERN).function(PATTERN).label(LPATTERN) |
ba4a90fd | 429 | kernel.statement(PATTERN) |
5e758862 | 430 | kernel.statement(PATTERN).nearest |
37ebca01 | 431 | kernel.statement(ADDRESS).absolute |
ba4a90fd | 432 | module(MPATTERN).statement(PATTERN) |
6f017dee | 433 | process("PATH").function("NAME") |
6f017dee | 434 | process("PATH").statement("*@FILE.c:123") |
b73a1293 | 435 | process("PATH").library("PATH").function("NAME") |
b73a1293 | 436 | process("PATH").library("PATH").statement("*@FILE.c:123") |
5e758862 | 437 | process("PATH").library("PATH").statement("*@FILE.c:123").nearest |
6f017dee | 438 | process("PATH").function("*").return |
6f017dee | 439 | process("PATH").function("myfun").label("foo") |
7c86df9f | 440 | process("PATH").function("foo").callee("bar") |
f0e06c0d FL |
441 | process("PATH").function("foo").callee("bar").return |
442 | process("PATH").function("foo").callee("bar").call | |
7c86df9f | 443 | process("PATH").function("foo").callees(DEPTH) |
af127b9f AJ |
444 | process(PID).function("NAME") |
445 | process(PID).function("myfun").label("foo") | |
2e96714f SC |
446 | process(PID).plt("NAME") |
447 | process(PID).plt("NAME").return | |
af127b9f | 448 | process(PID).statement("*@FILE.c:123") |
5e758862 | 449 | process(PID).statement("*@FILE.c:123").nearest |
5fa99496 | 450 | process(PID).statement(ADDRESS).absolute |
ba4a90fd | 451 | .ESAMPLE |
6f017dee FCE |
452 | (See the USER-SPACE section below for more information on the process |
453 | probes.) | |
7c86df9f JL |
454 | .PP |
455 | The list above includes multiple variants and modifiers which provide | |
456 | additional functionality or filters. They are: | |
457 | .RS | |
458 | .TP | |
459 | \fB.function\fR | |
460 | Places a probe near the beginning of the named function, so that | |
461 | parameters are available as context variables. | |
462 | .TP | |
463 | \fB.return\fR | |
464 | Places a probe at the moment \fBafter\fR the return from the named | |
465 | function, so the return value is available as the "$return" context | |
466 | variable. | |
467 | .TP | |
468 | \fB.inline\fR | |
469 | Filters the results to include only instances of inlined functions. Note | |
7f357865 | 470 | that inlined functions do not have an identifiable return point, so |
7c86df9f JL |
471 | \fB.return\fR is not supported on \fB.inline\fR probes. |
472 | .TP | |
473 | \fB.call\fR | |
474 | Filters the results to include only non-inlined functions (the opposite | |
475 | set of \fB.inline\fR) | |
476 | .TP | |
477 | \fB.exported\fR | |
478 | Filters the results to include only exported functions. | |
479 | .TP | |
7c86df9f | 480 | \fB.statement\fR |
7f357865 | 481 | Places a probe at the exact spot, exposing those local variables that |
7c86df9f JL |
482 | are visible there. |
483 | .TP | |
5e758862 | 484 | \fB.statement.nearest\fR |
18abf95e JL |
485 | Places a probe at the nearest available line number for each line number |
486 | given in the statement. | |
5e758862 | 487 | .TP |
7c86df9f JL |
488 | \fB.callee\fR |
489 | Places a probe on the callee function given in the \fB.callee\fR | |
490 | modifier, where the callee must be a function called by the target | |
491 | function given in \fB.function\fR. The advantage of doing this over | |
492 | directly probing the callee function is that this probe point is run | |
493 | only when the callee is called from the target function (add the | |
494 | -DSTAP_CALLEE_MATCHALL directive to override this when calling | |
495 | \fBstap\fR(1)). | |
496 | ||
497 | Note that only callees that can be statically determined are available. | |
498 | For example, calls through function pointers are not available. | |
499 | Additionally, calls to functions located in other objects (e.g. | |
074c54b6 JL |
500 | libraries) are not available (instead use another probe point). This |
501 | feature will only work for code compiled with GCC 4.7+. | |
7c86df9f JL |
502 | .TP |
503 | \fB.callees\fR | |
504 | Shortcut for \fB.callee("*")\fR, which places a probe on all callees of | |
505 | the function. | |
506 | .TP | |
507 | \fB.callees\fR(DEPTH) | |
508 | Recursively places probes on callees. For example, \fB.callees(2)\fR | |
509 | will probe both callees of the target function, as well as callees of | |
510 | those callees. And \fB.callees(3)\fR goes one level deeper, etc... | |
511 | A callee probe at depth N is only triggered when the N callers in the | |
512 | callstack match those that were statically determined during analysis | |
69b254f2 | 513 | (this also may be overridden using -DSTAP_CALLEE_MATCHALL). |
7c86df9f JL |
514 | .RE |
515 | .PP | |
516 | In the above list of probe points, MPATTERN stands for a string literal | |
00468ace JL |
517 | that aims to identify the loaded kernel module of interest. For in-tree |
518 | kernel modules, the name suffices (e.g. "btrfs"). The name may also | |
519 | include the "*", "[]", and "?" wildcards to match multiple in-tree | |
520 | modules. Out-of-tree modules are also supported by specifying the full | |
521 | path to the ko file. Wildcards are not supported. The file must follow | |
522 | the convention of being named <module_name>.ko (characters ',' and '-' | |
523 | are replaced by '_'). | |
524 | .PP | |
525 | LPATTERN stands for a source program label. It may also contain "*", | |
526 | "[]", and "?" wildcards. PATTERN stands for a string literal that aims | |
527 | to identify a point in the program. It is made up of three parts: | |
ca88561f MM |
528 | .IP \(bu 4 |
529 | The first part is the name of a function, as would appear in the | |
ba4a90fd FCE |
530 | .I nm |
531 | program's output. This part may use the "*" and "?" wildcarding | |
ca88561f MM |
532 | operators to match multiple names. |
533 | .IP \(bu 4 | |
534 | The second part is optional and begins with the "@" character. | |
535 | It is followed by the path to the source file containing the function, | |
536 | which may include a wildcard pattern, such as mm/slab*. | |
79640c29 | 537 | If it does not match as is, an implicit "*/" is optionally added |
ea384b8c | 538 | .I before |
79640c29 FCE |
539 | the pattern, so that a script need only name the last few components |
540 | of a possibly long source directory path. | |
ca88561f | 541 | .IP \(bu 4 |
ba4a90fd | 542 | Finally, the third part is optional if the file name part was given, |
1bd128a3 SC |
543 | and identifies the line number in the source file preceded by a ":" |
544 | or a "+". The line number is assumed to be an | |
775ccddf JL |
545 | absolute line number if preceded by a ":", or relative to the |
546 | declaration line of the function if preceded by a "+". | |
99a5f9cf | 547 | All the lines in the function can be matched with ":*". |
354ddff1 JL |
548 | A range of lines x through y can be matched with ":x\-y". Ranges and |
549 | specific lines can be mixed using commas, e.g. ":x,y\-z". | |
ca88561f | 550 | .PP |
ba4a90fd | 551 | As an alternative, PATTERN may be a numeric constant, indicating an |
ea384b8c FCE |
552 | address. Such an address may be found from symbol tables of the |
553 | appropriate kernel / module object file. It is verified against | |
554 | known statement code boundaries, and will be relocated for use at | |
555 | run time. | |
556 | .PP | |
557 | In guru mode only, absolute kernel-space addresses may be specified with | |
558 | the ".absolute" suffix. Such an address is considered already relocated, | |
559 | as if it came from | |
560 | .BR /proc/kallsyms , | |
561 | so it cannot be checked against statement/instruction boundaries. | |
6f017dee FCE |
562 | .SS CONTEXT VARIABLES |
563 | ||
ba4a90fd | 564 | .PP |
6f017dee | 565 | Many of the source-level context variables, such as function parameters, |
ba4a90fd FCE |
566 | locals, globals visible in the compilation unit, may be visible to |
567 | probe handlers. They may refer to these variables by prefixing their | |
568 | name with "$" within the scripts. In addition, a special syntax | |
6f017dee FCE |
569 | allows limited traversal of structures, pointers, and arrays. More |
570 | syntax allows pretty-printing of individual variables or their groups. | |
571 | See also | |
572 | .BR @cast . | |
f8b9be91 FCE |
573 | Note that variables may be inaccessible due to them being paged out, |
574 | or for a few other reasons. See also man | |
575 | .IR error::fault (7stap). | |
6f017dee | 576 | |
ba4a90fd FCE |
577 | .TP |
578 | $var | |
579 | refers to an in-scope variable "var". If it's an integer-like type, | |
7b9361d5 FCE |
580 | it will be cast to a 64-bit int for systemtap script use. String-like |
581 | pointers (char *) may be copied to systemtap string values using the | |
582 | .IR kernel_string " or " user_string | |
583 | functions. | |
ba4a90fd | 584 | .TP |
179a00c3 MW |
585 | @var("varname") |
586 | an alternative syntax for | |
587 | .IR $varname | |
588 | . | |
589 | .TP | |
590 | @var("varname@src/file.c") | |
591 | refers to the global (either file local or external) variable | |
592 | .IR varname | |
593 | defined when the file | |
594 | .IR src/file.c | |
595 | was compiled. The CU in which the variable is resolved is the first CU | |
596 | in the module of the probe point which matches the given file name at | |
597 | the end and has the shortest file name path (e.g. given | |
598 | .IR @var("foo@bar/baz.c") | |
599 | and CUs with file name paths | |
600 | .IR src/sub/module/bar/baz.c | |
601 | and | |
602 | .IR src/bar/baz.c | |
603 | the second CU will be chosen to resolve the (file) global variable | |
604 | .IR foo | |
605 | . | |
606 | .TP | |
ab5e90c2 FCE |
607 | $var\->field traversal via a structure's or a pointer's field. This |
608 | generalized indirection operator may be repeated to follow more | |
609 | levels. Note that the | |
610 | .IR . | |
611 | operator is not used for plain structure | |
612 | members, only | |
613 | .IR \-> | |
614 | for both purposes. (This is because "." is reserved for string | |
615 | concatenation.) | |
ba4a90fd | 616 | .TP |
a43ba433 FCE |
617 | $return |
618 | is available in return probes only for functions that are declared | |
462a0d51 | 619 | with a return value, which can be determined using @defined($return). |
a43ba433 | 620 | .TP |
ba4a90fd | 621 | $var[N] |
33b081c5 JS |
622 | indexes into an array. The index given with a literal number or even |
623 | an arbitrary numeric expression. | |
6f017dee FCE |
624 | .PP |
625 | A number of operators exist for such basic context variable expressions: | |
34af38db | 626 | .TP |
2cb3fe26 SC |
627 | $$vars |
628 | expands to a character string that is equivalent to | |
6f017dee FCE |
629 | .SAMPLE |
630 | sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x", | |
631 | parm1, ..., parmN, var1, ..., varN) | |
632 | .ESAMPLE | |
633 | for each variable in scope at the probe point. Some values may be | |
634 | printed as | |
635 | .IR =? | |
636 | if their run-time location cannot be found. | |
2cb3fe26 SC |
637 | .TP |
638 | $$locals | |
a43ba433 | 639 | expands to a subset of $$vars for only local variables. |
2cb3fe26 SC |
640 | .TP |
641 | $$parms | |
a43ba433 FCE |
642 | expands to a subset of $$vars for only function parameters. |
643 | .TP | |
644 | $$return | |
645 | is available in return probes only. It expands to a string that | |
fd574705 | 646 | is equivalent to sprintf("return=%x", $return) |
a43ba433 | 647 | if the probed function has a return value, or else an empty string. |
6f017dee FCE |
648 | .TP |
649 | & $EXPR | |
650 | expands to the address of the given context variable expression, if it | |
651 | is addressable. | |
652 | .TP | |
653 | @defined($EXPR) | |
654 | expands to 1 or 0 iff the given context variable expression is resolvable, | |
655 | for use in conditionals such as | |
656 | .SAMPLE | |
f7470174 | 657 | @defined($foo\->bar) ? $foo\->bar : 0 |
6f017dee FCE |
658 | .ESAMPLE |
659 | .TP | |
660 | $EXPR$ | |
661 | expands to a string with all of $EXPR's members, equivalent to | |
662 | .SAMPLE | |
663 | sprintf("{.a=%i, .b=%u, .c={...}, .d=[...]}", | |
664 | $EXPR\->a, $EXPR\->b) | |
665 | .ESAMPLE | |
666 | .TP | |
667 | $EXPR$$ | |
668 | expands to a string with all of $var's members and submembers, equivalent to | |
669 | .SAMPLE | |
670 | sprintf("{.a=%i, .b=%u, .c={.x=%p, .y=%c}, .d=[%i, ...]}", | |
671 | $EXPR\->a, $EXPR\->b, $EXPR\->c\->x, $EXPR\->c\->y, $EXPR\->d[0]) | |
672 | .ESAMPLE | |
673 | ||
3f5a5bb1 FCE |
674 | .SS MORE ON RETURN PROBES |
675 | ||
676 | .PP | |
677 | For the kernel ".return" probes, only a certain fixed number of | |
678 | returns may be outstanding. The default is a relatively small number, | |
679 | on the order of a few times the number of physical CPUs. If many | |
680 | different threads concurrently call the same blocking function, such | |
681 | as futex(2) or read(2), this limit could be exceeded, and skipped | |
e996e76a | 682 | "kretprobes" would be reported by "stap \-t". To work around this, |
3f5a5bb1 FCE |
683 | specify a |
684 | .SAMPLE | |
685 | probe FOO.return.maxactive(NNN) | |
686 | .ESAMPLE | |
687 | suffix, with a large enough NNN to cover all expected concurrently blocked | |
688 | threads. Alternately, use the | |
689 | .SAMPLE | |
e996e76a | 690 | stap \-DKRETACTIVE=NNNN |
3f5a5bb1 FCE |
691 | .ESAMPLE |
692 | stap command line macro setting to override the default for all | |
693 | ".return" probes. | |
1c0b8e23 | 694 | |
39e3139a | 695 | .PP |
1c0b8e23 FCE |
696 | For ".return" probes, context variables other than the "$return" may |
697 | be accessible, as a convenience for a script programmer wishing to | |
698 | access function parameters. These values are \fBsnapshots\fP | |
d1025fe6 | 699 | taken at the time of function entry. (Local variables within the |
1c0b8e23 | 700 | function are \fBnot\fP generally accessible, since those variables did |
d1025fe6 FCE |
701 | not exist in allocated/initialized form at the snapshot moment.) |
702 | These entry-snapshot variables should be accessed via | |
703 | .IR @entry($var) . | |
8cc799a5 | 704 | .PP |
1c0b8e23 FCE |
705 | In addition, arbitrary entry-time expressions can also be saved for |
706 | ".return" probes using the | |
8cc799a5 JS |
707 | .IR @entry(expr) |
708 | operator. For example, one can compute the elapsed time of a function: | |
709 | .SAMPLE | |
710 | probe kernel.function("do_filp_open").return { | |
711 | println( get_timeofday_us() \- @entry(get_timeofday_us()) ) | |
712 | } | |
713 | .ESAMPLE | |
39e3139a | 714 | |
1c0b8e23 FCE |
715 | .PP |
716 | The following table summarizes how values related to a function | |
717 | parameter context variable, a pointer named \fBaddr\fP, may be | |
718 | accessed from a | |
719 | .IR .return | |
720 | probe. | |
721 | .\" summarized from http://sourceware.org/ml/systemtap/2012-q1/msg00025.html | |
722 | .TS | |
723 | l l l. | |
724 | \fBat-entry value past-exit value\fP | |
725 | ||
726 | $addr \fInot available\fP | |
727 | $addr->x->y @cast(@entry($addr),"struct zz")->x->y | |
728 | $addr[0] {kernel,user}_{char,int,...}(& $addr[0]) | |
729 | .TE | |
730 | ||
ba4a90fd | 731 | |
94c3c803 AM |
732 | .SS DWARFLESS |
733 | In absence of debugging information, entry & exit points of kernel & module | |
734 | functions can be probed using the "kprobe" family of probes. | |
735 | However, these do not permit looking up the arguments / local variables | |
736 | of the function. | |
737 | Following constructs are supported : | |
738 | .SAMPLE | |
739 | kprobe.function(FUNCTION) | |
3c57fe1f | 740 | kprobe.function(FUNCTION).call |
94c3c803 AM |
741 | kprobe.function(FUNCTION).return |
742 | kprobe.module(NAME).function(FUNCTION) | |
3c57fe1f | 743 | kprobe.module(NAME).function(FUNCTION).call |
94c3c803 | 744 | kprobe.module(NAME).function(FUNCTION).return |
6448e5a5 | 745 | kprobe.statement(ADDRESS).absolute |
94c3c803 AM |
746 | .ESAMPLE |
747 | .PP | |
748 | Probes of type | |
749 | .B function | |
750 | are recommended for kernel functions, whereas probes of type | |
751 | .B module | |
752 | are recommended for probing functions of the specified module. | |
753 | In case the absolute address of a kernel or module function is known, | |
754 | .B statement | |
755 | probes can be utilized. | |
756 | .PP | |
757 | Note that | |
758 | .I FUNCTION | |
759 | and | |
760 | .I MODULE | |
761 | names | |
762 | .B must not | |
763 | contain wildcards, or the probe will not be registered. | |
764 | Also, statement probes must be run under guru-mode only. | |
765 | ||
766 | ||
1ada6f08 | 767 | .SS USER-SPACE |
38e96af8 FCE |
768 | Support for user-space probing is available for kernels that are |
769 | configured with the utrace extensions, or have the uprobes facility in | |
770 | linux 3.5. (Various kernel build configuration options need to be | |
771 | enabled; systemtap will advise if these are missing.) | |
772 | ||
0a1c696d FCE |
773 | .PP |
774 | There are several forms. First, a non-symbolic probe point: | |
1ada6f08 FCE |
775 | .SAMPLE |
776 | process(PID).statement(ADDRESS).absolute | |
777 | .ESAMPLE | |
778 | is analogous to | |
779 | .IR | |
780 | kernel.statement(ADDRESS).absolute | |
781 | in that both use raw (unverified) virtual addresses and provide | |
782 | no $variables. The target PID parameter must identify a running | |
783 | process, and ADDRESS should identify a valid instruction address. | |
784 | All threads of that process will be probed. | |
29cb9b42 | 785 | .PP |
0a1c696d FCE |
786 | Second, non-symbolic user-kernel interface events handled by |
787 | utrace may be probed: | |
29cb9b42 | 788 | .SAMPLE |
dd078c96 | 789 | process(PID).begin |
82f0e81b | 790 | process("FULLPATH").begin |
986e98de | 791 | process.begin |
dd078c96 | 792 | process(PID).thread.begin |
82f0e81b | 793 | process("FULLPATH").thread.begin |
986e98de | 794 | process.thread.begin |
dd078c96 | 795 | process(PID).end |
82f0e81b | 796 | process("FULLPATH").end |
986e98de | 797 | process.end |
dd078c96 | 798 | process(PID).thread.end |
82f0e81b | 799 | process("FULLPATH").thread.end |
986e98de | 800 | process.thread.end |
29cb9b42 | 801 | process(PID).syscall |
82f0e81b | 802 | process("FULLPATH").syscall |
986e98de | 803 | process.syscall |
29cb9b42 | 804 | process(PID).syscall.return |
82f0e81b | 805 | process("FULLPATH").syscall.return |
986e98de | 806 | process.syscall.return |
0afb7073 | 807 | process(PID).insn |
82f0e81b | 808 | process("FULLPATH").insn |
0afb7073 | 809 | process(PID).insn.block |
82f0e81b | 810 | process("FULLPATH").insn.block |
29cb9b42 DS |
811 | .ESAMPLE |
812 | .PP | |
813 | A | |
dd078c96 | 814 | .B .begin |
82f0e81b | 815 | probe gets called when new process described by PID or FULLPATH gets created. |
29cb9b42 | 816 | A |
dd078c96 | 817 | .B .thread.begin |
82f0e81b | 818 | probe gets called when a new thread described by PID or FULLPATH gets created. |
159cb109 | 819 | A |
dd078c96 | 820 | .B .end |
82f0e81b | 821 | probe gets called when process described by PID or FULLPATH dies. |
dd078c96 DS |
822 | A |
823 | .B .thread.end | |
82f0e81b | 824 | probe gets called when a thread described by PID or FULLPATH dies. |
29cb9b42 DS |
825 | A |
826 | .B .syscall | |
82f0e81b | 827 | probe gets called when a thread described by PID or FULLPATH makes a |
6270adc1 MH |
828 | system call. The system call number is available in the |
829 | .BR $syscall | |
830 | context variable, and the first 6 arguments of the system call | |
831 | are available in the | |
832 | .BR $argN | |
833 | (ex. $arg1, $arg2, ...) context variable. | |
29cb9b42 DS |
834 | A |
835 | .B .syscall.return | |
82f0e81b | 836 | probe gets called when a thread described by PID or FULLPATH returns from a |
5d67b47c MH |
837 | system call. The system call number is available in the |
838 | .BR $syscall | |
839 | context variable, and the return value of the system call is available | |
840 | in the | |
841 | .BR $return | |
29cb9b42 | 842 | context variable. |
a96d1db0 | 843 | A |
0afb7073 | 844 | .B .insn |
82f0e81b | 845 | probe gets called for every single-stepped instruction of the process described by PID or FULLPATH. |
0afb7073 FCE |
846 | A |
847 | .B .insn.block | |
82f0e81b FCE |
848 | probe gets called for every block-stepped instruction of the process described by PID or FULLPATH. |
849 | .PP | |
850 | If a process probe is specified without a PID or FULLPATH, all user | |
851 | threads will be probed. However, if systemtap was invoked with the | |
f7470174 | 852 | .IR \-c " or " \-x |
82f0e81b | 853 | options, then process probes are restricted to the process |
6d5d594e | 854 | hierarchy associated with the target process. If a process probe is |
fc18e6c4 | 855 | unspecified (i.e. without a PID or FULLPATH), but with the |
6d5d594e LB |
856 | .IR \-c " |
857 | option, the PATH of the | |
858 | .IR \-c " | |
fc18e6c4 JL |
859 | cmd will be heuristically filled into the process PATH. In that case, |
860 | only command parameters are allowed in the \fI-c\fR command (i.e. no | |
861 | command substitution allowed and no occurrences of any of these | |
862 | characters: '|&;<>(){}'). | |
0a1c696d FCE |
863 | |
864 | .PP | |
865 | Third, symbolic static instrumentation compiled into programs and | |
866 | shared libraries may be | |
867 | probed: | |
868 | .SAMPLE | |
869 | process("PATH").mark("LABEL") | |
a794dbeb | 870 | process("PATH").provider("PROVIDER").mark("LABEL") |
af127b9f AJ |
871 | process(PID).mark("LABEL") |
872 | process(PID).provider("PROVIDER").mark("LABEL") | |
0a1c696d FCE |
873 | .ESAMPLE |
874 | .PP | |
f28a8c28 SC |
875 | A |
876 | .B .mark | |
877 | probe gets called via a static probe which is defined in the | |
38e96af8 FCE |
878 | application by STAP_PROBE1(PROVIDER,LABEL,arg1), which are macros defined in |
879 | .BR sys/sdt.h . | |
880 | The PROVIDER is an arbitrary application identifier, LABEL is the | |
881 | marker site identifier, and arg1 is the integer-typed argument. | |
882 | STAP_PROBE1 is used for probes with 1 argument, STAP_PROBE2 is used | |
883 | for probes with 2 arguments, and so on. The arguments of the probe | |
884 | are available in the context variables $arg1, $arg2, ... An | |
885 | alternative to using the STAP_PROBE macros is to use the dtrace script | |
886 | to create custom macros. Additionally, the variables $$name and | |
887 | $$provider are available as parts of the probe point name. The | |
888 | .B sys/sdt.h | |
889 | macro names DTRACE_PROBE* are available as aliases for STAP_PROBE*. | |
0a1c696d | 890 | |
29cb9b42 | 891 | .PP |
38e96af8 FCE |
892 | Finally, full symbolic source-level probes in user-space programs and |
893 | shared libraries are supported. These are exactly analogous to the | |
894 | symbolic DWARF-based kernel/module probes described above. They | |
895 | expose the same sorts of context $variables for function parameters, | |
896 | local variables, and so on. | |
0a1c696d FCE |
897 | .SAMPLE |
898 | process("PATH").function("NAME") | |
899 | process("PATH").statement("*@FILE.c:123") | |
4d0fcb93 SC |
900 | process("PATH").plt("NAME") |
901 | process("PATH").library("PATH").plt("NAME") | |
b73a1293 SC |
902 | process("PATH").library("PATH").function("NAME") |
903 | process("PATH").library("PATH").statement("*@FILE.c:123") | |
0a1c696d FCE |
904 | process("PATH").function("*").return |
905 | process("PATH").function("myfun").label("foo") | |
7c86df9f | 906 | process("PATH").function("foo").callee("bar") |
2e96714f | 907 | process("PATH").plt("NAME").return |
af127b9f AJ |
908 | process(PID).function("NAME") |
909 | process(PID).statement("*@FILE.c:123") | |
910 | process(PID).plt("NAME") | |
0a1c696d FCE |
911 | .ESAMPLE |
912 | ||
913 | .PP | |
914 | Note that for all process probes, | |
29cb9b42 | 915 | .I PATH |
ea384b8c FCE |
916 | names refer to executables that are searched the same way shells do: relative |
917 | to the working directory if they contain a "/" character, otherwise in | |
918 | .BR $PATH . | |
d1bcbe71 RH |
919 | If PATH names refer to scripts, the actual interpreters (specified in the |
920 | script in the first line after the #! characters) are probed. | |
78683caf | 921 | |
e8b46a9e FL |
922 | .PP |
923 | Tapset process probes placed in the special directory | |
924 | $prefix/share/systemtap/tapset/PATH/ with relative paths will have their | |
925 | process parameter prefixed with the location of the tapset. For example, | |
926 | ||
927 | .SAMPLE | |
928 | process("foo").function("NAME") | |
929 | .ESAMPLE | |
930 | .PP | |
931 | expands to | |
932 | .SAMPLE | |
933 | process("/usr/bin/foo").function("NAME") | |
934 | .ESAMPLE | |
935 | ||
936 | .PP | |
937 | when placed in $prefix/share/systemtap/tapset/PATH/usr/bin/ | |
938 | ||
78683caf | 939 | .PP |
b73a1293 | 940 | If PATH is a process component parameter referring to shared libraries |
78683caf JL |
941 | then all processes that map it at runtime would be selected for probing. |
942 | If PATH is a library component parameter referring to shared libraries | |
943 | then the process specified by the process component would be selected. | |
944 | Note that the PATH pattern in a library component will always apply to | |
945 | libraries statically determined to be in use by the process. However, | |
946 | you may also specify the full path to any library file even if not | |
947 | statically needed by the process. | |
79dc1dee FCE |
948 | |
949 | .PP | |
950 | A .plt probe will probe functions in the program linkage table | |
4d0fcb93 | 951 | corresponding to the rest of the probe point. .plt can be specified |
79dc1dee FCE |
952 | as a shorthand for .plt("*"). The symbol name is available as a |
953 | $$name context variable; function arguments are not available, since | |
2e96714f SC |
954 | PLTs are processed without debuginfo. A .plt.return probe places a |
955 | probe at the moment \fBafter\fR the return from the named | |
956 | function. | |
79dc1dee FCE |
957 | |
958 | .PP | |
82f0e81b FCE |
959 | If the PATH string contains wildcards as in the MPATTERN case, then |
960 | standard globbing is performed to find all matching paths. In this | |
961 | case, the | |
962 | .BR $PATH | |
963 | environment variable is not used. | |
964 | ||
965 | .PP | |
153e7a22 FCE |
966 | If systemtap was invoked with the |
967 | .IR \-c " or " \-x | |
760695db FCE |
968 | options, then process probes are restricted to the process |
969 | hierarchy associated with the target process. | |
1ada6f08 | 970 | |
982026f1 SM |
971 | .SS JAVA |
972 | Support for probing Java methods is available using Byteman as a | |
973 | backend. Byteman is an instrumentation tool from the JBoss project | |
974 | which systemtap can use to monitor invocations for a specific method | |
975 | or line in a Java program. | |
976 | .PP | |
977 | Systemtap does so by generating a Byteman script listing the probes to | |
978 | instrument and then invoking the Byteman | |
979 | .IR bminstall | |
d885563b | 980 | utility. |
982026f1 | 981 | .PP |
768754f8 | 982 | This Java instrumentation support is currently a prototype feature |
d885563b FCE |
983 | with major limitations. Moreover, Java probing currently does not |
984 | work across users; the stap script must run (with appropriate | |
985 | permissions) under the same user that the Java process being | |
986 | probed. (Thus a stap script under root currently cannot probe Java | |
987 | methods in a non-root-user Java process.) | |
982026f1 SM |
988 | |
989 | .PP | |
990 | The first probe type refers to Java processes by the name of the Java process: | |
991 | .SAMPLE | |
992 | java("PNAME").class("CLASSNAME").method("PATTERN") | |
993 | java("PNAME").class("CLASSNAME").method("PATTERN").return | |
994 | .ESAMPLE | |
269cd0ae LB |
995 | The PNAME argument must be a pre-existing jvm pid, and be identifiable |
996 | via a jps listing. | |
997 | .PP | |
982026f1 SM |
998 | The PATTERN parameter specifies the signature of the Java method to |
999 | probe. The signature must consist of the exact name of the method, | |
1000 | followed by a bracketed list of the types of the arguments, for | |
1001 | instance "myMethod(int,double,Foo)". Wildcards are not supported. | |
1002 | .PP | |
1003 | The probe can be set to trigger at a specific line within the method | |
1004 | by appending a line number with colon, just as in other types of | |
1005 | probes: "myMethod(int,double,Foo):245". | |
1006 | .PP | |
1007 | The CLASSNAME parameter identifies the Java class the method belongs | |
1008 | to, either with or without the package qualification. By default, the | |
1009 | probe only triggers on descendants of the class that do not override | |
1010 | the method definition of the original class. However, CLASSNAME can | |
1011 | take an optional caret prefix, as in | |
1012 | .IR ^org.my.MyClass, | |
1013 | which specifies that the probe should also trigger on all descendants | |
1014 | of MyClass that override the original method. For instance, every method | |
1015 | with signature foo(int) in program org.my.MyApp can be probed at once using | |
1016 | .SAMPLE | |
1017 | java("org.my.MyApp").class("^java.lang.Object").method("foo(int)") | |
1018 | .ESAMPLE | |
1019 | .PP | |
1020 | The second probe type works analogously, but refers to Java processes by PID: | |
1021 | .SAMPLE | |
1022 | java(PID).class("CLASSNAME").method("PATTERN") | |
1023 | java(PID).class("CLASSNAME").method("PATTERN").return | |
1024 | .ESAMPLE | |
1025 | (PIDs for an already running process can be obtained using the | |
1026 | .IR jps (1) | |
1027 | utility.) | |
a26d56a4 SM |
1028 | .PP |
1029 | Context variables defined within java probes include | |
a26d56a4 SM |
1030 | .IR $arg1 |
1031 | through | |
1032 | .IR $arg10 | |
f8bc2a5e FCE |
1033 | (for up to the first 10 arguments of a method), represented as character-pointers |
1034 | for the | |
1035 | .B toString() | |
1036 | form of each actual argument. | |
1037 | The | |
1038 | .IR arg1 | |
1039 | through | |
1040 | .IR arg10 | |
1041 | script variables provide access to these as ordinary strings, fetched via | |
1042 | .IR user_string_warn() . | |
1043 | .PP | |
1044 | Prior to systemtap version 3.1, | |
1045 | .IR $arg1 | |
1046 | through | |
1047 | .IR $arg10 | |
1048 | could contain either integers or character pointers, depending on the types of the | |
1049 | objects being passed to each particular java method. This previous behaviour may | |
1050 | be invoked with the | |
1051 | .I stap --compatible=3.0 | |
1052 | flag. | |
982026f1 | 1053 | |
9cb48751 DS |
1054 | .SS PROCFS |
1055 | ||
1056 | These probe points allow procfs "files" in | |
c243f608 LB |
1057 | /proc/systemtap/MODNAME to be created, read and written using a |
1058 | permission that may be modified using the proper umask value. Default permissions are 0400 for read | |
1059 | probes, and 0200 for write probes. If both a read and write probe are being | |
1060 | used on the same file, a default permission of 0600 will be used. | |
1061 | Using procfs.umask(0040).read would | |
1062 | result in a 0404 permission set for the file. | |
9cb48751 DS |
1063 | .RI ( MODNAME |
1064 | is the name of the systemtap module). The | |
1065 | .I proc | |
b7110b33 | 1066 | filesystem is a pseudo-filesystem which is used as an interface to |
c243f608 | 1067 | kernel data structures. There are several probe point variants supported |
9cb48751 | 1068 | by the translator: |
ca88561f | 1069 | |
9cb48751 DS |
1070 | .SAMPLE |
1071 | procfs("PATH").read | |
c243f608 | 1072 | procfs("PATH").umask(UMASK).read |
38975255 | 1073 | procfs("PATH").read.maxsize(MAXSIZE) |
c243f608 | 1074 | procfs("PATH").umask(UMASK).maxsize(MAXSIZE) |
9cb48751 | 1075 | procfs("PATH").write |
c243f608 | 1076 | procfs("PATH").umask(UMASK).write |
9cb48751 | 1077 | procfs.read |
c243f608 | 1078 | procfs.umask(UMASK).read |
38975255 | 1079 | procfs.read.maxsize(MAXSIZE) |
c243f608 | 1080 | procfs.umask(UMASK).read.maxsize(MAXSIZE) |
9cb48751 | 1081 | procfs.write |
c243f608 | 1082 | procfs.umask(UMASK).write |
9cb48751 | 1083 | .ESAMPLE |
ca88561f | 1084 | |
9cb48751 DS |
1085 | .I PATH |
1086 | is the file name (relative to /proc/systemtap/MODNAME) to be created. | |
1087 | If no | |
1088 | .I PATH | |
1089 | is specified (as in the last two variants above), | |
1090 | .I PATH | |
1091 | defaults to "command". | |
1092 | .PP | |
1093 | When a user reads /proc/systemtap/MODNAME/PATH, the corresponding | |
1094 | procfs | |
1095 | .I read | |
1096 | probe is triggered. The string data to be read should be assigned to | |
1097 | a variable named | |
1098 | .IR $value , | |
1099 | like this: | |
ca88561f | 1100 | |
9cb48751 DS |
1101 | .SAMPLE |
1102 | procfs("PATH").read { $value = "100\\n" } | |
1103 | .ESAMPLE | |
1104 | .PP | |
1105 | When a user writes into /proc/systemtap/MODNAME/PATH, the | |
1106 | corresponding procfs | |
1107 | .I write | |
1108 | probe is triggered. The data the user wrote is available in the | |
1109 | string variable named | |
1110 | .IR $value , | |
1111 | like this: | |
ca88561f | 1112 | |
9cb48751 DS |
1113 | .SAMPLE |
1114 | procfs("PATH").write { printf("user wrote: %s", $value) } | |
1115 | .ESAMPLE | |
38975255 DS |
1116 | .PP |
1117 | .I MAXSIZE | |
1118 | is the size of the procfs read buffer. Specifying | |
1119 | .I MAXSIZE | |
1120 | allows larger procfs output. If no | |
1121 | .I MAXSIZE | |
1122 | is specified, the procfs read buffer defaults to | |
1123 | .I STP_PROCFS_BUFSIZE | |
1124 | (which defaults to | |
1125 | .IR MAXSTRINGLEN , | |
1126 | the maximum length of a string). | |
1127 | If setting the procfs read buffers for more than one file is needed, | |
1128 | it may be easiest to override the | |
1129 | .I STP_PROCFS_BUFSIZE | |
1130 | definition. | |
1131 | Here's an example of using | |
1132 | .IR MAXSIZE : | |
1133 | ||
1134 | .SAMPLE | |
1135 | procfs.read.maxsize(1024) { | |
1136 | $value = "long string..." | |
1137 | $value .= "another long string..." | |
1138 | $value .= "another long string..." | |
1139 | $value .= "another long string..." | |
1140 | } | |
1141 | .ESAMPLE | |
9cb48751 | 1142 | |
da00b50e SM |
1143 | .SS NETFILTER HOOKS |
1144 | ||
1145 | These probe points allow observation of network packets using the | |
1146 | netfilter mechanism. A netfilter probe in systemtap corresponds to a | |
1147 | netfilter hook function in the original netfilter probes API. It is | |
1148 | probably more convenient to use | |
1149 | .IR tapset::netfilter (3stap), | |
1150 | which wraps the primitive netfilter hooks and does the work of | |
1151 | extracting useful information from the context variables. | |
1152 | ||
1153 | .PP | |
1154 | There are several probe point variants supported by the translator: | |
1155 | ||
1156 | .SAMPLE | |
1157 | netfilter.hook("HOOKNAME").pf("PROTOCOL_F") | |
1158 | netfilter.pf("PROTOCOL_F").hook("HOOKNAME") | |
1159 | netfilter.hook("HOOKNAME").pf("PROTOCOL_F").priority("PRIORITY") | |
1160 | netfilter.pf("PROTOCOL_F").hook("HOOKNAME").priority("PRIORITY") | |
1161 | .ESAMPLE | |
1162 | ||
1163 | .PP | |
1164 | .I PROTOCOL_F | |
1165 | is the protocol family to listen for, currently one of | |
1166 | .I NFPROTO_IPV4, | |
1167 | .I NFPROTO_IPV6, | |
1168 | .I NFPROTO_ARP, | |
1169 | or | |
1170 | .I NFPROTO_BRIDGE. | |
1171 | ||
1172 | .PP | |
1173 | .I HOOKNAME | |
1174 | is the point, or 'hook', in the protocol stack at which to intercept | |
1175 | the packet. The available hook names for each protocol family are | |
1176 | taken from the kernel header files <linux/netfilter_ipv4.h>, | |
1177 | <linux/netfilter_ipv6.h>, <linux/netfilter_arp.h> and | |
1178 | <linux/netfilter_bridge.h>. For instance, allowable hook names for | |
1179 | .I NFPROTO_IPV4 | |
1180 | are | |
1181 | .I NF_INET_PRE_ROUTING, | |
1182 | .I NF_INET_LOCAL_IN, | |
1183 | .I NF_INET_FORWARD, | |
1184 | .I NF_INET_LOCAL_OUT, | |
1185 | and | |
1186 | .I NF_INET_POST_ROUTING. | |
1187 | ||
1188 | .PP | |
1189 | .I PRIORITY | |
1190 | is an integer priority giving the order in which the probe point | |
1191 | should be triggered relative to any other netfilter hook functions | |
1192 | which trigger on the same packet. Hook functions execute on each | |
1193 | packet in order from smallest priority number to largest priority number. If no | |
1194 | .I PRIORITY | |
1195 | is specified (as in the first two probe point variants above), | |
1196 | .I PRIORITY | |
1197 | defaults to "0". | |
1198 | ||
1199 | There are a number of predefined priority names of the form | |
1200 | .I NF_IP_PRI_* | |
1201 | and | |
1202 | .I NF_IP6_PRI_* | |
1203 | which are defined in the kernel header files <linux/netfilter_ipv4.h> and <linux/netfilter_ipv6.h> respectively. The script is permitted to use these | |
1204 | instead of specifying an integer priority. (The probe points for | |
1205 | .I NFPROTO_ARP | |
1206 | and | |
1207 | .I NFPROTO_BRIDGE | |
1208 | currently do not expose any named hook priorities to the script writer.) | |
1209 | Thus, allowable ways to specify the priority include: | |
1210 | ||
1211 | .SAMPLE | |
1212 | priority("255") | |
1213 | priority("NF_IP_PRI_SELINUX_LAST") | |
1214 | .ESAMPLE | |
1215 | ||
1216 | A script using guru mode is permitted to specify any identifier or | |
1217 | number as the parameter for hook, pf, and priority. This feature | |
1218 | should be used with caution, as the parameter is inserted verbatim into | |
1219 | the C code generated by systemtap. | |
1220 | ||
1221 | The netfilter probe points define the following context variables: | |
1222 | .TP | |
4d914c37 FCE |
1223 | .IR $hooknum |
1224 | The hook number. | |
1225 | .TP | |
da00b50e SM |
1226 | .IR $skb |
1227 | The address of the sk_buff struct representing the packet. See | |
1228 | <linux/skbuff.h> for details on how to use this struct, or | |
1229 | alternatively use the tapset | |
1230 | .IR tapset::netfilter (3stap) | |
1231 | for easy access to key information. | |
1232 | ||
1233 | .TP | |
1234 | .IR $in | |
1235 | The address of the net_device struct representing the network device | |
1236 | on which the packet was received (if any). May be 0 if the device is | |
1237 | unknown or undefined at that stage in the protocol stack. | |
1238 | ||
1239 | .TP | |
1240 | .IR $out | |
1241 | The address of the net_device struct representing the network device | |
1242 | on which the packet will be sent (if any). May be 0 if the device is | |
1243 | unknown or undefined at that stage in the protocol stack. | |
1244 | ||
1245 | .TP | |
1246 | .IR $verdict | |
1247 | (Guru mode only.) Assigning one of the verdict values defined in | |
1248 | <linux/netfilter.h> to this variable alters the further progress of | |
1249 | the packet through the protocol stack. For instance, the following | |
1250 | guru mode script forces all ipv6 network packets to be dropped: | |
1251 | ||
1252 | .SAMPLE | |
1253 | probe netfilter.pf("NFPROTO_IPV6").hook("NF_IP6_PRE_ROUTING") { | |
c49ffe6c | 1254 | $verdict = 0 /* nf_drop */ |
da00b50e SM |
1255 | } |
1256 | .ESAMPLE | |
1257 | ||
c49ffe6c SM |
1258 | For convenience, unlike the primitive probe points discussed here, the |
1259 | probes defined in | |
1260 | .IR tapset::netfilter (3stap) | |
1261 | export the lowercase names of the verdict constants (e.g. NF_DROP | |
1262 | becomes nf_drop) as local variables. | |
1263 | ||
6032e2ce | 1264 | .SS KERNEL TRACEPOINTS |
bc724b8b JS |
1265 | |
1266 | This family of probe points hooks up to static probing tracepoints | |
1267 | inserted into the kernel or modules. As with markers, these | |
1268 | tracepoints are special macro calls inserted by kernel developers to | |
1269 | make probing faster and more reliable than with DWARF-based probes, | |
1270 | and DWARF debugging information is not required to probe tracepoints. | |
1271 | Tracepoints have an extra advantage of more strongly-typed parameters | |
1272 | than markers. | |
1273 | ||
6032e2ce FCE |
1274 | Tracepoint probes look like: |
1275 | .BR kernel.trace("name") . | |
bc724b8b JS |
1276 | The tracepoint name string, which may contain the usual wildcard |
1277 | characters, is matched against the names defined by the kernel | |
970d1d06 JL |
1278 | developers in the tracepoint header files. To restrict the search to |
1279 | specific subsystems (e.g. sched, ext3, etc...), the following syntax | |
1280 | can be used: | |
1281 | .BR kernel.trace("system:name") . | |
1282 | The tracepoint system string may also contain the usual wildcard | |
1283 | characters. | |
bc724b8b JS |
1284 | |
1285 | The handler associated with a tracepoint-based probe may read the | |
1286 | optional parameters specified at the macro call site. These are | |
1287 | named according to the declaration by the tracepoint author. For | |
1288 | example, the tracepoint probe | |
970d1d06 | 1289 | .BR kernel.trace("sched:sched_switch") |
bc724b8b | 1290 | provides the parameters |
970d1d06 | 1291 | .BR $prev " and " $next . |
bc724b8b JS |
1292 | If the parameter is a complex type, as in a struct pointer, then a |
1293 | script can access fields with the same syntax as DWARF $target | |
1294 | variables. Also, tracepoint parameters cannot be modified, but in | |
1295 | guru-mode a script may modify fields of parameters. | |
1296 | ||
970d1d06 JL |
1297 | The subsystem and name of the tracepoint are available in |
1298 | .BR $$system " and " $$name | |
bc724b8b JS |
1299 | and a string of name=value pairs for all parameters of the tracepoint |
1300 | is available in | |
046e7190 | 1301 | .BR $$vars " or " $$parms . |
bc724b8b | 1302 | |
6032e2ce FCE |
1303 | .SS KERNEL MARKERS (OBSOLETE) |
1304 | ||
1305 | This family of probe points hooks up to an older style of static | |
1306 | probing markers inserted into older kernels or modules. These markers | |
1307 | are special STAP_MARK macro calls inserted by kernel developers to | |
1308 | make probing faster and more reliable than with DWARF-based probes. | |
1309 | Further, DWARF debugging information is | |
1310 | .I not | |
1311 | required to probe markers. | |
1312 | ||
1313 | Marker probe points begin with | |
1314 | .BR kernel . | |
1315 | The next part names the marker itself: | |
1316 | .BR mark("name") . | |
1317 | The marker name string, which may contain the usual wildcard characters, | |
1318 | is matched against the names given to the marker macros when the kernel | |
1319 | and/or module was compiled. Optionally, you can specify | |
1320 | .BR format("format") . | |
1321 | Specifying the marker format string allows differentiation between two | |
1322 | markers with the same name but different marker format strings. | |
1323 | ||
1324 | The handler associated with a marker-based probe may read the | |
1325 | optional parameters specified at the macro call site. These are | |
1326 | named | |
1327 | .BR $arg1 " through " $argNN , | |
1328 | where NN is the number of parameters supplied by the macro. Number | |
1329 | and string parameters are passed in a type-safe manner. | |
1330 | ||
1331 | The marker format string associated with a marker is available in | |
1332 | .BR $format . | |
1333 | And also the marker name string is available in | |
1334 | .BR $name . | |
1335 | ||
dd225250 PS |
1336 | .SS HARDWARE BREAKPOINTS |
1337 | This family of probes is used to set hardware watchpoints for a given | |
1338 | (global) kernel symbol. The probes take three components as inputs : | |
1339 | ||
1340 | 1. The | |
1341 | .BR virtual address / name | |
1342 | of the kernel symbol to be traced is supplied as argument to this class | |
1343 | of probes. ( Probes for only data segment variables are supported. Probing | |
1344 | local variables of a function cannot be done.) | |
1345 | ||
1346 | 2. Nature of access to be probed : | |
1347 | a. | |
1348 | .I .write | |
1349 | probe gets triggered when a write happens at the specified address/symbol | |
1350 | name. | |
1351 | b. | |
1352 | .I rw | |
1353 | probe is triggered when either a read or write happens. | |
1354 | ||
1355 | 3. | |
1356 | .BR .length | |
1357 | (optional) | |
1358 | Users have the option of specifying the address interval to be probed | |
1359 | using "length" constructs. The user-specified length gets approximated | |
1360 | to the closest possible address length that the architecture can | |
1361 | support. If the specified length exceeds the limits imposed by | |
1362 | architecture, an error message is flagged and probe registration fails. | |
1363 | Wherever 'length' is not specified, the translator requests a hardware | |
1364 | breakpoint probe of length 1. It should be noted that the "length" | |
1365 | construct is not valid with symbol names. | |
1366 | ||
1367 | Following constructs are supported : | |
1368 | .SAMPLE | |
1369 | probe kernel.data(ADDRESS).write | |
1370 | probe kernel.data(ADDRESS).rw | |
1371 | probe kernel.data(ADDRESS).length(LEN).write | |
1372 | probe kernel.data(ADDRESS).length(LEN).rw | |
1373 | probe kernel.data("SYMBOL_NAME").write | |
1374 | probe kernel.data("SYMBOL_NAME").rw | |
1375 | .ESAMPLE | |
1376 | ||
1377 | This set of probes make use of the debug registers of the processor, | |
1378 | which is a scarce resource. (4 on x86 , 1 on powerpc ) The script | |
1379 | translation flags a warning if a user requests more hardware breakpoint probes | |
1380 | than the limits set by architecture. For example,a pass-2 warning is flashed | |
1381 | when an input script requests 5 hardware breakpoint probes on an x86 | |
1382 | system while x86 architecture supports a maximum of 4 breakpoints. | |
1383 | Users are cautioned to set probes judiciously. | |
1384 | ||
9becfcef MW |
1385 | .SS PERF |
1386 | ||
f8b9be91 | 1387 | This family of probe points interfaces to the kernel "perf event" |
cb7d3cd8 | 1388 | infrastructure for controlling hardware performance counters. |
9becfcef MW |
1389 | The events being attached to are described by the "type", |
1390 | "config" fields of the | |
1391 | .IR perf_event_attr | |
1392 | structure, and are sampled at an interval governed by the | |
b113d360 | 1393 | "sample_period" and "sample_freq" fields. |
9becfcef MW |
1394 | |
1395 | These fields are made available to systemtap scripts using | |
1396 | the following syntax: | |
1397 | .SAMPLE | |
1398 | probe perf.type(NN).config(MM).sample(XX) | |
07c818a0 | 1399 | probe perf.type(NN).config(MM).hz(XX) |
9becfcef | 1400 | probe perf.type(NN).config(MM) |
dbdab5c8 SC |
1401 | probe perf.type(NN).config(MM).process("PROC") |
1402 | probe perf.type(NN).config(MM).counter("COUNTER") | |
1403 | probe perf.type(NN).config(MM).process("PROC").counter("COUNTER") | |
9becfcef MW |
1404 | .ESAMPLE |
1405 | The systemtap probe handler is called once per XX increments | |
b113d360 FL |
1406 | of the underlying performance counter when using the .sample field |
1407 | or at a frequency in hertz when using the .hz field. When not specified, | |
1408 | the default behavior is to sample at a count of 1000000. | |
9becfcef MW |
1409 | The range of valid type/config is described by the |
1410 | .IR perf_event_open (2) | |
1411 | system call, and/or the | |
1412 | .IR linux/perf_event.h | |
1413 | file. Invalid combinations or exhausted hardware counter resources | |
1414 | result in errors during systemtap script startup. Systemtap does | |
1415 | not sanity-check the values: it merely passes them through to | |
6a8fe809 SC |
1416 | the kernel for error- and safety-checking. By default the perf event |
1417 | probe is systemwide unless .process is specified, which will bind the | |
fce2c5df | 1418 | probe to a specific task. If the name is omitted then it |
e996e76a | 1419 | is inferred from the stap \-c argument. A perf event can be read on |
75cd04ca SC |
1420 | demand using .counter. The body of the perf probe handler will not be |
1421 | invoked for a .counter probe; instead, the counter is read in a user | |
1422 | space probe via: | |
dbdab5c8 SC |
1423 | .TP |
1424 | process("PROCESS").statement("func@file") {stat <<< @perf("NAME")} | |
1425 | ||
fce2c5df | 1426 | |
ba4a90fd FCE |
1427 | .SH EXAMPLES |
1428 | .PP | |
1429 | Here are some example probe points, defining the associated events. | |
1430 | .TP | |
1431 | begin, end, end | |
1432 | refers to the startup and normal shutdown of the session. In this | |
1433 | case, the handler would run once during startup and twice during | |
1434 | shutdown. | |
1435 | .TP | |
1436 | timer.jiffies(1000).randomize(200) | |
13d2ecdb | 1437 | refers to a periodic interrupt, every 1000 +/\- 200 jiffies. |
ba4a90fd FCE |
1438 | .TP |
1439 | kernel.function("*init*"), kernel.function("*exit*") | |
1440 | refers to all kernel functions with "init" or "exit" in the name. | |
1441 | .TP | |
199d126d MW |
1442 | kernel.function("*@kernel/time.c:240") |
1443 | refers to any functions within the "kernel/time.c" file that span | |
6ff00e1d FCE |
1444 | line 240. |
1445 | .BR | |
1446 | Note | |
1447 | that this is | |
1448 | .BR not | |
1449 | a probe at the statement at that line number. Use the | |
1450 | .IR | |
1451 | kernel.statement | |
1452 | probe instead. | |
ba4a90fd | 1453 | .TP |
6032e2ce FCE |
1454 | kernel.trace("sched_*") |
1455 | refers to all scheduler-related (really, prefixed) tracepoints in | |
1456 | the kernel. | |
1457 | .TP | |
6f05b6ab | 1458 | kernel.mark("getuid") |
6032e2ce | 1459 | refers to an obsolete STAP_MARK(getuid, ...) macro call in the kernel. |
6f05b6ab | 1460 | .TP |
ba4a90fd FCE |
1461 | module("usb*").function("*sync*").return |
1462 | refers to the moment of return from all functions with "sync" in the | |
1463 | name in any of the USB drivers. | |
1464 | .TP | |
1465 | kernel.statement(0xc0044852) | |
1466 | refers to the first byte of the statement whose compiled instructions | |
1467 | include the given address in the kernel. | |
b4ceace2 | 1468 | .TP |
199d126d MW |
1469 | kernel.statement("*@kernel/time.c:296") |
1470 | refers to the statement of line 296 within "kernel/time.c". | |
1bd128a3 SC |
1471 | .TP |
1472 | kernel.statement("bio_init@fs/bio.c+3") | |
1473 | refers to the statement at line bio_init+3 within "fs/bio.c". | |
a5ae3f3d | 1474 | .TP |
dd225250 | 1475 | kernel.data("pid_max").write |
cb7d3cd8 | 1476 | refers to a hardware breakpoint of type "write" set on pid_max |
dd225250 | 1477 | .TP |
729286d8 | 1478 | syscall.*.return |
b4ceace2 | 1479 | refers to the group of probe aliases with any name in the third position |
ba4a90fd FCE |
1480 | |
1481 | .SH SEE ALSO | |
5dfce2b6 FCE |
1482 | .nh |
1483 | .nf | |
78db65bd | 1484 | .IR stap (1), |
89965a32 FCE |
1485 | .IR probe::* (3stap), |
1486 | .IR tapset::* (3stap) | |
1c0b8e23 FCE |
1487 | |
1488 | .\" Local Variables: | |
1489 | .\" mode: nroff | |
1490 | .\" End: |