.TS
l l l.
-\fBDWARF AUTO-DWARF NON-DWARF\fP
-
-kernel.function, .statement kernel.trace kernel.mark
-module.function, .statement process.mark
-process.function, .statement begin, end, error, never
-process.mark \fI(backup)\fP timer
- perf
- procfs
- kernel.statement.absolute
- kernel.data
- kprobe.function
- process.statement.absolute
- process.begin, .end, .error
+\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
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
.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
threads will be probed. However, if systemtap was invoked with the
.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
.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
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.
+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