-.\" -*- nroff -*-
+.\" t
.TH STAPPROBES 3stap
.SH NAME
stapprobes \- systemtap probe points
kprobe.function("foo")
.ESAMPLE
-
Probes may be broadly classified into "synchronous" and
"asynchronous". A "synchronous" event is deemed to occur when any
processor executes an instruction matched by the specification. This
declaration may also contain several comma-separated specifications,
all of which are probed.
+.SH DWARF DEBUGINFO
+
+Resolving some probe points requires DWARF debuginfo or "debug
+symbols" for the specific part being instrumented. For some others,
+DWARF is automatically synthesized on the fly from source code header
+files. For others, it is not needed at all. Since a systemtap script
+may use any mixture of probe points together, the union of their DWARF
+requirements has to be met on the computer where script compilation
+occurs. (See the \fI\-\-use\-server\fR option and the \fBstap-server\
+(8)\fR man page for information about the remote compilation facility,
+which allows these requirements to be met on a different machine.)
+.PP
+The following point lists many of the available probe point families,
+to classify them with respect to their need for DWARF debuginfo.
+
+.TS
+l l l.
+\fBDWARF NON-DWARF\fP
+
+kernel.function, .statement kernel.mark
+module.function, .statement process.mark
+process.function, .statement begin, end, error, never
+process.mark \fI(backup)\fP timer
+ perf
+ procfs
+\fBAUTO-DWARF\fP kernel.statement.absolute
+ kernel.data
+kernel.trace kprobe.function
+ process.statement.absolute
+ process.begin, .end, .error
+.TE
+
+.SH PROBE POINT FAMILIES
+
.SS BEGIN/END/ERROR
The probe points
.IR .return
probe.
.PP
-Each probe alias defines a variety of variables. Looking at the tapset source
+Each probe alias provides a variety of variables. Looking at the tapset source
code is the most reliable way. Generally, each variable listed in the standard
manual page is made available as a script-level variable, so
.IR syscall.open
.IR retstr
For return probes, a pretty-printed form of the system-call result.
.PP
-Not all probe aliases obey all of these general guidelines. Please report
-any bothersome ones you encounter as a bug.
+As usual for probe aliases, these variables are all simply initialized
+once from the underlying $context variables, so that later changes to
+$context variables are not automatically reflected. Not all probe
+aliases obey all of these general guidelines. Please report any
+bothersome ones you encounter as a bug.
.SS TIMERS
filters the results to include only instances of inlined functions.
The
.B .call
-modifier selects the opposite subset. Inline functions do not have an
-identifiable return point, so
+modifier selects the opposite subset. The \textbf{.exported} modifier
+filters the results to include only exported functions. Inline
+functions do not have an identifiable return point, so
.B .return
is not supported on
.B .inline
.br
module(MPATTERN).function(PATTERN).inline
.br
+module(MPATTERN).function(PATTERN).label(LPATTERN)
+.br
.br
kernel.statement(PATTERN)
.br
.br
process("PATH").statement("*@FILE.c:123")
.br
+process("PATH").library("PATH").function("NAME")
+.br
+process("PATH").library("PATH").statement("*@FILE.c:123")
+.br
process("PATH").function("*").return
.br
process("PATH").function("myfun").label("foo")
absolute line number if preceded by a ":", or relative to the entry of
the function if preceded by a "+".
All the lines in the function can be matched with ":*".
-A range of lines x through y can be matched with ":x-y".
+A range of lines x through y can be matched with ":x\-y".
.PP
As an alternative, PATTERN may be a numeric constant, indicating an
address. Such an address may be found from symbol tables of the
.IR kernel_string " or " user_string
functions.
.TP
+@var("varname")
+an alternative syntax for
+.IR $varname
+.
+.TP
+@var("varname@src/file.c")
+refers to the global (either file local or external) variable
+.IR varname
+defined when the file
+.IR src/file.c
+was compiled. The CU in which the variable is resolved is the first CU
+in the module of the probe point which matches the given file name at
+the end and has the shortest file name path (e.g. given
+.IR @var("foo@bar/baz.c")
+and CUs with file name paths
+.IR src/sub/module/bar/baz.c
+and
+.IR src/bar/baz.c
+the second CU will be chosen to resolve the (file) global variable
+.IR foo
+.
+.TP
$var\->field traversal via a structure's or a pointer's field. This
generalized indirection operator may be repeated to follow more
levels. Note that the
expands to 1 or 0 iff the given context variable expression is resolvable,
for use in conditionals such as
.SAMPLE
-@defined($foo->bar) ? $foo->bar : 0
+@defined($foo\->bar) ? $foo\->bar : 0
.ESAMPLE
.TP
$EXPR$
.PP
If a process probe is specified without a PID or FULLPATH, all user
threads will be probed. However, if systemtap was invoked with the
-.IR -c " or " -x
+.IR \-c " or " \-x
options, then process probes are restricted to the process
-hierarchy associated with the target process.
+hierarchy associated with the target process. If a process probe is
+specified without a PID or FULLPATH, but with the
+.IR \-c "
+option, the PATH of the
+.IR \-c "
+cmd will be heuristically filled into the process PATH.
.PP
Third, symbolic static instrumentation compiled into programs and
Finally, full symbolic source-level probes in user-space programs
and shared libraries are supported. These are exactly analogous
to the symbolic DWARF-based kernel/module probes described above,
-and expose similar contextual $-variables.
+and expose similar contextual $variables.
.SAMPLE
process("PATH").function("NAME")
process("PATH").statement("*@FILE.c:123")
+process("PATH").plt("NAME")
+process("PATH").library("PATH").plt("NAME")
+process("PATH").library("PATH").function("NAME")
+process("PATH").library("PATH").statement("*@FILE.c:123")
process("PATH").function("*").return
process("PATH").function("myfun").label("foo")
.ESAMPLE
.BR $PATH .
If PATH names refer to scripts, the actual interpreters (specified in the
script in the first line after the #! characters) are probed.
-PATH may also refer to shared libraries, in which case all proceses that
-map it at runtime would be selected for probing.
+If PATH is a process component parameter referring to shared libraries
+then all processes that map it at runtime would be selected for
+probing. If PATH is a library component parameter referring to shared
+libraries then the process specified by the process component would be
+selected. A .plt probe will probe functions in the program linkage table
+corresponding to the rest of the probe point. .plt can be specified
+as a shorthand for .plt("*").
If the PATH string contains wildcards as in the MPATTERN case, then
standard globbing is performed to find all matching paths. In this
case, the
system while x86 architecture supports a maximum of 4 breakpoints.
Users are cautioned to set probes judiciously.
+.SS PERF
+
+This
+.IR prototype
+family of probe points interfaces to the kernel "perf event"
+infrasture for controlling hardware performance counters.
+The events being attached to are described by the "type",
+"config" fields of the
+.IR perf_event_attr
+structure, and are sampled at an interval governed by the
+"sample_period" field.
+
+These fields are made available to systemtap scripts using
+the following syntax:
+.SAMPLE
+probe perf.type(NN).config(MM).sample(XX)
+probe perf.type(NN).config(MM)
+.ESAMPLE
+The systemtap probe handler is called once per XX increments
+of the underlying performance counter. The default sampling
+count is 1000000.
+The range of valid type/config is described by the
+.IR perf_event_open (2)
+system call, and/or the
+.IR linux/perf_event.h
+file. Invalid combinations or exhausted hardware counter resources
+result in errors during systemtap script startup. Systemtap does
+not sanity-check the values: it merely passes them through to
+the kernel for error- and safety-checking.
+
.SH EXAMPLES
.PP
Here are some example probe points, defining the associated events.
kernel.function("*init*"), kernel.function("*exit*")
refers to all kernel functions with "init" or "exit" in the name.
.TP
-kernel.function("*@kernel/sched.c:240")
-refers to any functions within the "kernel/sched.c" file that span
+kernel.function("*@kernel/time.c:240")
+refers to any functions within the "kernel/time.c" file that span
line 240.
.BR
Note
refers to the first byte of the statement whose compiled instructions
include the given address in the kernel.
.TP
-kernel.statement("*@kernel/sched.c:2917")
-refers to the statement of line 2917 within "kernel/sched.c".
+kernel.statement("*@kernel/time.c:296")
+refers to the statement of line 296 within "kernel/time.c".
.TP
kernel.statement("bio_init@fs/bio.c+3")
refers to the statement at line bio_init+3 within "fs/bio.c".
syscall.*.return
refers to the group of probe aliases with any name in the third position
-.SS PERF
-
-This
-.IR prototype
-family of probe points interfaces to the kernel "perf event"
-infrasture for controlling hardware performance counters.
-The events being attached to are described by the "type",
-"config" fields of the
-.IR perf_event_attr
-structure, and are sampled at an interval governed by the
-"sample_period" field.
-
-These fields are made available to systemtap scripts using
-the following syntax:
-.SAMPLE
-probe perf.type(NN).config(MM).sample(XX)
-probe perf.type(NN).config(MM)
-.ESAMPLE
-The range of valid type/config is described by the
-.IR perf_event_open (2)
-system call, and/or the
-.IR linux/perf_event.h
-file. Invalid combinations or exhausted hardware counter resources
-result in errors during systemtap script startup. Systemtap does
-not sanity-check the values: it merely passes them through to
-the kernel for error- and safety-checking.
-
.SH SEE ALSO
.IR stap (1),
.IR probe::* (3stap),
git://sourceware.org / systemtap.git / blobdiff