summaryrefslogtreecommitdiffstats
path: root/man
diff options
authormcermak <mcermak>2014-05-16 18:00:12 +0000
committermcermak <mcermak>2014-05-16 18:00:12 +0000
commitec538d9efc06cd5663fce290c6d273af4fde3e1c (patch)
treea2831ff7fce25cec2dcc91f2c30c9a18edcd173e /man
parentremoved man pages (diff)
added new man pages
Diffstat (limited to 'man')
-rw-r--r--man/dtrace.1.html202
-rw-r--r--man/error::buildid.7stap.html117
-rw-r--r--man/error::dwarf.7stap.html111
-rw-r--r--man/error::fault.7stap.html70
-rw-r--r--man/error::inode-uprobes.7stap.html65
-rw-r--r--man/error::pass1.7stap.html93
-rw-r--r--man/error::pass2.7stap.html141
-rw-r--r--man/error::pass3.7stap.html62
-rw-r--r--man/error::pass4.7stap.html86
-rw-r--r--man/error::pass5.7stap.html129
-rw-r--r--man/error::process-tracking.7stap.html128
-rw-r--r--man/error::reporting.7stap.html77
-rw-r--r--man/error::sdt.7stap.html120
-rw-r--r--man/index.html30
-rw-r--r--man/stap-merge.1.html185
-rw-r--r--man/stap-prep.1.html99
-rw-r--r--man/stap-report.1.html101
-rw-r--r--man/stap-server.8.html786
-rw-r--r--man/stap.1.html3138
-rw-r--r--man/stapdyn.8.html250
-rw-r--r--man/stapex.3stap.html246
-rw-r--r--man/stapfuncs.3stap.html54
-rw-r--r--man/stappaths.7.html182
-rw-r--r--man/stapprobes.3stap.html2023
-rw-r--r--man/staprun.8.html451
-rw-r--r--man/stapsh.8.html64
-rw-r--r--man/stapvars.3stap.html95
-rw-r--r--man/systemtap.8.html784
-rw-r--r--man/warning::debuginfo.7stap.html178
29 files changed, 10067 insertions, 0 deletions
diff --git a/man/dtrace.1.html b/man/dtrace.1.html
new file mode 100644
index 00000000..825866fc
--- /dev/null
+++ b/man/dtrace.1.html
@@ -0,0 +1,202 @@
1
2<HTML><HEAD><TITLE>Manpage of DTRACE</TITLE>
3</HEAD><BODY>
4<H1>DTRACE</H1>
5Section: User Commands (1)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11dtrace - Dtrace compatibile user application static probe generation tool.
12<P>
13
14
15
16
17<P>
18<A NAME="lbAC">&nbsp;</A>
19<H2>SYNOPSIS</H2>
20
21<P>
22<BR>
23
24<B>dtrace -s </B><I>file</I> [<B>OPTIONS</B>]
25
26<P>
27<A NAME="lbAD">&nbsp;</A>
28<H2>DESCRIPTION</H2>
29
30<P>
31The dtrace command converts probe descriptions defined in <I>file.d</I>
32into a probe header
33file via the <B>-h</B> option
34or a probe description file via the <B>-G</B> option.
35<P>
36<A NAME="lbAE">&nbsp;</A>
37<H2>OPTIONS</H2>
38
39<P>
40
41<DL COMPACT>
42<DT><B>-h</B>
43
44<DD>
45generate a systemtap header file.
46<P>
47<DT><B>-G</B>
48
49<DD>
50generate a systemtap probe definition object file.
51<P>
52<DT><B>-o </B><I>file</I>
53
54<DD>
55is the name of the output file. If the <B>-G</B> option is given then
56the output file will be called <I>file.o</I>; if the <B>-h</B> option is
57given then the output file will be called <I>file.h</I>.
58<P>
59<DT><B>-C</B>
60
61<DD>
62run the cpp preprocessor on the input file when the <B>-h</B> option
63is given.
64<P>
65<DT><B>-I </B><I>file</I>
66
67<DD>
68give this include path to cpp when the <B>-C</B> option is given.
69<P>
70<DT><B>-k</B>
71
72<DD>
73keep temporary files, for example the C language source for the
74<B>-G</B> option.
75<P>
76</DL>
77<A NAME="lbAF">&nbsp;</A>
78<H2>EXAMPLES</H2>
79
80<P>
81Systemtap is source compatible with dtrace user application static
82probe support.
83Given a file <I>test.d</I> containing:
84
85<BR>
86
87<P>
88
89<DL COMPACT><DT><DD>
90<PRE>
91provider sdt_probes
92{
93 probe test_0 (int type);
94 probe test_1 (struct astruct node);
95};
96struct astruct {int a; int b;};
97
98</PRE>
99
100</DL>
101
102
103<P>
104
105Then the command <I>&quot;dtrace&nbsp;-s&nbsp;test.d&nbsp;-G&quot;</I> will create the
106probe definition file <I>test.o</I> and the command <I>&quot;dtrace&nbsp;-stest.d&nbsp;-h&quot;</I> will create the probe header file <I>test.h</I>
107Subsequently the application can use the generated macros this way:
108
109<BR>
110
111<P>
112
113<DL COMPACT><DT><DD>
114<PRE>
115#include &quot;test.h&quot;
116 ...
117struct astruct s;
118 ...
119SDT_PROBES_TEST_0(value);
120 ...
121if (SDT_PROBES_TEST_1_ENABLED())
122 SDT_PROBES_TEST_1(expensive_function(s));
123
124</PRE>
125
126</DL>
127
128
129<P>
130
131<P>
132<A NAME="lbAG">&nbsp;</A>
133<H2>SEMAPHORES</H2>
134
135<P>
136Semaphores are flag variables used by probes as a way of bypassing
137potentially costly processing to prepare arguments for probes that may
138not even be active. They are automatically set/cleared by systemtap
139when a relevant script is running, so the argument setup cost is only
140paid when necessary. These semaphore variables are defined within the
141the <I>&quot;test.o&quot;</I> object file, which must therefore be linked into an
142application.
143<P>
144
145Sometimes, semaphore variables are not necessary nor helpful. Skipping
146them can simplfy the build process, by omitting the extra <I>&quot;test.o&quot;</I>
147file. To skip dependence upon semaphore variables, include <I>&quot;&lt;<A HREF="file:///usr/include/sys/sdt.h">sys/sdt.h</A>&gt;&quot;</I>
148within the application before <I>&quot;test.h&quot;</I>:
149
150<BR>
151
152<P>
153
154<DL COMPACT><DT><DD>
155<PRE>
156#include &lt;<A HREF="file:///usr/include/sys/sdt.h">sys/sdt.h</A>&gt;
157#include &quot;test.h&quot;
158 ...
159struct astruct s;
160 ...
161SDT_PROBES_TEST_0(value);
162 ...
163if (SDT_PROBES_TEST_1_ENABLED())
164 SDT_PROBES_TEST_1(cheap_function(s));
165
166</PRE>
167
168</DL>
169
170
171<P>
172
173In this mode, the ENABLED() test is fixed at 1.
174<P>
175<A NAME="lbAH">&nbsp;</A>
176<H2>SEE ALSO</H2>
177
178
179<PRE>
180<I><A HREF="stap.1.html">stap</A></I>(1),
181<I><A HREF="stappaths.7.html">stappaths</A></I>(7)
182
183
184</PRE>
185<HR>
186<A NAME="index">&nbsp;</A><H2>Index</H2>
187<DL>
188<DT><A HREF="#lbAB">NAME</A><DD>
189<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
190<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
191<DT><A HREF="#lbAE">OPTIONS</A><DD>
192<DT><A HREF="#lbAF">EXAMPLES</A><DD>
193<DT><A HREF="#lbAG">SEMAPHORES</A><DD>
194<DT><A HREF="#lbAH">SEE ALSO</A><DD>
195</DL>
196<HR>
197This document was created by
198<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
199using the manual pages.<BR>
200Time: 17:59:59 GMT, May 16, 2014
201</BODY>
202</HTML>
diff --git a/man/error::buildid.7stap.html b/man/error::buildid.7stap.html
new file mode 100644
index 00000000..642f1952
--- /dev/null
+++ b/man/error::buildid.7stap.html
@@ -0,0 +1,117 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::BUILDID</TITLE>
3</HEAD><BODY>
4<H1>ERROR::BUILDID</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::buildid - build-id verification failures
12<P>
13
14
15
16<P>
17<P>
18<A NAME="lbAC">&nbsp;</A>
19<H2>DESCRIPTION</H2>
20
21<P>
22Because systemtap's script translation / execution stages may be
23executed at different times and places, it is sometimes necessary to
24verify certain invariants. One such invariant is that if a script
25was informed by translate-time analysis of executables, then those
26same executables need to be used at run time. This checking
27is done based upon the build-id, a binary hash that modern (post-2007)
28compilers/toolchains add as an
29<I>NT_GNU_BUILD_ID</I>
30
31ELF note to object files and executables.
32Use the
33<I>readelf -n</I>
34
35command to examine the build-ids of binaries, if you are interested.
36<P>
37<P>
38
39<P>
40Only scripts are sensitive to executables' build-ids: generally those
41that perform deep analysis of the binaries or their debuginfo. For example,
42scripts that place
43<I>.function</I> or <I>.statement</I>
44
45probes, or use stack backtrace-related tapset functions may be sensitive.
46Other scripts that rely only on
47<I>process.mark</I> or <I>kernel.trace</I>
48
49probes do not require debuginfo. See the DWARF DEBUGINFO section in the
50<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap)
51
52man page.
53<P>
54<P>
55
56<P>
57During translation, systemtap saves a copy of the relevant files'
58build-ids within the compiled modules. At run-time, the modules
59compare the saved ones to the actual run-time build-ids in memory.
60The error message indicates that they did not match, so the module
61will decline placing a probe that was computed based upon obsolete
62data. This is important for safety, as placing them at an
63inappropriate address could crash the programs. However, this is not
64necessarily a fatal error, since probes unrelated to the mismatching
65binaries may operate.
66<P>
67<P>
68
69<P>
70A build-id mismatch could be caused by a few different situations.
71The main one is where the executable versions or architecture were
72different between the systemtap translation and execution
73times/places. For example, one may run a stap-server on a slightly
74different version of the OS distribution. Someone may have rebuilt a
75new kernel image, but preserved the previous version numbers. The
76kernel running on the workstation may be slightly different from the
77version being targeted - perhaps due to a pending kernel upgrade
78leaving different files on disk versus running in memory. If your OS
79distribution uses separate debuginfo packages, the split <I>.debug</I>
80files may not exactly match the main binaries.
81<P>
82<P>
83
84<P>
85To disable build-id verification errors, if one is confident that they
86are an artefact of build accidents rather than a real mismatch, one
87might try the
88<I>-DSTP_NO_BUILDID_CHECK</I>
89
90option.
91<P>
92<A NAME="lbAD">&nbsp;</A>
93<H2>SEE ALSO</H2>
94
95
96<PRE>
97<I><A HREF="http://fedoraproject.org/wiki/Releases/FeatureBuildId">http://fedoraproject.org/wiki/Releases/FeatureBuildId</A></I>,
98<I><A HREF="stap.1.html">stap</A></I>(1),
99<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
100<I><A HREF="./warning::debuginfo.7stap.html">warning::debuginfo</A></I>(7stap),
101<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
102
103</PRE>
104<HR>
105<A NAME="index">&nbsp;</A><H2>Index</H2>
106<DL>
107<DT><A HREF="#lbAB">NAME</A><DD>
108<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
109<DT><A HREF="#lbAD">SEE ALSO</A><DD>
110</DL>
111<HR>
112This document was created by
113<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
114using the manual pages.<BR>
115Time: 17:59:59 GMT, May 16, 2014
116</BODY>
117</HTML>
diff --git a/man/error::dwarf.7stap.html b/man/error::dwarf.7stap.html
new file mode 100644
index 00000000..0a6fcae0
--- /dev/null
+++ b/man/error::dwarf.7stap.html
@@ -0,0 +1,111 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::DWARF</TITLE>
3</HEAD><BODY>
4<H1>ERROR::DWARF</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::dwarf - dwarf debuginfo quality problems
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>DESCRIPTION</H2>
15
16<P>
17Systemtap sometimes relies on ELF/DWARF debuginfo for programs being
18instrumented to locate places to probe, or context variables to
19read/write, just like a symbolic debugger does. Even though
20examination of the program's source code may show variables or lines
21where probes may be desired, the compiler must preserve information
22about them for systemtap (or a debugger such as gdb) to get pinpoint
23access to the desired information. If a script requires such data,
24but the compiler did not preserve enough of it, pass-2 errors may
25result.
26<P>
27
28Common conditions that trigger these problems include;
29<P>
30<DL COMPACT>
31<DT>compiler version<DD>
32Prior to GCC version 4.5, debuginfo quality was fairly limited.
33Often developers were advised to build their programs with
34<I>-O0 -g</I>
35
36flags to disable optimization. GCC version 4.5 introduced
37a facility called &quot;variable-tracking assignments&quot; that allows it
38to generate high-quality debuginfo under full
39<I>-O2 -g</I>
40
41optimization. It is not perfect, but much better than before.
42Note that, due to another gcc bug (PR51358)
43<I>-O0 -g</I>
44
45can actually sometimes make debuginfo quality worse than for
46<I>-O2 -g</I>.
47
48<P>
49<DT>function inlining<DD>
50Even modern gcc sometimes has problems with parameters for inlined functions.
51It may be necessary to change the script to probe at a slightly different place
52(try a
53<I>.statement()</I> probe, instead of a <I>.function()</I> probe,
54
55somewhere a few source lines into the body of the inlined function. Or try
56putting a probe at the call site of the inlined function. Or use the
57<I>if @defined($var) { ... }</I>
58
59script language construct to test for the resolvability of the context
60variable before using it.
61<P>
62<DT>instruction reordering<DD>
63Heavily optimized code often smears the instructions from
64multiple source statements together. This can leave systemtap with no place
65to choose to place a probe, especially a statement probe specified by line
66number. Systemtap may advise to try a nearby line number, but these may
67not work well either. Consider placing a probe by a statement wildcard
68or line number range.
69<P>
70</DL>
71<A NAME="lbAD">&nbsp;</A>
72<H2>ALTERNATIVES</H2>
73
74<P>
75In order to reduce reliance on ELF/DWARF debuginfo, consider the use of
76statically compiled-in instrumentation, such as kernel tracepoints, or
77<I>&lt;<A HREF="file:///usr/include/sys/sdt.h">sys/sdt.h</A>&gt;</I>
78
79userspace markers. Such instrumentation hook sites are relatively low
80cost (just one NOP instruction for sdt.h), and nearly guarantee the
81availability of parameter data and a reliable probe site,
82all without reliance on debuginfo.
83<P>
84<A NAME="lbAE">&nbsp;</A>
85<H2>SEE ALSO</H2>
86
87
88<PRE>
89<I><A HREF="stap.1.html">stap</A></I>(1),
90<I><A HREF="http://dwarfstd.org/">http://dwarfstd.org/</A></I>,
91<I><A HREF="http://sourceware.org/systemtap/wiki/TipContextVariables">http://sourceware.org/systemtap/wiki/TipContextVariables</A></I>,
92<I><A HREF="http://gcc.gnu.org/wiki/Var_Tracking_Assignments">http://gcc.gnu.org/wiki/Var_Tracking_Assignments</A></I>,
93<I><A HREF="./warning::debuginfo.7stap.html">warning::debuginfo</A></I>(7stap),
94<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
95
96</PRE>
97<HR>
98<A NAME="index">&nbsp;</A><H2>Index</H2>
99<DL>
100<DT><A HREF="#lbAB">NAME</A><DD>
101<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
102<DT><A HREF="#lbAD">ALTERNATIVES</A><DD>
103<DT><A HREF="#lbAE">SEE ALSO</A><DD>
104</DL>
105<HR>
106This document was created by
107<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
108using the manual pages.<BR>
109Time: 17:59:59 GMT, May 16, 2014
110</BODY>
111</HTML>
diff --git a/man/error::fault.7stap.html b/man/error::fault.7stap.html
new file mode 100644
index 00000000..e0bd1a36
--- /dev/null
+++ b/man/error::fault.7stap.html
@@ -0,0 +1,70 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::FAULT</TITLE>
3</HEAD><BODY>
4<H1>ERROR::FAULT</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::fault - memory access faults
12<P>
13
14
15
16<P>
17<P>
18<A NAME="lbAC">&nbsp;</A>
19<H2>DESCRIPTION</H2>
20
21<P>
22Read or write faults can occur during the operation of a systemtap
23script, if the script causes dereferencing of a pointer that turns out
24to be invalid. This can be caused by using context variables that do
25not happen to have valid values, or perhaps references to memory that
26is unavailable at that moment due to paging.
27<P>
28
29These fault conditions are benign because they are caught by the
30systemtap runtime, which cleanly terminates the script. If quick
31termination is not desired, consider using the
32<I>--skip-badvars</I> or <I>--suppress-handler-errors</I> or <I>-DMAXERRORS=NN</I>
33
34stap options, or wrapping relevant parts of the probe handlers in a
35<I>try</I>/<I>catch</I>
36
37block.
38<P>
39
40It may be possible to adjust the target program, to make it more likely
41that needed context variables are paged in when systemtap looks for them.
42Consider adding some lightweight processing on the key variables, like a
43<I>strlen(foo)</I>
44
45for a string, or iterating acrosse elements of an array or linked list,
46or touching a few bytes of a heap-allocated block. The idea is to trigger
47any page faults in the target program, before systemtap would need to (but can't).
48<A NAME="lbAD">&nbsp;</A>
49<H2>SEE ALSO</H2>
50
51
52<PRE>
53<I><A HREF="stap.1.html">stap</A></I>(1),
54<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
55
56</PRE>
57<HR>
58<A NAME="index">&nbsp;</A><H2>Index</H2>
59<DL>
60<DT><A HREF="#lbAB">NAME</A><DD>
61<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
62<DT><A HREF="#lbAD">SEE ALSO</A><DD>
63</DL>
64<HR>
65This document was created by
66<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
67using the manual pages.<BR>
68Time: 17:59:59 GMT, May 16, 2014
69</BODY>
70</HTML>
diff --git a/man/error::inode-uprobes.7stap.html b/man/error::inode-uprobes.7stap.html
new file mode 100644
index 00000000..953b02c3
--- /dev/null
+++ b/man/error::inode-uprobes.7stap.html
@@ -0,0 +1,65 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::INODE-UPROBES</TITLE>
3</HEAD><BODY>
4<H1>ERROR::INODE-UPROBES</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::inode-uprobes - limitations of inode-uprobes
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>DESCRIPTION</H2>
15
16<P>
17The uprobes kernel facility introduced in Linux 3.5 aims to supplant the
18earlier out-of-tree utrace patch to enable user-space probing. There
19have been some functional limitations in inode-uprobes that preclude
20some systemtap constructs. Over time, we hope these regressions will
21be corrected.
22<P>
23<DL COMPACT>
24<DT>function.return probes<DD>
25<I>process.function().return</I>
26
27probes require &quot;return-probes&quot; or &quot;uretprobes&quot; functionality, which was not
28implemented in the builtin inode-uprobes until kernel 3.10. If you cannot
29upgrade your kernel, consider using
30<I>process.statement()</I>
31
32probes placed on source line numbers at the function's return statements.
33<P>
34<DT>function.statement.absolute probes<DD>
35In utrace-equipped kernels, systemtap made it possible to address probes
36by literal addresses in the process virtual memory address space. The
37new inode-uprobes does not have this capability.
38<P>
39<P>
40</DL>
41<A NAME="lbAD">&nbsp;</A>
42<H2>SEE ALSO</H2>
43
44
45<PRE>
46<I><A HREF="stap.1.html">stap</A></I>(1),
47<I><A HREF="http://kernelnewbies.org/Linux_3.5">http://kernelnewbies.org/Linux_3.5</A></I>,
48<I><A HREF="http://sourceware.org/systemtap/wiki/utrace">http://sourceware.org/systemtap/wiki/utrace</A></I>,
49<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
50
51</PRE>
52<HR>
53<A NAME="index">&nbsp;</A><H2>Index</H2>
54<DL>
55<DT><A HREF="#lbAB">NAME</A><DD>
56<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
57<DT><A HREF="#lbAD">SEE ALSO</A><DD>
58</DL>
59<HR>
60This document was created by
61<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
62using the manual pages.<BR>
63Time: 17:59:59 GMT, May 16, 2014
64</BODY>
65</HTML>
diff --git a/man/error::pass1.7stap.html b/man/error::pass1.7stap.html
new file mode 100644
index 00000000..f55e2bfc
--- /dev/null
+++ b/man/error::pass1.7stap.html
@@ -0,0 +1,93 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::PASS1</TITLE>
3</HEAD><BODY>
4<H1>ERROR::PASS1</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::pass1 - systemtap pass-1 errors
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>DESCRIPTION</H2>
15
16Errors that occur during pass 1 (parsing) usually mean
17a basic syntax error of some sort occurred in the systemtap script.
18There are several classes of problems possible:
19<P>
20<DL COMPACT>
21<DT>plain syntax error<DD>
22The systemtap script parser detects a large variety of errors, such as
23missing operands, bad punctuation. It tries to list what kinds of tokens
24it was expecting to see, and will show the region of the source code with
25the problem. Please review the
26<I><A HREF="stap.1.html">stap</A></I>(1)
27
28man page and/or the tutorial, to correct the script's syntax.
29<P>
30<DT>grammar ambiguities<DD>
31There is at least one known ambiguity in the systemtap grammar. It relates
32to the optionality of
33<I>;</I>
34
35(semicolon) separators between statements, and the
36<I>++</I> and <I>--</I>
37
38increment/decrement operators. If the parser indicates an error, consider
39adding some explicit
40<I>;</I>
41
42separators between nearby statements and try again.
43<P>
44<DT>missing command line arguments<DD>
45A systemtap script that uses the
46<I>$N</I> and <I>@N</I>
47
48constructs for substituting in command-line options may fail if not
49enough options were given on the stap command line.
50<P>
51<DT>compatibility changes<DD>
52Some versions of systemtap have changed the language incompatibly,
53for example by adding the try/catch keywords for exception handling.
54In such cases, rerun systemtap with the
55<I>--compatibility=VERSION</I>
56
57option, substituting the last systemtap version where your script
58was known to work. You may also check the release-history NEWS file
59for compatibility changes.
60<P>
61</DL>
62<A NAME="lbAD">&nbsp;</A>
63<H2>GATHERING MORE INFORMATION</H2>
64
65Increasing the verbosity of pass-1 with an option such as
66<I>--vp 1</I>
67
68can help pinpoint the problem.
69<P>
70<A NAME="lbAE">&nbsp;</A>
71<H2>SEE ALSO</H2>
72
73
74<PRE>
75<I><A HREF="stap.1.html">stap</A></I>(1),
76<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
77
78</PRE>
79<HR>
80<A NAME="index">&nbsp;</A><H2>Index</H2>
81<DL>
82<DT><A HREF="#lbAB">NAME</A><DD>
83<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
84<DT><A HREF="#lbAD">GATHERING MORE INFORMATION</A><DD>
85<DT><A HREF="#lbAE">SEE ALSO</A><DD>
86</DL>
87<HR>
88This document was created by
89<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
90using the manual pages.<BR>
91Time: 17:59:59 GMT, May 16, 2014
92</BODY>
93</HTML>
diff --git a/man/error::pass2.7stap.html b/man/error::pass2.7stap.html
new file mode 100644
index 00000000..55ea6f58
--- /dev/null
+++ b/man/error::pass2.7stap.html
@@ -0,0 +1,141 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::PASS2</TITLE>
3</HEAD><BODY>
4<H1>ERROR::PASS2</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::pass2 - systemtap pass-2 errors
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>DESCRIPTION</H2>
15
16Errors that occur during pass 2 (elaboration) can have a variety of causes.
17Common types include:
18<P>
19<DL COMPACT>
20<DT>unavailable probe point classes<DD>
21Some types of probe points are only available on certain system versions,
22architectures, and configurations. For example, user-space
23<I>process.*</I>
24
25probes may require utrace or uprobes capability in the kernel for this
26architecture.
27<P>
28<DT>unavailable probe points<DD>
29Some probe points may be individually unavailable even when their class is
30fine. For example,
31<I>kprobe.function(foobar)</I>
32
33may fail if function
34<I>foobar</I>
35
36does not exist in the kernel any more. Debugging or symbol data may be absent for
37some types of
38<I>.function</I> or <I>.statement</I>
39
40probes; check for availability of debuginfo. Try the
41<I>stap-prep</I>
42
43program to download possibly-required debuginfo.
44Use a wildcard parameter such as
45<I>stap -l 'kprobe.function(*foo*)'</I>
46
47to locate still-existing variants. Use
48<I>!</I> or <I>?</I>
49
50probe point suffixes to denote optional / preferred-alternatives, to let
51the working parts of a script continue.
52<P>
53<DT>typos<DD>
54There might be a spelling error in the probe point name (&quot;sycsall&quot; vs.
55&quot;syscall&quot;). Wildcard probes may not find a match at all in the
56tapsets. Recheck the names using
57<I>stap -l PROBEPOINT</I>.
58
59Another common mistake is to use the
60<I>.</I>
61
62operator instead of the correct
63<I>-&gt;</I>
64
65when dereferencing context variable subfields or pointers:
66<I>$foo-&gt;bar-&gt;baz</I>
67
68even if in C one would say
69<I>foo-&gt;bar.baz</I>.
70
71<P>
72<DT>unavailable context variables<DD>
73Systemtap scripts often wish to refer to variables from the context of the
74probed programs using
75<I>$variable</I>
76
77notation. These variables may not always be available, depending on versions
78of the compiler, debugging/optimization flags used, architecture, etc. Use
79<I>stap -L PROBEPOINT</I>
80
81to list available context variables for given probes. Use the
82<I>@defined()</I>
83
84expression to test for the resolvability of a context variable expression.
85Consider using the
86<I>stap --skip-badvars</I>
87
88option to silently replace misbehaving context variable expressions with zero.
89<P>
90<DT>module cache inconsistencies<DD>
91Occasionally, the systemtap module cache ($HOME/.systemtap/cache) might
92contain obsolete information from a prior system configuration/version,
93and produce false results as systemtap attempts to reuse it. Retrying
94with
95<I>stap --poison-cache ...</I>
96
97forces new information to be generated.
98<B>Note:</B>
99
100this should not happen and likely represents a systemtap bug. Please
101report it.
102<P>
103</DL>
104<A NAME="lbAD">&nbsp;</A>
105<H2>GATHERING MORE INFORMATION</H2>
106
107Increasing the verbosity of pass-2 with an option such as
108<I>--vp 02</I>
109
110can help pinpoint the problem.
111<P>
112<A NAME="lbAE">&nbsp;</A>
113<H2>SEE ALSO</H2>
114
115
116<PRE>
117<I><A HREF="stap.1.html">stap</A></I>(1),
118<I><A HREF="stap-prep.1.html">stap-prep</A></I>(1),
119<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
120<I>probe::*</I>(3stap),
121<I><A HREF="./error::dwarf.7stap.html">error::dwarf</A></I>(7stap),
122<I><A HREF="./error::inode-uprobes.7stap.html">error::inode-uprobes</A></I>(7stap),
123<I><A HREF="./warning::debuginfo.7stap.html">warning::debuginfo</A></I>(7stap),
124<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
125
126</PRE>
127<HR>
128<A NAME="index">&nbsp;</A><H2>Index</H2>
129<DL>
130<DT><A HREF="#lbAB">NAME</A><DD>
131<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
132<DT><A HREF="#lbAD">GATHERING MORE INFORMATION</A><DD>
133<DT><A HREF="#lbAE">SEE ALSO</A><DD>
134</DL>
135<HR>
136This document was created by
137<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
138using the manual pages.<BR>
139Time: 17:59:59 GMT, May 16, 2014
140</BODY>
141</HTML>
diff --git a/man/error::pass3.7stap.html b/man/error::pass3.7stap.html
new file mode 100644
index 00000000..0bf61cea
--- /dev/null
+++ b/man/error::pass3.7stap.html
@@ -0,0 +1,62 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::PASS3</TITLE>
3</HEAD><BODY>
4<H1>ERROR::PASS3</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::pass3 - systemtap pass-3 errors
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>DESCRIPTION</H2>
15
16Errors during pass 3 (translation) occur only rarely.
17<P>
18<DL COMPACT>
19<DT>unsupported code generation<DD>
20Some script language constructs are not available in every
21probe point. For example, the
22<I>@perf()</I>
23
24counter-reading function may only be used in
25<I>process.*</I>
26
27probes.
28<P>
29</DL>
30<A NAME="lbAD">&nbsp;</A>
31<H2>GATHERING MORE INFORMATION</H2>
32
33Increasing the verbosity of pass-3 with an option such as
34<I>--vp 002</I>
35
36may help pinpoint the problem.
37<P>
38<A NAME="lbAE">&nbsp;</A>
39<H2>SEE ALSO</H2>
40
41
42<PRE>
43<I><A HREF="stap.1.html">stap</A></I>(1),
44<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap)
45<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
46
47</PRE>
48<HR>
49<A NAME="index">&nbsp;</A><H2>Index</H2>
50<DL>
51<DT><A HREF="#lbAB">NAME</A><DD>
52<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
53<DT><A HREF="#lbAD">GATHERING MORE INFORMATION</A><DD>
54<DT><A HREF="#lbAE">SEE ALSO</A><DD>
55</DL>
56<HR>
57This document was created by
58<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
59using the manual pages.<BR>
60Time: 17:59:59 GMT, May 16, 2014
61</BODY>
62</HTML>
diff --git a/man/error::pass4.7stap.html b/man/error::pass4.7stap.html
new file mode 100644
index 00000000..36275cb4
--- /dev/null
+++ b/man/error::pass4.7stap.html
@@ -0,0 +1,86 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::PASS4</TITLE>
3</HEAD><BODY>
4<H1>ERROR::PASS4</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::pass4 - systemtap pass-4 errors
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>DESCRIPTION</H2>
15
16Errors that occur during pass 4 (compilation) have generally only a few
17causes:
18<P>
19<DL COMPACT>
20<DT>kernel or OS version changes<DD>
21The systemtap runtime and embedded-C fragments in the tapset library
22are designed to be portable across a wide range of OS versions. However,
23incompatibilities can occur when some OS changes occur, such as kernel
24modifications that change functions, types, or macros referenced
25by systemtap. Upstream (<A HREF="git://sourceware.org/git/systemtap.git)">git://sourceware.org/git/systemtap.git)</A> builds
26of systemtap are often quickly updated to include relevant fixes, so try
27getting or making an updated build.
28If the issue persists, report the problem to the systemtap developers.
29<P>
30<DT>buggy embedded-C code<DD>
31Embedded-C code in your own guru-mode script cannot be checked by systemtap,
32and is passed through verbatim to the compiler. Errors in such snippets of
33code may be found during the pass-4 compiler invocation, though may be hard
34to identify by the compiler errors.
35<P>
36<DT>incompatible embedded-C code<DD>
37The interface standards between systemtap-generated code and embedded-C code
38occasionally change. For example, before version 1.8, arguments were passed
39using macros
40<I>THIS-&gt;foo</I> and <I>THIS-&gt;__retvalue</I>
41
42but from version 1.8 onward, using
43<I>STAP_ARG_foo</I> and <I>STAP_RETVALUE</I>.
44
45Adjust your embedded-C code to current standards, or use the
46<I>stap --compatible=VERSION</I>
47
48option to make systemtap use a different one.
49<P>
50</DL>
51<A NAME="lbAD">&nbsp;</A>
52<H2>GATHERING MORE INFORMATION</H2>
53
54It may be necessary to run systemtap with
55<I>-k</I> or <I>-p3</I>
56
57to examine the generated C code. Increasing the verbosity of pass-4
58with an option such as
59<I>--vp 0001</I>
60
61can also help pinpoint the problem.
62<P>
63<A NAME="lbAE">&nbsp;</A>
64<H2>SEE ALSO</H2>
65
66
67<PRE>
68<I><A HREF="stap.1.html">stap</A></I>(1),
69<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
70
71</PRE>
72<HR>
73<A NAME="index">&nbsp;</A><H2>Index</H2>
74<DL>
75<DT><A HREF="#lbAB">NAME</A><DD>
76<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
77<DT><A HREF="#lbAD">GATHERING MORE INFORMATION</A><DD>
78<DT><A HREF="#lbAE">SEE ALSO</A><DD>
79</DL>
80<HR>
81This document was created by
82<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
83using the manual pages.<BR>
84Time: 17:59:59 GMT, May 16, 2014
85</BODY>
86</HTML>
diff --git a/man/error::pass5.7stap.html b/man/error::pass5.7stap.html
new file mode 100644
index 00000000..5051ad9c
--- /dev/null
+++ b/man/error::pass5.7stap.html
@@ -0,0 +1,129 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::PASS5</TITLE>
3</HEAD><BODY>
4<H1>ERROR::PASS5</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::pass5 - systemtap pass-5 errors
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>DESCRIPTION</H2>
15
16Errors that occur during pass 5 (execution) can have a variety of causes.
17<P>
18<DL COMPACT>
19<DT>exceptional events during script execution<DD>
20The systemtap translator and runtime include numerous error checks
21that aim to protect the systems and the users from mistakes or
22transient conditions. The script may deliberately call the
23<I>error()</I>
24
25tapset function to signal a problem. Some memory needed for
26accessing
27<I>$context</I>
28
29variables may be temporarily unavailable. Consider using the
30<I>try</I>/<I>catch</I>
31
32construct to wrap script fragments in exception-handling code.
33Consider using the
34<I>stap --suppress-handler-errors</I>
35
36or
37<I>stap --skip-badvars</I>
38
39option.
40<P>
41<DT>resource exhaustion<DD>
42One of several types of space or time resource limits may be
43exceeded by the script, including system overload, too many tuples
44to be stored in an array, etc. Some of the error messages identify
45the constraint by macro name, which may be individually raised.
46Consider using the
47<I>stap --suppress-handler-errors</I>
48
49option. Extend or disable resource limits using the
50<I>stap -DLIMIT=NNNN</I>
51
52option.
53
54<P>
55<DT>remote execution server problems<DD>
56If you use the
57<I>stap --remote</I>
58
59option to direct a systemtap script to be executed somewhere else,
60ensure that an SSH connection may be made to the remote host, and
61that it has the current systemtap runtime installed &amp; available.
62<P>
63<DT>installation/permission problems<DD>
64It is possible that your installation of systemtap was not correctly
65installed. For example, the
66<I>/usr/bin/staprun</I>
67
68program may lack the necessary setuid permissions, or your invoking
69userid might not have sufficient privileges (root, or
70<I>stapusr</I>
71
72and related group memberships). Environment
73variables may interfere with locating
74<I>/usr/libexec/.../stapio</I>.
75
76<P>
77<DT>errors from target program<DD>
78The program invoked by the
79<I>stap -c CMD</I>
80
81option may exit with a non-zero code.
82<P>
83<DT>uncaught exceptions in the target program<DD>
84When using
85<I>--runtime=dyninst</I>
86
87you may encounter an issue where the target program aborts with a
88message like &quot;terminate called after throwing an instance
89of 'foo_exception'&quot;. This is unfortunately a limitation of Dyninst,
90which sometimes prevents exceptions from properly unwinding through
91instrumented code.
92<P>
93<P>
94</DL>
95<A NAME="lbAD">&nbsp;</A>
96<H2>GATHERING MORE INFORMATION</H2>
97
98Increasing the verbosity of pass-5
99with an option such as
100<I>--vp 00001</I>
101
102can help pinpoint the problem.
103<P>
104<A NAME="lbAE">&nbsp;</A>
105<H2>SEE ALSO</H2>
106
107
108<PRE>
109<I><A HREF="stap.1.html">stap</A></I>(1),
110<I><A HREF="http://sourceware.org/systemtap/wiki/TipExhaustedResourceErrors">http://sourceware.org/systemtap/wiki/TipExhaustedResourceErrors</A></I>,
111<I><A HREF="./error::fault.7stap.html">error::fault</A></I>(7stap),
112<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
113
114</PRE>
115<HR>
116<A NAME="index">&nbsp;</A><H2>Index</H2>
117<DL>
118<DT><A HREF="#lbAB">NAME</A><DD>
119<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
120<DT><A HREF="#lbAD">GATHERING MORE INFORMATION</A><DD>
121<DT><A HREF="#lbAE">SEE ALSO</A><DD>
122</DL>
123<HR>
124This document was created by
125<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
126using the manual pages.<BR>
127Time: 17:59:59 GMT, May 16, 2014
128</BODY>
129</HTML>
diff --git a/man/error::process-tracking.7stap.html b/man/error::process-tracking.7stap.html
new file mode 100644
index 00000000..a82cf0a5
--- /dev/null
+++ b/man/error::process-tracking.7stap.html
@@ -0,0 +1,128 @@
1
2<HTML><HEAD><TITLE>Manpage of WARNING::PROCESS-TRACKING</TITLE>
3</HEAD><BODY>
4<H1>WARNING::PROCESS-TRACKING</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11warning::process-tracking - process-tracking facilities are not available
12<P>
13
14
15
16<P>
17<A NAME="lbAC">&nbsp;</A>
18<H2>DESCRIPTION</H2>
19
20These errors and warnings occur when the kernel systemtap is running on
21lacks support for user-space process tracking facilities.
22<P>
23<A NAME="lbAD">&nbsp;</A>
24<H3>COMPILE-TIME ERROR</H3>
25
26The error
27
28<P>
29
30<BR>
31
32<DL COMPACT><DT><DD>
33<PRE>
34ERROR: user-space process-tracking facilities not available
35
36</PRE>
37
38</DL>
39
40
41<P>
42
43occurs when the script contains a uprobes probe point that the current
44kernel does not support.
45<P>
46<A NAME="lbAE">&nbsp;</A>
47<H3>RUNTIME WARNINGS</H3>
48
49<P>
50
51The warning,
52
53<P>
54
55<BR>
56
57<DL COMPACT><DT><DD>
58<PRE>
59WARNING: process-tracking facilities are not available in this kernel
60
61</PRE>
62
63</DL>
64
65
66<P>
67
68and the related message,
69
70<P>
71
72<BR>
73
74<DL COMPACT><DT><DD>
75<PRE>
76WARNING: cannot track target in process '...'
77
78</PRE>
79
80</DL>
81
82
83<P>
84
85both occur at runtime when running on a kernel (generally an older
86version) that has neither utrace functionality nor an acceptable
87substitute.
88<P>
89
90The script should still load and run. However, probes that rely on
91availability of process-tracking facilities will silently fail to
92trigger.
93<P>
94<A NAME="lbAF">&nbsp;</A>
95<H2>RESOLVING THE ISSUE</H2>
96
97If process-tracking functionality is absolutely necessary, either a
98kernel version newer than 3.5 is needed, or an older version must be
99compiled with appropriate utrace patches.
100<P>
101<A NAME="lbAG">&nbsp;</A>
102<H2>SEE ALSO</H2>
103
104
105<PRE>
106<I><A HREF="stap.1.html">stap</A></I>(1),
107<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
108
109</PRE>
110<HR>
111<A NAME="index">&nbsp;</A><H2>Index</H2>
112<DL>
113<DT><A HREF="#lbAB">NAME</A><DD>
114<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
115<DL>
116<DT><A HREF="#lbAD">COMPILE-TIME ERROR</A><DD>
117<DT><A HREF="#lbAE">RUNTIME WARNINGS</A><DD>
118</DL>
119<DT><A HREF="#lbAF">RESOLVING THE ISSUE</A><DD>
120<DT><A HREF="#lbAG">SEE ALSO</A><DD>
121</DL>
122<HR>
123This document was created by
124<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
125using the manual pages.<BR>
126Time: 17:59:59 GMT, May 16, 2014
127</BODY>
128</HTML>
diff --git a/man/error::reporting.7stap.html b/man/error::reporting.7stap.html
new file mode 100644
index 00000000..de133ea8
--- /dev/null
+++ b/man/error::reporting.7stap.html
@@ -0,0 +1,77 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::REPORTING</TITLE>
3</HEAD><BODY>
4<H1>ERROR::REPORTING</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::reporting - systemtap error reporting
12<P>
13<P>
14<A NAME="lbAC">&nbsp;</A>
15<H2>COMMERCIAL SUPPORT</H2>
16
17If you have a commercial support agreement with your OS distributor
18that covers this software, we recommend getting your money's worth
19by using their problem reporting systems first.
20<P>
21<A NAME="lbAD">&nbsp;</A>
22<H2>COMMUNITY SUPPORT</H2>
23
24Systemtap community &amp; volunteer developers are eager to hear problem
25reports, so they can improve the software. Various ways to contact them
26include:
27<P>
28<DL COMPACT>
29<DT>public mailing list<DD>
30<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>
31<P>
32<DT>public IRC<DD>
33#systemtap on irc.freenode.net, use fpaste.org for snippets of text
34<P>
35<DT>public bugzilla<DD>
36<A HREF="http://sourceware.org/bugzilla/">http://sourceware.org/bugzilla/</A>
37<P>
38</DL>
39<A NAME="lbAE">&nbsp;</A>
40<H2>INFORMATION TO COLLECT</H2>
41
42In general, please include information about your platform,
43systemtap version, your scripts &amp; custom tapsets, systemtap
44invocation, actual behavior / errors seen, and expected behavior.
45The
46<I>stap-report</I>
47
48script collects useful system/kernel information that helps describe
49the OS environment; please include its output.
50<P>
51<A NAME="lbAF">&nbsp;</A>
52<H2>SEE ALSO</H2>
53
54
55<PRE>
56<I><A HREF="stap.1.html">stap</A></I>(1),
57<I><A HREF="stap-report.1.html">stap-report</A></I>(1),
58<I><A HREF="http://sourceware.org/systemtap/wiki/">http://sourceware.org/systemtap/wiki/</A></I>
59
60
61</PRE>
62<HR>
63<A NAME="index">&nbsp;</A><H2>Index</H2>
64<DL>
65<DT><A HREF="#lbAB">NAME</A><DD>
66<DT><A HREF="#lbAC">COMMERCIAL SUPPORT</A><DD>
67<DT><A HREF="#lbAD">COMMUNITY SUPPORT</A><DD>
68<DT><A HREF="#lbAE">INFORMATION TO COLLECT</A><DD>
69<DT><A HREF="#lbAF">SEE ALSO</A><DD>
70</DL>
71<HR>
72This document was created by
73<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
74using the manual pages.<BR>
75Time: 17:59:59 GMT, May 16, 2014
76</BODY>
77</HTML>
diff --git a/man/error::sdt.7stap.html b/man/error::sdt.7stap.html
new file mode 100644
index 00000000..a0c9de29
--- /dev/null
+++ b/man/error::sdt.7stap.html
@@ -0,0 +1,120 @@
1
2<HTML><HEAD><TITLE>Manpage of ERROR::SDT</TITLE>
3</HEAD><BODY>
4<H1>ERROR::SDT</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11error::sdt - &lt;<A HREF="file:///usr/include/sys/sdt.h">sys/sdt.h</A>&gt; marker failures
12<P>
13
14
15
16<P>
17<P>
18<A NAME="lbAC">&nbsp;</A>
19<H2>DESCRIPTION</H2>
20
21<P>
22Systemtap's
23<B>&lt;<A HREF="file:///usr/include/sys/sdt.h">sys/sdt.h</A>&gt;</B>
24
25probes are modeled after the dtrace USDT API, but are implemented
26differently. They leave a only a NOP instruction in the userspace
27program's text segment, and add an ELF note to the binary with
28metadata. This metadata describes the marker's name and parameters.
29This encoding is designed to be parseable by multiple tools (not just
30systemtap: GDB, the GNU Debugger, also contains support). These allow
31the tools to find parameters and their types, wherever they happen to
32reside, even without DWARF debuginfo.
33<P>
34<P>
35
36<P>
37The reason finding parameters is tricky is because the STAP_PROBE /
38DTRACE_PROBE markers store an assembly language expression for each
39operand, as a result of use of gcc inline-assembly directives. The
40compiler is given a broad gcc operand constraint string (&quot;nor&quot;) for
41the operands, which usually works well. Usually, it does not force
42the compiler to load the parameters into or out of registers, which
43would slow down an instrumented program. However, some
44instrumentation sites with some parameters do not work well with the
45default &quot;nor&quot; constraint.
46<P>
47<DL COMPACT>
48<DT>unresolveable at run-time<DD>
49GCC may emit strings that an assembler could resolve (from the
50context of compiling the original program), but a run-time tool
51cannot. For example, the operand string might refer to a label of a
52local symbol that is not emitted into the ELF object file at all,
53which leaves no trace for the run-time. Reference to such parameters
54from within systemtap can result in &quot;SDT asm not understood&quot; errors.
55<P>
56<DT>too complicated expression<DD>
57GCC might synthesize very complicated assembly addressing modes from
58complex C data types / pointer expressions. systemtap or gdb may not
59be able to parse some valid but complicated expressions. Reference to
60such parameters from within systemtap can result in &quot;SDT asm not
61understood&quot; errors.
62<P>
63<DT>overly restrictive constraint<DD>
64GCC might not be able to even compile the original program with the
65default &quot;nor&quot; constraint due to shortage of registers or other
66reasons. A compile-time gcc error such as &quot;asm operand has impossible
67constraints&quot; may result.
68<P>
69</DL>
70<P>
71
72<P>
73There are two general workarounds to this family of problems.
74<P>
75<DL COMPACT>
76<DT>change the constraints<DD>
77While compiling the original instrumented program, set the
78<I>STAP_SDT_ARG_CONSTRAINT</I>
79
80macro to different constraint strings. See the GCC manual about
81various options. For example, on many machine architectures, &quot;r&quot; forces
82operands into registers, and &quot;g&quot; leaves operands essentially unconstrained.
83<P>
84<DT>revert to debuginfo<DD>
85As long as the instrumented program compiles, it may be fine simply to
86keep using &lt;<A HREF="file:///usr/include/sys/sdt.h">sys/sdt.h</A>&gt; but eschew extraction of a few individual
87parameters. In the worst case, disable &lt;<A HREF="file:///usr/include/sys/sdt.h">sys/sdt.h</A>&gt; macros entirely to
88eschew the compiled-in instrumentation. If DWARF debuginfo was
89generated and preserved, a systemtap script could refer to the
90underlying source context variables instead of the positional
91STAP_PROBE parameters.
92<P>
93</DL>
94<A NAME="lbAD">&nbsp;</A>
95<H2>SEE ALSO</H2>
96
97
98<PRE>
99<I><A HREF="stap.1.html">stap</A></I>(1),
100<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
101<I><A HREF="./error::dwarf.7stap.html">error::dwarf</A></I>(7stap),
102<I><A HREF="http://gcc.gnu.org/onlinedocs/gcc/Constraints.html">http://gcc.gnu.org/onlinedocs/gcc/Constraints.html</A></I>,
103<I><A HREF="http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation">http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation</A></I>,
104<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap)
105
106</PRE>
107<HR>
108<A NAME="index">&nbsp;</A><H2>Index</H2>
109<DL>
110<DT><A HREF="#lbAB">NAME</A><DD>
111<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
112<DT><A HREF="#lbAD">SEE ALSO</A><DD>
113</DL>
114<HR>
115This document was created by
116<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
117using the manual pages.<BR>
118Time: 17:59:59 GMT, May 16, 2014
119</BODY>
120</HTML>
diff --git a/man/index.html b/man/index.html
new file mode 100644
index 00000000..d5243ce6
--- /dev/null
+++ b/man/index.html
@@ -0,0 +1,30 @@
1<html><head><title>systemtap man page index</title></head><body><ul>
2<li><a href="./dtrace.1.html">dtrace.1</a></li>
3<li><a href="./stap.1.html">stap.1</a></li>
4<li><a href="./stap-merge.1.html">stap-merge.1</a></li>
5<li><a href="./stap-prep.1.html">stap-prep.1</a></li>
6<li><a href="./stap-report.1.html">stap-report.1</a></li>
7<li><a href="./stapex.3stap.html">stapex.3stap</a></li>
8<li><a href="./stapfuncs.3stap.html">stapfuncs.3stap</a></li>
9<li><a href="./stapprobes.3stap.html">stapprobes.3stap</a></li>
10<li><a href="./stapvars.3stap.html">stapvars.3stap</a></li>
11<li><a href="./error::buildid.7stap.html">error::buildid.7stap</a></li>
12<li><a href="./error::dwarf.7stap.html">error::dwarf.7stap</a></li>
13<li><a href="./error::fault.7stap.html">error::fault.7stap</a></li>
14<li><a href="./error::inode-uprobes.7stap.html">error::inode-uprobes.7stap</a></li>
15<li><a href="./error::pass1.7stap.html">error::pass1.7stap</a></li>
16<li><a href="./error::pass2.7stap.html">error::pass2.7stap</a></li>
17<li><a href="./error::pass3.7stap.html">error::pass3.7stap</a></li>
18<li><a href="./error::pass4.7stap.html">error::pass4.7stap</a></li>
19<li><a href="./error::pass5.7stap.html">error::pass5.7stap</a></li>
20<li><a href="./error::process-tracking.7stap.html">error::process-tracking.7stap</a></li>
21<li><a href="./error::reporting.7stap.html">error::reporting.7stap</a></li>
22<li><a href="./error::sdt.7stap.html">error::sdt.7stap</a></li>
23<li><a href="./stappaths.7.html">stappaths.7</a></li>
24<li><a href="./warning::debuginfo.7stap.html">warning::debuginfo.7stap</a></li>
25<li><a href="./stapdyn.8.html">stapdyn.8</a></li>
26<li><a href="./staprun.8.html">staprun.8</a></li>
27<li><a href="./stap-server.8.html">stap-server.8</a></li>
28<li><a href="./stapsh.8.html">stapsh.8</a></li>
29<li><a href="./systemtap.8.html">systemtap.8</a></li>
30</ul></body></html>
diff --git a/man/stap-merge.1.html b/man/stap-merge.1.html
new file mode 100644
index 00000000..4f8493f2
--- /dev/null
+++ b/man/stap-merge.1.html
@@ -0,0 +1,185 @@
1
2<HTML><HEAD><TITLE>Manpage of STAP-MERGE</TITLE>
3</HEAD><BODY>
4<H1>STAP-MERGE</H1>
5Section: User Commands (1)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stap-merge - systemtap per-cpu binary merger
12<P>
13
14
15
16
17<P>
18<A NAME="lbAC">&nbsp;</A>
19<H2>SYNOPSIS</H2>
20
21<P>
22<BR>
23
24<B>stap-merge</B>
25
26[
27<I>OPTIONS</I>
28
29]
30[
31<I>INPUT FILENAMES</I>
32
33]
34<P>
35<A NAME="lbAD">&nbsp;</A>
36<H2>DESCRIPTION</H2>
37
38<P>
39The stap-merge executable applies when the -b option has been used
40while running a
41<I>stap</I>
42
43script. The -b option will generate files
44per-cpu, based on the timestamp field. Then stap-merge will
45merge and sort through the per-cpu files based on the timestamp
46field.
47<P>
48<A NAME="lbAE">&nbsp;</A>
49<H2>OPTIONS</H2>
50
51<P>
52The systemtap merge executable supports the following options.
53<DL COMPACT>
54<DT><B>-v</B>
55
56<DD>
57Verbose mode, displays three extra fields per set of collected data.
58
59<BR>
60
61<P>
62
63<DL COMPACT><DT><DD>
64<PRE>
65<B>[cpu</B>number,<B>sequence</B>number<B>of</B>data,<B>the</B>length<B>of</B>the<B>data</B>set]
66
67</PRE>
68
69</DL>
70
71
72<P>
73
74<DT><B>-o</B><I> OUTPUT_FILENAME</I>
75
76<DD>
77<P>
78Specify the name of the file you would like the output to be
79redirected into. If this option is not specified than the
80output will be pushed to standard out.
81<P>
82</DL>
83<A NAME="lbAF">&nbsp;</A>
84<H2>EXAMPLES</H2>
85
86
87<BR>
88
89<P>
90
91<DL COMPACT><DT><DD>
92<PRE>
93$ stap -v -b -e 'probe syscall.open { printf(&quot;%s(%d) open\n&quot;,
94execname(), pid()) }'
95
96
97</PRE>
98
99</DL>
100
101
102<P>
103
104<P>
105This should result in several
106<I>stpd_cpu</I>
107
108files (each labled with a number
109representing which cpu the file was produced from).
110<P>
111
112<BR>
113
114<P>
115
116<DL COMPACT><DT><DD>
117<PRE>
118$ stap-merge -v stpd_cpu0 stpd_cpu1
119
120
121</PRE>
122
123</DL>
124
125
126<P>
127
128<P>
129Running the stap-merge program in the same directory as the stap
130script earlier in the example, will produce an ordered sequence of
131packets with the three part label for each set of data. This
132result will be pushed through the standard output. An output file
133could have been specified using the &quot;-o&quot; option.
134<P>
135<A NAME="lbAG">&nbsp;</A>
136<H2>FILES</H2>
137
138<P>
139<DL COMPACT>
140<DT>Important files and their corresponding paths can be located in the <DD>
141stappaths (7) manual page.
142<P>
143</DL>
144<A NAME="lbAH">&nbsp;</A>
145<H2>SEE ALSO</H2>
146
147
148<PRE>
149<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
150<I><A HREF="stappaths.7.html">stappaths</A></I>(7),
151<I><A HREF="staprun.8.html">staprun</A></I>(8),
152<I><A HREF="stapvars.3stap.html">stapvars</A></I>(3stap),
153<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap),
154<I><A HREF="stap-server.8.html">stap-server</A></I>(8),
155<I><A HREF="gdb.1.html">gdb</A></I>(1)
156
157</PRE><A NAME="lbAI">&nbsp;</A>
158<H2>BUGS</H2>
159
160Use the Bugzilla link of the project web page or our mailing list.
161
162<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>,<B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
163
164
165<P>
166
167<HR>
168<A NAME="index">&nbsp;</A><H2>Index</H2>
169<DL>
170<DT><A HREF="#lbAB">NAME</A><DD>
171<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
172<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
173<DT><A HREF="#lbAE">OPTIONS</A><DD>
174<DT><A HREF="#lbAF">EXAMPLES</A><DD>
175<DT><A HREF="#lbAG">FILES</A><DD>
176<DT><A HREF="#lbAH">SEE ALSO</A><DD>
177<DT><A HREF="#lbAI">BUGS</A><DD>
178</DL>
179<HR>
180This document was created by
181<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
182using the manual pages.<BR>
183Time: 17:59:59 GMT, May 16, 2014
184</BODY>
185</HTML>
diff --git a/man/stap-prep.1.html b/man/stap-prep.1.html
new file mode 100644
index 00000000..7c224cc5
--- /dev/null
+++ b/man/stap-prep.1.html
@@ -0,0 +1,99 @@
1
2<HTML><HEAD><TITLE>Manpage of STAP-PREP</TITLE>
3</HEAD><BODY>
4<H1>STAP-PREP</H1>
5Section: User Commands (1)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stap-prep - prepare system for systemtap use
12<P>
13
14
15
16
17<P>
18<A NAME="lbAC">&nbsp;</A>
19<H2>SYNOPSIS</H2>
20
21<P>
22<BR>
23
24<B>stap-prep</B>
25
26[
27<I>KERNEL_VERSION</I>
28
29]
30<P>
31<A NAME="lbAD">&nbsp;</A>
32<H2>DESCRIPTION</H2>
33
34<P>
35The stap-prep executable prepares the system for systemtap use by
36installing kernel headers, debug symbols and build tools that match
37the currently running kernel or optionally the kernel version given by
38the user.
39<P>
40The exact behavior of stap-prep may be customized by the
41distribution maintainers. It might for example only give suggestions
42and not actually install the required packages if that is difficult to
43automate.
44<P>
45<A NAME="lbAE">&nbsp;</A>
46<H2>EXAMPLES</H2>
47
48
49<BR>
50
51<P>
52
53<DL COMPACT><DT><DD>
54<PRE>
55$ stap-prep
56Please install linux-image-3.2.0-2-amd64-dbg
57
58</PRE>
59
60</DL>
61
62
63<P>
64
65<P>
66<A NAME="lbAF">&nbsp;</A>
67<H2>SEE ALSO</H2>
68
69
70<PRE>
71<I><A HREF="stap.1.html">stap</A></I>(1)
72
73</PRE><A NAME="lbAG">&nbsp;</A>
74<H2>BUGS</H2>
75
76Use the Bugzilla link of the project web page or our mailing list.
77
78<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>,<B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
79
80
81<P>
82
83<HR>
84<A NAME="index">&nbsp;</A><H2>Index</H2>
85<DL>
86<DT><A HREF="#lbAB">NAME</A><DD>
87<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
88<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
89<DT><A HREF="#lbAE">EXAMPLES</A><DD>
90<DT><A HREF="#lbAF">SEE ALSO</A><DD>
91<DT><A HREF="#lbAG">BUGS</A><DD>
92</DL>
93<HR>
94This document was created by
95<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
96using the manual pages.<BR>
97Time: 17:59:59 GMT, May 16, 2014
98</BODY>
99</HTML>
diff --git a/man/stap-report.1.html b/man/stap-report.1.html
new file mode 100644
index 00000000..6228712a
--- /dev/null
+++ b/man/stap-report.1.html
@@ -0,0 +1,101 @@
1
2<HTML><HEAD><TITLE>Manpage of STAP-REPORT</TITLE>
3</HEAD><BODY>
4<H1>STAP-REPORT</H1>
5Section: User Commands (1)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stap-report - collect system information that is useful for debugging systemtap bugs
12<P>
13
14
15
16
17<P>
18<A NAME="lbAC">&nbsp;</A>
19<H2>SYNOPSIS</H2>
20
21<P>
22<BR>
23
24<B>stap-report</B>
25
26<P>
27<A NAME="lbAD">&nbsp;</A>
28<H2>DESCRIPTION</H2>
29
30<P>
31The stap-report executable collects system information that is useful
32for debugging systemtap bugs. It is a good idea to include such a
33report in bug reports especially if you send them directly to the
34upstream. stap-report can be run either as a normal user or as
35root. The report will be more complete if stap-report is run as root.
36<P>
37<A NAME="lbAE">&nbsp;</A>
38<H2>EXAMPLES</H2>
39
40
41<BR>
42
43<P>
44
45<DL COMPACT><DT><DD>
46<PRE>
47$ stap-report &gt; report.txt
48$ head report.txt
49== id ==
50uid=1000(user) gid=1000(user) groups=122(stapdev),123(stapusr),129(stapsys)
51== stap -V ==
52Systemtap translator/driver (version 2.2.1/0.153, Debian version 2.2.1-1)
53Copyright (C) 2005-2013 Red Hat, Inc. and others
54This is free software; see the source for copying conditions.
55enabled features: AVAHI LIBSQLITE3 NSS TR1_UNORDERED_MAP NLS
56== which stap ==
57/usr/bin/stap
58== locate --regex '/stap(run)?$' | xargs ls -ald ==
59
60</PRE>
61
62</DL>
63
64
65<P>
66
67<P>
68<A NAME="lbAF">&nbsp;</A>
69<H2>SEE ALSO</H2>
70
71
72<PRE>
73<I><A HREF="stap.1.html">stap</A></I>(1)
74
75</PRE><A NAME="lbAG">&nbsp;</A>
76<H2>BUGS</H2>
77
78Use the Bugzilla link of the project web page or our mailing list.
79
80<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>,<B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
81
82
83<P>
84
85<HR>
86<A NAME="index">&nbsp;</A><H2>Index</H2>
87<DL>
88<DT><A HREF="#lbAB">NAME</A><DD>
89<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
90<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
91<DT><A HREF="#lbAE">EXAMPLES</A><DD>
92<DT><A HREF="#lbAF">SEE ALSO</A><DD>
93<DT><A HREF="#lbAG">BUGS</A><DD>
94</DL>
95<HR>
96This document was created by
97<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
98using the manual pages.<BR>
99Time: 17:59:59 GMT, May 16, 2014
100</BODY>
101</HTML>
diff --git a/man/stap-server.8.html b/man/stap-server.8.html
new file mode 100644
index 00000000..d07d7aaa
--- /dev/null
+++ b/man/stap-server.8.html
@@ -0,0 +1,786 @@
1
2<HTML><HEAD><TITLE>Manpage of STAP-SERVER</TITLE>
3</HEAD><BODY>
4<H1>STAP-SERVER</H1>
5Section: Maintenance Commands (8)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stap-server - systemtap compile server management
12<P>
13
14
15
16<P>
17<A NAME="lbAC">&nbsp;</A>
18<H2>SYNOPSIS</H2>
19
20<P>
21<BR>
22
23[
24<B>service</B>
25
26]
27<B>stap-server</B>
28
29{
30<B>start</B>
31
32|
33<B>stop</B>
34
35|
36<B>restart</B>
37
38|
39<B>condrestart</B>
40
41|
42<B>try-restart</B>
43
44|
45<B>force-reload</B>
46
47|
48<B>status</B>
49
50} [
51<I>options</I>
52
53]
54<P>
55<A NAME="lbAD">&nbsp;</A>
56<H2>DESCRIPTION</H2>
57
58<P>
59A systemtap compile server listens for connections from stap clients
60on a secure SSL network port and accepts requests to run the
61<I>stap</I>
62
63front end. Each server advertises its presence and configuration on the local
64network using mDNS (<I>avahi</I>) allowing for automatic detection by clients.
65<P>
66<P>
67
68The stap-server script aims to provide:
69<DL COMPACT>
70<DT>&bull;<DD>
71management of systemtap compile servers as a service.
72<DT>&bull;<DD>
73convenient control over configured servers and individual (ad-hoc) servers.
74<P>
75</DL>
76<A NAME="lbAE">&nbsp;</A>
77<H2>ARGUMENTS</H2>
78
79One of the actions below must be specified:
80<DL COMPACT>
81<DT><B>start</B>
82
83<DD>
84Start servers. The specified servers are started.
85If no server is specified, the configured servers are started. If no servers
86are configured, a server for the kernel release and architecture of the host
87is started.
88If a specified server is
89already started, this action will
90be ignored for that server. If a server fails to start, this action fails.
91<P>
92<DT><B>stop</B>
93
94<DD>
95Stop server(s). The specified servers are stopped.
96If no server is specified, all currently running servers are stopped.
97If a specified server is
98not running, this action
99will be successful for that server. If a server fails to stop, this action
100fails.
101<P>
102<DT><B>restart</B>
103
104<DD>
105Stop and restart servers. The specified servers are stopped and restarted.
106If no server is specified, all currently running servers are stopped and
107restarted. If no servers are running, this action behaves like <I>start</I>.
108<P>
109<DT><B>condrestart</B>
110
111<DD>
112Stop and restart servers. The specified servers are stopped and restarted.
113If a specified server is not running, it is not started. If no server is
114specified, all currently running servers are stopped and restarted. If no
115servers are running, none will be started.
116<P>
117<DT><B>try-restart</B>
118
119<DD>
120This action is identical to <I>condrestart</I>.
121<P>
122<DT><B>force-reload</B>
123
124<DD>
125Stop all running servers, reload config files and restart the service as if
126<I>start</I>
127
128was specified.
129<P>
130<DT><B>status</B>
131
132<DD>
133Print information about running servers. Information about the specified
134server(s) will be printed. If no server is specified, information about all
135running servers will be printed.
136<P>
137</DL>
138<A NAME="lbAF">&nbsp;</A>
139<H2>OPTIONS</H2>
140
141The following options are used to provide additional configuration and
142to specify servers to be managed:
143<P>
144<DL COMPACT>
145<DT><B>-c</B> <I>configfile</I><DD>
146This option specifies a global configuration file in addition to the default
147global configuration file described
148below. This file will be processed after the default global
149configuration file. If the <B>-c</B> option is specified more than once, the
150last
151configuration file specified will be used.
152<P>
153<DT><B>-a</B> <I>architecture</I><DD>
154This option specifies the target architecture of the server and is
155analogous to the <B>-a</B> option of <I>stap</I>. See the
156<I><A HREF="stap.1.html">stap</A></I>(1)
157
158manual page for more details.
159The default architecture is the architecture of the host.
160<P>
161<DT><B>-r</B> <I>kernel-release</I><DD>
162This option specifies the target kernel release of the server and is
163analogous to the <B>-r</B> option of <I>stap</I>. See the
164<I><A HREF="stap.1.html">stap</A></I>(1)
165
166manual page for more details.
167The default release is that of the currently running kernel.
168<P>
169<DT><B>-I</B> <I>path</I><DD>
170This option specifies an additional path to be searched by the server(s) for
171tapsets and is analogous to the <B>-I</B> option of <I>stap</I>.
172See the
173<I><A HREF="stap.1.html">stap</A></I>(1)
174
175manual page for more details.
176<P>
177<DT><B>-R</B> <I>path</I><DD>
178This option specifies the location of the systemtap runtime to be used by the
179server(s) and is analogous to the <B>-R</B> option of <I>stap</I>.
180See the
181<I><A HREF="stap.1.html">stap</A></I>(1)
182
183manual page for more details.
184<P>
185<DT><B>-B</B> <I>options</I><DD>
186This option specifies options to be passed to <I>make</I> when building systemtap
187modules and is analogous to the <B>-B</B> option of <I>stap</I>.
188See the
189<I><A HREF="stap.1.html">stap</A></I>(1)
190
191manual page for more details.
192<P>
193<DT><B>-i</B><DD>
194This option is a shortcut which specifies one server for each kernel
195release installed in <I>/lib/modules/</I>. Previous
196<B>-I</B>, <B>-R</B>, <B>-B</B> and <B>-u</B> options will be
197applied to each server, however previous <B>-a</B> options will be ignored and
198the default architecture will be used.
199<P>
200<DT><B>-n</B> <I>nickname</I><DD>
201This option allows the specification of a server configuration by nickname.
202When <B>-n</B> is specified, a currently running server with the given nickname
203will be searched for. If no currently running server with the given nickname is
204found, a server configuration with the given nickname will be searched for in
205the configuration files for default servers,
206or the path configured in the global configuration file or
207the configuration file specified by the
208<B>-c</B> option. If a server configuration for the given
209nickname is found, the
210<B>-a</B>, <B>-r</B>, <B>-I</B>, <B>-R</B>, <B>-B</B> and <B>-u</B> options for
211that server will be used as if they were specified on the command line. If no
212configuration with the given nickname is found, and the action is
213<I>start</I>
214
215(or an action behaving like <I>start</I>
216(see <B>ARGUMENTS</B>), the server will be started with the given nickname.
217If no configuration with the given nickname is found, and the action is not
218<I>start</I>
219
220(or an action behaving like <I>start</I>), it is an error. If a nickname is
221not specified for a server which is being started, its nickname will be its
222process id.
223<P>
224<DT><B>-p</B> <I>pid</I><DD>
225This option allows the specification of a server configuration by process id.
226When <B>-p</B> is specified, a currently running server with the given process
227id will be searched for. If no such server is found, it is an error. If a server
228with the given procss id is found, the
229<B>-a</B>, <B>-r</B>, <B>-I</B>, <B>-R</B>, <B>-B</B> and <B>-u</B> options for
230that server will be used as if they were specified on the command line.
231<P>
232<DT><B>-u</B> <I>user-name</I><DD>
233Each systemtap compile server is normally run by the user name
234<I>stap-server</I> (for the initscript) or as the user invoking
235<I>stap-server</I>,
236unless otherwise configured (see <B>FILES</B>). This option
237specifies the user name used to run the server(s). The user name specified
238must be a member of the group <I>stap-server</I>.
239<P>
240<DT><B>--log</B> <I>logfile</I><DD>
241This option allows the specification of a separate log file for each server.
242Each --log option is added to a list which will be applied, in turn, to each
243server specified. If more servers are specified than --log options, the default
244log file (see <B>FILES</B>) will be used for subsequent servers.
245<P>
246<DT><B>--port</B> <I>port-number</I><DD>
247This option allows the specification of a specific network port for each
248server. Each --port option is added to a list which will be applied, in turn,
249to each server specified. If more servers are specified than
250--port options, a randomly selected port is used for subsequent servers.
251<P>
252<DT><B>--ssl</B> <I>certificate-db-path</I><DD>
253This option allows the specification of a separate NSS certificate database
254for each server. Each --ssl option is added to a list which will be applied,
255in turn, to each server specified. If more servers are specified than --ssl
256options, the default certificate database
257(see <B>FILES</B>) for subsequent servers.
258<P>
259<DT><B>--max-threads</B> <I>threads</I><DD>
260This option allows the specification of the maximum number of worker threads
261to handle concurrent requests. If <I>threads</I> == 0, each request will be
262handled on the main thread, serially. The default is the number of available
263processor cores.
264<P>
265</DL>
266<A NAME="lbAG">&nbsp;</A>
267<H2>CONFIGURATION</H2>
268
269<P>
270Configuration files allow us to:
271<DL COMPACT>
272<DT>&bull;<DD>
273specify global configuration of logging, server configuration files, status
274files and other global parameters.
275<DT>&bull;<DD>
276specify which servers are to be started by default.
277<P>
278</DL>
279<A NAME="lbAH">&nbsp;</A>
280<H2>Global Configuration</H2>
281
282<P>
283The Global Configuration file contains
284variable assignments used to configure the overall operation of the service.
285Each line beginning with a '#' character is ignored. All other lines must be
286of the form <I>VARIABLE=VALUE</I>. This is not a shell script. The entire
287contents of the line after the = will be assigned as-is to the variable.
288<P>
289The following variables may be assigned:
290<P>
291<DL COMPACT>
292<DT><B>CONFIG_PATH</B>
293
294<DD>
295Specifies the absolute path of the directory containing the default server
296configurations.
297<P>
298<DT><B>STAT_PATH</B>
299
300<DD>
301Specifies the absolute path of the running server status directory.
302<P>
303<DT><B>LOG_FILE</B>
304
305<DD>
306Specifies the absolute path of the log file.
307<P>
308<DT><B>STAP_USER</B>
309
310<DD>
311Specifies the userid which will be used to run the server(s)
312(default: for the initscript <I>stap-server</I>, otherwise the user running
313<I>stap-server</I>).
314<P>
315</DL>
316<P>
317
318Here is an example of a Global Configuration file:
319
320<P>
321
322<BR>
323
324<DL COMPACT><DT><DD>
325<PRE>
326CONFIG_PATH=~&lt;user&gt;/my-stap-server-configs
327LOG_FILE=/tmp/stap-server/log
328
329</PRE>
330
331</DL>
332
333
334<P>
335
336<P>
337<A NAME="lbAI">&nbsp;</A>
338<H2>Individual Server Configuration</H2>
339
340<P>
341Each server configuration file configures a server to be started when no
342server is specified for the <I>start</I> action, or an action behaving like the
343<I>start</I> action (see <I>ARGUMENTS</I>). Each configuration file contains
344variable assignments used to configure an individual server.
345<P>
346Each line beginning with a '#' character is ignored. All other lines must be
347of the form <I>VARIABLE=VALUE</I>. This is not a shell script. The entire
348contents of the line after the = will be assigned as-is to the variable.
349<P>
350Each configuration file must have a filename suffix of <I>.conf</I>. See
351<I><A HREF="stappaths.7.html">stappaths</A></I>(7) for the default location of these files. This default
352location can be overridden in the global configuration file using the <B>-c</B>
353option (see <I>OPTIONS</I>).
354<P>
355The following variables may be assigned:
356<DL COMPACT>
357<DT><B>ARCH</B>
358
359<DD>
360Specifies the target architecture for this server and corresponds to the
361<B>-a</B> option (see <I>OPTIONS</I>). If <B>ARCH</B> is not set, the
362architecture of the host will be used.
363<P>
364<DT><B>RELEASE</B>
365
366<DD>
367Specifies the kernel release for this server
368and corresponds to the
369<B>-r</B> option (see <I>OPTIONS</I>). If <B>RELEASE</B> is not set, the
370release
371of the kernel running on the host will be used.
372<BR>&nbsp;
373<DT><B>BUILD</B>
374
375<DD>
376Specifies options to be passed to the <I>make</I> process used by
377<I>systemtap</I> to build kernel modules.
378This an array variable with each element corresponding to a
379<B>-B</B> option (see <I>OPTIONS</I>). Using the form <B>BUILD=STRING</B> clears
380the array and sets the first element to <B>STRING</B>. Using the form
381<B>BUILD+=STRING</B> adds <B>STRING</B> as an additional element to the array.
382<BR>&nbsp;
383<DT><B>INCLUDE</B>
384
385<DD>
386Specifies a list of directories to be searched by the server for tapsets.
387This is an array variable with each element corresponding to a
388<B>-I</B> option (see <I>OPTIONS</I>). Using the form <B>INCLUDE=PATH</B> clears
389the array and sets the first element to <B>PATH</B>. Using the form
390<B>INCLUDE+=PATH</B> adds <B>PATH</B> as an additional element to the array.
391<P>
392<DT><B>RUNTIME</B>
393
394<DD>
395Specifies the directory which contains the systemtap runtime code to be used
396by this server
397and corresponds to the
398<B>-R</B> option (see <I>OPTIONS</I>).
399<P>
400<DT><B>USER</B>
401
402<DD>
403Specifies the user name to be used to run this server
404and corresponds to the
405<B>-u</B> option (see <I>OPTIONS</I>).
406<P>
407<DT><B>NICKNAME</B>
408
409<DD>
410Specifies the nickname to be used to refer to this server
411and corresponds to the
412<B>-n</B> option (see <I>OPTIONS</I>).
413<P>
414<DT><B>LOG</B>
415
416<DD>
417Specifies the location of the log file to be used by this server and corresponds to the
418<B>--log</B> option (see <I>OPTIONS</I>).
419<P>
420<DT><B>PORT</B>
421
422<DD>
423Specifies the network port to be used by this server and corresponds to the
424<B>--port</B> option (see <I>OPTIONS</I>).
425<P>
426<DT><B>SSL</B>
427
428<DD>
429Specifies the location of the NSS certificate database to be used by this server and corresponds
430to the
431<B>--ssl</B> option (see <I>OPTIONS</I>).
432<P>
433<DT><B>MAXTHREADS</B>
434
435<DD>
436Specifies the maximum number of worker threads to handle concurrent requests to be used by this server
437and corresponds to the <B>--max-threads</B> option (see <I>OPTIONS</I>).
438<P>
439</DL>
440<P>
441
442Here is an example of a server configuration file:
443
444<P>
445
446<BR>
447
448<DL COMPACT><DT><DD>
449<PRE>
450ARCH=
451USER=
452RELEASE=
453NICKNAME=native
454
455</PRE>
456
457</DL>
458
459
460<P>
461
462By keeping the ARCH, USER, and RELEASE fields blank, they will default to the
463current arch and release and use the default user.
464<P>
465A more specific example:
466
467<P>
468
469<BR>
470
471<DL COMPACT><DT><DD>
472<PRE>
473ARCH=i386
474RELEASE=2.6.18-128.el5
475PORT=5001
476LOG=/path/to/log/file
477
478</PRE>
479
480</DL>
481
482
483<P>
484
485<P>
486And here is a more complicated example:
487
488<P>
489
490<BR>
491
492<DL COMPACT><DT><DD>
493<PRE>
494USER=serveruser
495RELEASE=/kernels/2.6.18-92.1.18.el5/build
496INCLUDE=/mytapsets
497INCLUDE+=/yourtapsets
498BUILD='VARIABLE1=VALUE1 VARIABLE2=VALUE2'
499DEFINE=STP_MAXMEMORY=1024
500DEFINE+=DEBUG_TRANS
501RUNTIME=/myruntime
502NICKNAME=my-server
503SSL=/path/to/NSS/certificate/database
504
505</PRE>
506
507</DL>
508
509
510<P>
511
512<P>
513<A NAME="lbAJ">&nbsp;</A>
514<H2>SERVER AUTHENTICAION</H2>
515
516The security of the SSL network connection between the client and server
517depends on the proper
518management of server certificates.
519<P>
520<P>
521
522The trustworthiness of a given systemtap compile server can not be determined
523automatically without a trusted certificate authority issuing systemtap compile server
524certificates. This is
525not practical in everyday use and so, clients must authenticate servers
526against their own database of trusted server certificates. In this context,
527establishing a given server as trusted by a given client means adding
528that server's certificate to the
529client's database of trusted servers.
530<P>
531<P>
532
533For the <I>stap-server</I> initscript, on the local host, this is handled
534automatically.
535When the <I>systemtap-server</I> package is installed, the server's
536certificate for the default user (<I>stap-server</I>) is automatically
537generated and installed. This means that servers started by the
538<I>stap-server</I> initscript,
539with the default user, are automatically trusted by clients on the local
540host, both as an SSL peer and as a systemtap module signer.
541<P>
542
543Furthermore, when stap is invoked by an unprivileged user
544(not root, not a member of the group stapdev, but a member of the group
545stapusr and possibly the group stapsys), the options <I>--use-server</I>
546and <I>--privilege</I>
547are automatically added to the specified options.
548This means that unprivileged users
549on the local host can use a server on the local host
550in unprivileged mode with no further setup or options required. Normal users
551(those in none of the SystemTap groups) can also use compile-servers through the
552<I>--use-server</I> and <I>--privilege</I> options. But they will of course
553be unable to load the module (the <I>-p4</I> option can be used to stop short of
554loading).
555<P>
556<P>
557
558In order to use a server running on another host, that server's certificate
559must be installed on the client's host.
560See the <I>--trust-servers</I> option in the
561<I><A HREF="stap.1.html">stap</A></I>(1)
562
563manual page for more details and README.unprivileged in the systemtap sources
564for more details.
565<P>
566<A NAME="lbAK">&nbsp;</A>
567<H2>EXAMPLES</H2>
568
569See the
570<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap)
571
572manual page for a collection of sample <I>systemtap</I> scripts.
573<P>
574
575To start the configured servers, or the default server, if none are configured:
576<P>
577
578<B> $ [ service ] stap-server start</B>
579
580<P>
581
582To start a server for each kernel installed in /lib/modules:
583<P>
584
585<B> $ [ service ] stap-server start -i</B>
586
587<P>
588
589To obtain information about the running server(s):
590<P>
591
592<B> $ [ service ] stap-server status</B>
593
594<P>
595
596To start a server like another one, except targeting a different architecture,
597by referencing the first server's nickname:
598<P>
599
600<B> $ [ service ] stap-server start -n </B><I>NICKNAME</I><B> -a </B><I>ARCH</I>
601
602<P>
603
604To start a server for a kernel release not installed (cross-compiling)
605<P>
606
607<B> $ [ service ] stap-server start -a </B><I>ARCH</I><B> -r </B><I>/BUILDDIR</I>
608
609<P>
610
611To stop one of the servers by referencing its process id (obtained by running
612<B>stap-server status</B>):
613<P>
614
615<B> $ [ service ] stap-server stop -p </B><I>PID</I>
616
617<P>
618
619To run a script using a compile server:
620<P>
621
622<B> $ stap SCRIPT --use-server</B>
623
624<P>
625
626To run a script as an unprivileged user using a compile server:
627<P>
628
629<B> $ stap SCRIPT</B>
630
631<P>
632
633To stop all running servers:
634<P>
635
636<B> $ [ service ] stap-server stop</B>
637
638<P>
639
640To restart servers after a global configuration change and/or when default
641servers have been added, changed, or removed:
642<P>
643
644<B> $ [ service ] stap-server force-reload</B>
645
646<P>
647<A NAME="lbAL">&nbsp;</A>
648<H2>SAFETY AND SECURITY</H2>
649
650Systemtap is an administrative tool. It exposes kernel internal data
651structures and potentially private user information. See the
652<I><A HREF="stap.1.html">stap</A></I>(1)
653
654manual page for additional information on safety and security.
655<P>
656<P>
657
658As a network server, stap-server should be activated with care in
659order to limit the potential effects of bugs or mischevious users.
660Consider the following prophylactic measures.
661<DL COMPACT>
662<DT>1<DD>
663Run stap-server as an unprivileged user, never as root.
664<P>
665When invoked as a
666service (i.e. <B>service stap-server</B> ...), each server is run,
667by default, as the user <I>stap-server</I>.
668When invoked directly (i.e. <B>stap-server</B> ...), each server is run,
669by default, as the invoking user. In each case, another user may be selected by
670using the <I>-u</I> option on invocation, by specifying
671<I>STAP_USER=</I>username in the global configuration file or by specifying
672<I>USER=</I>username in an individual server configuration file. The invoking
673user must have authority to run processes as another user.
674See <I>CONFIGURATION</I>.
675<P>
676The selected user must have write access to the server log file.
677The location of the server log file may
678be changed by setting <I>LOG_FILE=</I>path in the global configuration file.
679See <I>CONFIGURATION</I>.
680<P>
681The selected user must have
682read/write access to the directory containing the server status files.
683The location of the server
684status files may be changed by setting <I>STAT_PATH=</I>path in the global
685configuration file.
686See <I>CONFIGURATION</I>.
687<P>
688The selected user must have
689read/write access to the uprobes.ko build directory and its files.
690<P>
691Neither form of stap-server will run if the selected user is root.
692<P>
693<DT>2<DD>
694Run stap-server requests with resource limits that impose maximum
695cpu time, file size, memory consumption, in order to bound
696the effects of processing excessively large or bogus inputs.
697<P>
698When the user running the server is <I>stap-server</I>,
699each server request is run with limits specified in <I>~stap-server/.systemtap/rc</I>
700otherwise, no limits are imposed.
701<P>
702<DT>3<DD>
703Run stap-server with a TMPDIR environment variable that
704points to a separate and/or quota-enforced directory, in
705order to prevent filling up of important filesystems.
706<P>
707The default TMPDIR is <I>/tmp/</I>.
708<P>
709<DT>4<DD>
710Activate network firewalls to limit stap client connections
711to relatively trustworthy networks.
712<P>
713For automatic selection of servers by clients, <I>avahi</I> must be installed
714on both the server and client hosts and <I>mDNS</I> messages must be allowed through the firewall.
715<P>
716</DL>
717<P>
718
719The systemtap compile server and its related utilities use the Secure Socket Layer
720(SSL) as implemented by Network Security Services (NSS)
721for network security. NSS is also used
722for the generation and management of certificates. The related
723certificate databases must be protected in order to maintain the security of
724the system.
725Use of the utilities provided will help to ensure that the proper protection
726is maintained. The systemtap client will check for proper
727access permissions before making use of any certificate database.
728<P>
729<A NAME="lbAM">&nbsp;</A>
730<H2>FILES</H2>
731
732<DL COMPACT>
733<DT>Important files and their corresponding paths can be located in the <DD>
734stappaths (7) manual page.
735<P>
736</DL>
737<A NAME="lbAN">&nbsp;</A>
738<H2>SEE ALSO</H2>
739
740
741<PRE>
742<I><A HREF="stap.1.html">stap</A></I>(1),
743<I><A HREF="staprun.8.html">staprun</A></I>(8),
744<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
745<I><A HREF="stappaths.7.html">stappaths</A></I>(7),
746<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap),
747<I>avahi</I>,
748<I><A HREF="ulimit.1.html">ulimit</A></I>(1),
749<I>NSS</I>
750
751</PRE><A NAME="lbAO">&nbsp;</A>
752<H2>BUGS</H2>
753
754Use the Bugzilla link of the project web page or our mailing list.
755
756<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>, <B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
757
758
759<P>
760<P>
761
762<HR>
763<A NAME="index">&nbsp;</A><H2>Index</H2>
764<DL>
765<DT><A HREF="#lbAB">NAME</A><DD>
766<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
767<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
768<DT><A HREF="#lbAE">ARGUMENTS</A><DD>
769<DT><A HREF="#lbAF">OPTIONS</A><DD>
770<DT><A HREF="#lbAG">CONFIGURATION</A><DD>
771<DT><A HREF="#lbAH">Global Configuration</A><DD>
772<DT><A HREF="#lbAI">Individual Server Configuration</A><DD>
773<DT><A HREF="#lbAJ">SERVER AUTHENTICAION</A><DD>
774<DT><A HREF="#lbAK">EXAMPLES</A><DD>
775<DT><A HREF="#lbAL">SAFETY AND SECURITY</A><DD>
776<DT><A HREF="#lbAM">FILES</A><DD>
777<DT><A HREF="#lbAN">SEE ALSO</A><DD>
778<DT><A HREF="#lbAO">BUGS</A><DD>
779</DL>
780<HR>
781This document was created by
782<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
783using the manual pages.<BR>
784Time: 18:00:00 GMT, May 16, 2014
785</BODY>
786</HTML>
diff --git a/man/stap.1.html b/man/stap.1.html
new file mode 100644
index 00000000..4c02d8d8
--- /dev/null
+++ b/man/stap.1.html
@@ -0,0 +1,3138 @@
1
2<HTML><HEAD><TITLE>Manpage of STAP</TITLE>
3</HEAD><BODY>
4<H1>STAP</H1>
5Section: User Commands (1)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stap - systemtap script translator/driver
12<P>
13
14
15
16
17<P>
18<A NAME="lbAC">&nbsp;</A>
19<H2>SYNOPSIS</H2>
20
21<P>
22<BR>
23
24<B>stap</B>
25
26[
27<I>OPTIONS</I>
28
29]
30<I>FILENAME</I>
31
32[
33<I>ARGUMENTS</I>
34
35]
36<BR>
37
38<B>stap</B>
39
40[
41<I>OPTIONS</I>
42
43]
44<B>-</B>
45
46[
47<I>ARGUMENTS</I>
48
49]
50<BR>
51
52<B>stap</B>
53
54[
55<I>OPTIONS</I>
56
57]
58<B>-e</B><I> SCRIPT</I>
59
60[
61<I>ARGUMENTS</I>
62
63]
64<BR>
65
66<B>stap</B>
67
68[
69<I>OPTIONS</I>
70
71]
72<B>-l</B><I> PROBE</I>
73
74[
75<I>ARGUMENTS</I>
76
77]
78<BR>
79
80<B>stap</B>
81
82[
83<I>OPTIONS</I>
84
85]
86<B>-L</B><I> PROBE</I>
87
88[
89<I>ARGUMENTS</I>
90
91]
92<BR>
93
94<B>stap</B>
95
96[
97<I>OPTIONS</I>
98
99]
100<B>--dump-probe-types</B>
101
102<BR>
103
104<B>stap</B>
105
106[
107<I>OPTIONS</I>
108
109]
110<B>--dump-probe-aliases</B>
111
112<BR>
113
114<B>stap</B>
115
116[
117<I>OPTIONS</I>
118
119]
120<B>--dump-functions</B>
121
122<P>
123<A NAME="lbAD">&nbsp;</A>
124<H2>DESCRIPTION</H2>
125
126<P>
127The
128<I>stap</I>
129
130program is the front-end to the Systemtap tool. It accepts probing
131instructions (written in a simple scripting language), translates
132those instructions into C code, compiles this C code, and loads the
133resulting module into a running Linux kernel or a DynInst user-space
134mutator, to perform the requested system trace/probe functions. You
135can supply the script in a named file (FILENAME), from standard input
136(use - instead of FILENAME), or from the command line (using -e
137SCRIPT). The program runs until it is interrupted by the user, or if
138the script voluntarily invokes the
139<I>exit()</I>
140
141function, or by sufficient number of soft errors.
142<P>
143
144The language, which is described in a later section, is strictly typed,
145declaration free, procedural, and inspired by
146<I>awk</I>.
147
148It allows source code points or events in the kernel to be associated
149with handlers, which are subroutines that are executed synchronously. It is
150somewhat similar conceptually to &quot;breakpoint command lists&quot; in the
151<I>gdb</I>
152
153debugger.
154<P>
155<A NAME="lbAE">&nbsp;</A>
156<H2>OPTIONS</H2>
157
158The systemtap translator supports the following options. Any other option
159prints a list of supported options. Options may be given on the command line,
160as usual. If the file $SYSTEMTAP_DIR/rc exist, options are also loaded from
161there and interpreted first. ($SYSTEMTAP_DIR defaults to $HOME/.systemtap if unset.)
162<DL COMPACT>
163<DT><B>-</B>
164
165<DD>
166Use standard input instead of a given FILENAME as probe language input,
167unless -e SCRIPT is given.
168<DT><B>-h --help</B>
169
170<DD>
171Show help message.
172<DT><B>-V --version</B>
173
174<DD>
175Show version message.
176<DT><B>-p</B><I> NUM</I>
177
178<DD>
179Stop after pass NUM. The passes are numbered 1-5: parse, elaborate,
180translate, compile, run. See the
181<B>PROCESSING</B>
182
183section for details.
184<DT><B>-v</B>
185
186<DD>
187Increase verbosity for all passes. Produce a larger volume of
188informative (?) output each time option repeated.
189<DT><B>--vp ABCDE</B>
190
191<DD>
192Increase verbosity on a per-pass basis. For example, &quot;--vp&nbsp;002&quot;
193adds 2 units of verbosity to pass 3 only. The combination &quot;-v&nbsp;--vp&nbsp;00004&quot;
194adds 1 unit of verbosity for all passes, and 4 more for pass 5.
195<DT><B>-k</B>
196
197<DD>
198Keep the temporary directory after all processing. This may be useful
199in order to examine the generated C code, or to reuse the compiled
200kernel object.
201<DT><B>-g</B>
202
203<DD>
204Guru mode. Enable parsing of unsafe expert-level constructs like
205embedded C.
206<DT><B>-P</B>
207
208<DD>
209Prologue-searching mode. Activate heuristics to work around incorrect
210debugging information for $context variables.
211<DT><B>-u</B>
212
213<DD>
214Unoptimized mode. Disable unused code elision during elaboration.
215<DT><B>-w</B>
216
217<DD>
218Suppressed warnings mode. Disables all warning messages.
219<DT><B>-W</B>
220
221<DD>
222Treat all warnings as errors.
223<DT><B>-b</B>
224
225<DD>
226Use bulk mode (percpu files) for kernel-to-user data transfer.
227<DT><B>-t</B>
228
229<DD>
230Collect timing information on the number of times probe executes
231and average amount of time spent in each probe-point. Also shows
232the derivation for each probe-point.
233<DT><B>-s</B><I>NUM</I>
234
235<DD>
236Use NUM megabyte buffers for kernel-to-user data transfer. On a
237multiprocessor in bulk mode, this is a per-processor amount.
238<DT><B>-I</B><I> DIR</I>
239
240<DD>
241Add the given directory to the tapset search directory. See the
242description of pass 2 for details.
243<DT><B>-D</B><I> NAME=VALUE</I>
244
245<DD>
246Add the given C preprocessor directive to the module Makefile. These can
247be used to override limit parameters described below.
248<DT><B>-B</B><I> NAME=VALUE</I>
249
250<DD>
251Add the given make directive to the kernel module build's make invocation.
252These can be used to add or override kconfig options.
253<DT><B>-a</B><I> ARCH</I>
254
255<DD>
256Use a cross-compilation mode for the given target architecture. This requires
257access to the cross-compiler and the kernel build tree, and goes along
258with the
259<B>-B CROSS_COMPILE=arch-tool-prefix-</B> and <B>-r /build/tree</B>
260
261options.
262<DT><B>--modinfo</B><I> NAME=VALUE</I>
263
264<DD>
265Add the name/value pair as a MODULE_INFO macro call to the generated module.
266This may be useful to inform or override various module-related checks in
267the kernel.
268<DT><B>-G</B><I> NAME=VALUE</I>
269
270<DD>
271Sets the value of global variable NAME to VALUE when staprun is invoked.
272This applies to scalar variables declared global in the script/tapset.
273<DT><B>-R</B><I> DIR</I>
274
275<DD>
276Look for the systemtap runtime sources in the given directory.
277<DT><B>-r</B><I> /DIR</I>
278
279<DD>
280Build for kernel in given build tree. Can also be set with the
281<I>SYSTEMTAP_RELEASE</I>
282
283environment variable.
284<DT><B>-r</B><I> RELEASE</I>
285
286<DD>
287Build for kernel in build tree
288<B>/lib/modules/RELEASE/build</B>.
289
290Can also be set with the
291<I>SYSTEMTAP_RELEASE</I>
292
293environment variable.
294<DT><B>-m</B><I> MODULE</I>
295
296<DD>
297Use the given name for the generated kernel object module, instead
298of a unique randomized name. The generated kernel object module is
299copied to the current directory.
300<DT><B>-d</B><I> MODULE</I>
301
302<DD>
303Add symbol/unwind information for the given module into the kernel object
304module. This may enable symbolic tracebacks from those modules/programs,
305even if they do not have an explicit probe placed into them.
306<DT><B>--ldd</B>
307
308<DD>
309Add symbol/unwind information for all shared libraries suspected by
310ldd to be necessary for user-space binaries being probe or listed with
311the -d option. Caution: this can make the probe modules considerably
312larger.
313<DT><B>--all-modules</B>
314
315<DD>
316Equivalent to specifying &quot;-dkernel&quot; and a &quot;-d&quot; for each kernel module that is
317currently loaded. Caution: this can make the probe modules considerably
318larger.
319<DT><B>-o</B><I> FILE</I>
320
321<DD>
322Send standard output to named file. In bulk mode, percpu files will
323start with FILE_ (FILE_cpu with -F) followed by the cpu number.
324This supports <A HREF="strftime.3.html">strftime</A>(3) formats for FILE.
325<DT><B>-c</B><I> CMD</I>
326
327<DD>
328Start the probes, run CMD, and exit when CMD finishes. This also has the
329effect of setting target() to the pid of the command ran.
330<DT><B>-x</B><I> PID</I>
331
332<DD>
333Sets target() to PID. This allows scripts to be written that filter on
334a specific process.
335<DT><B>-e</B><I> SCRIPT</I>
336
337<DD>
338Run the given SCRIPT specified on the command line.
339<DT><B>-l</B><I> PROBE</I>
340
341<DD>
342Instead of running a probe script, just list all available probe
343points matching the given single probe point. The pattern may include
344wildcards and aliases, but not comma-separated multiple probe points.
345The process result code will indicate failure if there are no matches.
346<DT><B>-L</B><I> PROBE</I>
347
348<DD>
349Similar to &quot;-l&quot;, but list probe points and script-level local variables.
350<DT><B>-F</B>
351
352<DD>
353Without -o option, load module and start probes, then detach from the module
354leaving the probes running.
355With -o option, run staprun in background as a daemon and show its pid.
356<DT><B>-S</B><I> size[,N]</I>
357
358<DD>
359Sets the maximum size of output file and the maximum number of output files.
360If the size of output file will exceed
361<B>size</B>
362
363, systemtap switches output file to the next file. And if the number of
364output files exceed
365<B>N</B>
366
367, systemtap removes the oldest output file. You can omit the second argument.
368<DT><B>--skip-badvars</B>
369
370<DD>
371Ignore unresolvable or run-time-inaccessible context variables and
372substitute with 0, without errors.
373<P>
374<DT><B>--suppress-handler-errors</B>
375
376<DD>
377Wrap all probe handlers into something like this
378
379<BR>
380
381<P>
382
383<DL COMPACT><DT><DD>
384<PRE>
385try { ... } catch { next }
386
387</PRE>
388
389</DL>
390
391
392<P>
393
394block, which causes any runtime errors to be quietly suppressed.
395Suppressed errors do not count against
396<B>MAXERRORS</B>
397
398limits. In this mode, the
399<B>MAXSKIPPED</B>
400
401limits are also suppressed, so that many errors and skipped probes
402may be accumulated during a script's runtime. Any overall counts will
403still be reported at shutdown.
404<P>
405<DT><B>--compatible</B><I> VERSION</I>
406
407<DD>
408Suppress recent script language or tapset changes which are incompatible
409with given older version of systemtap. This may be useful if a much older
410systemtap script fails to run. See the DEPRECATION section for more
411details.
412<P>
413<DT><B>--check-version</B>
414
415<DD>
416This option is used to check if the active script has any constructors
417that may be systemtap version specific. See the DEPRECATION section
418for more details.
419<P>
420<DT><B>--clean-cache</B>
421
422<DD>
423This option prunes stale entries from the cache directory. This is normally
424done automatically after successful runs, but this option will trigger the
425cleanup manually and then exit. See the CACHING section for more details about
426cache limits.
427<P>
428<DT><B>--color</B>[=<I>WHEN</I>], <B>--colour</B>[=<I>WHEN</I>]<DD>
429This option controls coloring of error messages. WHEN can be either &quot;never&quot;,
430&quot;always&quot;, or &quot;auto&quot; (i.e. enable only if at a terminal). If WHEN is missing,
431then &quot;always&quot; is assumed. If the option is missing, then &quot;auto&quot; is assumed.
432<P>
433Colors can be modified using the SYSTEMTAP_COLORS environment variable. The
434format must be of the form
435
436<B>key1=val1:key2=val2:key3=val3</B> ...etc.
437
438Valid keys are
439
440&quot;error&quot;, &quot;warning&quot;, &quot;source&quot;, &quot;caret&quot;, and &quot;token&quot;.
441
442Values constitute Select Graphic Rendition (SGR) parameter(s). Consult the
443documentation of your terminal for the SGRs it supports. As an example, the
444default colors would be expressed as
445
446<B>error=01;31:warning=00;33:source=00;34:caret=01:token=01</B>.
447
448If SYSTEMTAP_COLORS is absent, the default colors will be used. If it is empty
449or invalid, coloring is turned off.
450<P>
451<DT><B>--disable-cache</B>
452
453<DD>
454This option disables all use of the cache directory. No files will be either
455read from or written to the cache.
456<P>
457<DT><B>--poison-cache</B>
458
459<DD>
460This option treats files in the cache directory as invalid. No files will be
461read from the cache, but resulting files from this run will still be written to
462the cache. This is meant as a troubleshooting aid when stap's cached behavior
463seems to be misbehaving.
464<P>
465<DT><B>--privilege</B>[=<I>stapusr</I> | =<I>stapsys</I> | =<I>stapdev</I>]<DD>
466This option instructs <I>stap</I> to examine the script looking for constructs
467which are not allowed for the specified privilege level (see <I>UNPRIVILEGED USERS</I>).
468Compilation fails if any such
469constructs are used.
470If <I>stapusr</I> or <I>stapsys</I> are specified when using a compile server
471(see <I>--use-server</I>),
472the server will examine the script and, if compilation succeeds, the
473server will cryptographically sign the resulting kernel module, certifying
474that is it safe for use by users at the specified privilege level.
475<P>
476If <I>--privilege</I> has not been specified,
477<I>-pN</I> has not been specified with N &lt; 5,
478and the invoking user is not
479<I>root</I>, and is not a member of the group <I>stapdev</I>,
480then <I>stap</I> will automatically
481add the appropriate <I>--privilege</I> option to the options already specified.
482<P>
483<DT><B>--unprivileged</B>
484
485<DD>
486This option is equivalent to <I>--privilege=stapusr</I>.
487<P>
488<DT><B>--use-server</B>[=<I>HOSTNAME</I>[<I>:PORT</I>] | =<I>IP_ADDRESS</I>[<I>:PORT</I>] | =<I>CERT_SERIAL</I>]<DD>
489Specify compile-server(s) to be used for compilation and/or in conjunction
490with
491<I>--list-servers</I>
492
493and
494<I>--trust-servers</I>
495
496(see below). If no argument is
497supplied, then the default in unprivileged mode (see
498<I>--privilege</I>)
499
500is to select compatible servers which are trusted as SSL peers and as
501module signers and currently online. Otherwise the default is to select
502compatible servers which are trusted as SSL peers
503and currently online.
504<I>--use-server</I>
505
506may be
507specified more than once, in which case a list of servers is accumulated
508in the order specified. Servers may be specified by host name, ip address, or
509by certificate serial number (obtained using
510<I>--list-servers</I>).
511
512The latter is most commonly used when adding or revoking
513trust in a server (see
514<I>--trust-servers</I>
515
516below). If a server is specified by host name or ip address, then an optional
517port number may be specified. This is useful for accessing servers which are
518not on the local network or to specify a particular server.
519<P>
520IP addresses may be IPv4 or IPv6 addresses.
521<P>
522If a particular IPv6 address is link local and exists
523on more than one interface, the intended interface may be specified by appending the address with
524a percent sign (%) followed by the intended interface name. For example,
525&quot;fe80::5eff:35ff:fe07:55ca%eth0&quot;.
526<P>
527In order to specify a port number with an IPv6 address, it is necessary to enclose the IPv6 address
528in square brackets ([]) in order to separate the port number from the rest of the address. For
529example, &quot;[fe80::5eff:35ff:fe07:55ca]:5000&quot; or &quot;[fe80::5eff:35ff:fe07:55ca%eth0]:5000&quot;.
530<P>
531If <I>--use-server</I> has not been specified,
532<I>-pN</I> has not been specified with N &lt; 5,
533and the invoking user not <I>root</I>,
534is not a member of the group <I>stapdev</I>, but is a member of the group
535<I>stapusr</I>, then <I>stap</I> will automatically
536add <I>--use-server</I> to the options already specified.
537<P>
538<DT><B>--use-server-on-error</B>[=<B>yes</B>|=<B>no</B>]<DD>
539Instructs stap to retry compilation of a script using a compile server if
540compilation on the local host fails in a manner which suggests that it might
541succeed using a server.
542If this option is not specified, the default is <I>no</I>.
543If no argument is provided, then the default
544is <I>yes</I>. Compilation will be retried for certain types of errors
545(e.g. insufficient data or resources) which may not occur during
546re-compilation by a compile
547server. Compile servers will be selected automatically for the
548re-compilation attempt as if <I>--use-server</I> was specified with no
549arguments.
550<P>
551<DT><B>--list-servers</B><I>[=SERVERS]</I>
552
553<DD>
554Display the status of the requested
555<I>SERVERS</I>,
556
557where
558<I>SERVERS</I>
559
560is a comma-separated
561list of server attributes. The list of attributes is combined to filter the
562list of servers displayed. Supported attributes are:
563<DL COMPACT><DT><DD>
564<DL COMPACT>
565<DT><B>all</B>
566
567<DD>
568specifies all known servers (trusted SSL peers, trusted module signers, online
569servers).
570<DT><B>specified</B>
571
572<DD>
573specifies servers specified using
574<I>--use-server</I>.
575
576<DT><B>online</B>
577
578<DD>
579filters the output by retaining information about servers which are currently
580online.
581<DT><B>trusted</B>
582
583<DD>
584filters the output by retaining information about servers which are trusted as
585SSL peers.
586<DT><B>signer</B>
587
588<DD>
589filters the output by retaining information about servers which are trusted as
590module signers (see
591<I>--privilege</I>).
592
593<DT><B>compatible</B>
594
595<DD>
596filters the output by retaining information about servers which are compatible
597with the current kernel release and architecture.
598</DL>
599</DL>
600
601<DT><DD>
602If no argument is provided, then the default is
603<B>specified</B>.
604
605If no servers were specified using
606<I>--use-server</I>,
607
608then the default servers for
609<I>--use-server</I>
610
611are listed.
612<P>
613Note that
614<I>--list-servers</I>
615
616uses the
617<I>avahi-daemon</I>
618
619service to detect online servers. If this service is not available, then
620<I>--list-servers</I>
621
622will fail to detect any
623<I>online</I>
624
625servers. In order for
626<I>--list-servers</I>
627
628to detect servers listening on IPv6 addresses, the
629<I>avahi-daemon</I>
630
631configuration file
632<I>/etc/avahi/avahi-daemon.conf</I>
633
634must contain an active &quot;use-ipv6=yes&quot; line. The service must be restarted after adding this line
635in order for IPv6 to be enabled.
636<P>
637<DT><B>--trust-servers</B><I>[=TRUST_SPEC]</I>
638
639<DD>
640Grant or revoke trust in compile-servers, specified using
641<I>--use-server</I>
642
643as specified by TRUST_SPEC,
644where TRUST_SPEC is a comma-separated list specifying the trust which is to
645be granted or revoked. Supported elements are:
646<DL COMPACT><DT><DD>
647<DL COMPACT>
648<DT><B>ssl</B>
649
650<DD>
651trust the specified servers as SSL peers.
652<DT><B>signer</B>
653
654<DD>
655trust the specified servers as module signers (see
656<I>--privilege</I>).
657
658Only root can specify
659<B>signer.</B>
660
661<DT><B>all-users</B>
662
663<DD>
664grant trust as an ssl peer for all users on the local host. The default is
665to grant trust as an ssl peer for the current user only. Trust as a module
666signer is always granted for all users. Only root can specify
667<B>all-users</B>.
668
669<DT><B>revoke</B>
670
671<DD>
672revoke the specified trust. The default is to grant it.
673<DT><B>no-prompt</B>
674
675<DD>
676do not prompt the user for confirmation before carrying out the requested
677action. The default is to prompt the user for confirmation.
678</DL>
679</DL>
680
681<DT><DD>
682If no argument is provided, then the default is
683<B>ssl</B>.
684
685If no servers were specified using
686<I>--use-server</I>,
687
688then no trust will be granted or revoked.
689<DT><DD>
690Unless <B>no-prompt</B> has been specified,
691the user will be prompted to confirm the trust to be granted or revoked before
692the operation is performed.
693<P>
694<DT><B>--dump-probe-types</B>
695
696<DD>
697Dumps a list of supported probe types and exits. If
698<I>--privilege=stapusr</I>
699
700is also specified, the list will be limited to probe types available to unprivileged users.
701<P>
702<DT><B>--dump-probe-aliases</B>
703
704<DD>
705Dumps a list of all probe aliases found in library files and exits.
706<P>
707<DT><B>--dump-functions</B>
708
709<DD>
710Dumps a list of all functions found in library files and exits. Also includes
711their parameters and types. A function of type 'unknown' indicates a function
712that does not return a value. Note that not all function/parameter types may be
713resolved (these are also shown by 'unknown'). This features is very
714memory-intensive and thus may not work properly with <I>--use-server</I> if the
715target server imposes an rlimit on process memory (i.e. through the
716<I>~stap-server/.systemtap/rc</I> configuration file, see <I><A HREF="stap-server.8.html">stap-server</A></I>(8)).
717<P>
718<DT><B>--remote</B><I> URL</I>
719
720<DD>
721Set the execution target to the given host. This option may be
722repeated to target multiple execution targets. Passes 1-4 are
723completed locally as normal to build the script, and then pass 5 will
724copy the module to the target and run it. Acceptable URL forms include:
725<DL COMPACT><DT><DD>
726<DL COMPACT>
727<DT><B>[USER@]HOSTNAME</B>, <B><A HREF="ssh://[USER@]HOSTNAME">ssh://[USER@]HOSTNAME</A></B><DD>
728This mode uses ssh, optionally using a username not matching your own. If a
729custom ssh_config file is in use, add <B>SendEnv LANG</B> to retain
730internationalization functionality.
731<DT><B>libvirt://DOMAIN</B>, <B>libvirt://DOMAIN/LIBVIRT_URI</B><DD>
732This mode uses <I>stapvirt</I> to execute the script on a domain managed by
733libvirt. Optionally, LIBVIRT_URI may be specified to connect to a specific
734driver and/or a remote host. For example, to connect to the local privileged
735QEMU driver, use:
736
737<BR>
738
739<P>
740
741<DL COMPACT><DT><DD>
742<PRE>
743--remote libvirt://MyDomain/<A HREF="qemu:///system">qemu:///system</A>
744
745</PRE>
746
747</DL>
748
749
750<P>
751
752See the page at
753
754&lt;<A HREF="http://libvirt.org/uri.html">http://libvirt.org/uri.html</A>&gt;
755
756for supported URIs. Also see <I><A HREF="stapvirt.1.html">stapvirt</A></I>(1) for more information on how to
757prepare the domain for stap probing.
758<DT><B>unix:PATH</B><DD>
759This mode connects to a UNIX socket. This can be used with a QEMU virtio-serial
760port for executing scripts inside a running virtual machine.
761<DT><B>direct://</B><DD>
762Special loopback mode to run on the local host.
763</DL>
764</DL>
765
766<DT><DD>
767<P>
768<DT><B>--remote-prefix</B>
769
770<DD>
771Prefix each line of remote output with &quot;N: &quot;, where N is the index of the remote
772execution target from which the given line originated.
773<P>
774<DT><B>--download-debuginfo</B><I>[=OPTION]</I>
775
776<DD>
777Enable, disable or set a timeout for the automatic debuginfo downloading feature
778offered by abrt as specified by OPTION, where OPTION is one of the following:
779<DL COMPACT><DT><DD>
780<DL COMPACT>
781<DT><B>yes</B>
782
783<DD>
784enable automatic downloading of debuginfo with no timeout. This is the same
785as not providing an OPTION value to
786<I>--download-debuginfo</I>
787
788<DT><B>no</B>
789
790<DD>
791explicitly disable automatic downloading of debuginfo. This is the same as
792not using the option at all.
793<DT><B>ask</B>
794
795<DD>
796show abrt output, and ask before continuing download. No timeout will be set.
797<DT><B>&lt;timeout&gt;</B>
798
799<DD>
800specify a timeout as a positive number to stop the download if it is taking
801too long.
802</DL>
803</DL>
804
805<DT><DD>
806<P>
807<DT><B>--rlimit-as</B><I>=NUM</I>
808
809<DD>
810Specify the maximum size of the process's virtual memory (address space),
811in bytes. If nothing is specified, no limits are imposed.
812<P>
813<DT><B>--rlimit-cpu</B><I>=NUM</I>
814
815<DD>
816Specify the CPU time limit, in seconds. If nothing is specified, no limits are
817imposed.
818<P>
819<DT><B>--rlimit-nproc</B><I>=NUM</I>
820
821<DD>
822Specify the maximum number of processes that can be created. If nothing is
823specified, no limits are imposed.
824<P>
825<DT><B>--rlimit-stack</B><I>=NUM</I>
826
827<DD>
828Specify the maximum size of the process stack, in bytes. If nothing is specified,
829no limits are imposed.
830<P>
831<DT><B>--rlimit-fsize</B><I>=NUM</I>
832
833<DD>
834Specify the maximum size of files that the process may create, in bytes. If nothing is specified, no limits are
835imposed.
836<P>
837<DT><B>--sysroot</B><I>=DIR</I>
838
839<DD>
840Specify sysroot directory where target files (executables, libraries, etc.)
841are located. With <I>-r RELEASE</I>, the sysroot will be searched for the
842appropriate kernel build directory. With <I>-r /DIR</I>, however, the sysroot
843will not be used to find the kernel build.
844<P>
845<DT><B>--sysenv</B><I>=VAR=VALUE</I>
846
847<DD>
848Provide an alternate value for an environment variable where the value on a
849remote system differs. Path variables (e.g. PATH, LD_LIBRARY_PATH) are assumed
850to be relative to the directory provided by <I>--sysroot</I>, if provided.
851<P>
852<DT><B>--suppress-time-limits</B>
853
854<DD>
855Disable -DSTP_OVERLOAD related options as well as -DMAXACTION and -DMAXTRYLOCK.
856This option requires guru mode.
857<P>
858<DT><B>--runtime</B><I>=MODE</I>
859
860<DD>
861Set the pass-5 runtime mode. Valid options are <I>kernel</I> (default)
862and <I>dyninst</I>. See
863<B>ALTERNATE&nbsp;RUNTIMES</B>
864
865below for more information.
866<P>
867<DT><B>--dyninst</B>
868
869<DD>
870Shorthand for <I>--runtime=dyninst</I>.
871<P>
872</DL>
873<A NAME="lbAF">&nbsp;</A>
874<H2>ARGUMENTS</H2>
875
876<P>
877Any additional arguments on the command line are passed to the script
878parser for substitution. See below.
879<P>
880<A NAME="lbAG">&nbsp;</A>
881<H2>SCRIPT LANGUAGE</H2>
882
883<P>
884The systemtap script language resembles
885<I>awk</I>.
886
887There are two main outermost constructs: probes and functions. Within
888these, statements and expressions use C-like operator syntax and
889precedence.
890<P>
891<A NAME="lbAH">&nbsp;</A>
892<H3>GENERAL SYNTAX</H3>
893
894Whitespace is ignored. Three forms of comments are supported:
895<DL COMPACT><DT><DD>
896<BR>
897
898<B>#</B> ... shell style, to the end of line, except for $# and @#
899
900<BR>
901
902<B>//</B> ... C++ style, to the end of line
903
904<BR>
905
906<B>/*</B> ... C style ... <B>*/</B>
907
908</DL>
909
910Literals are either strings enclosed in double-quotes (passing through
911the usual C escape codes with backslashes, and with adjacent string
912literals glued together, also as in C), or integers (in decimal,
913hexadecimal, or octal, using the same notation as in C). All strings
914are limited in length to some reasonable value (a few hundred bytes).
915Integers are 64-bit signed quantities, although the parser also
916accepts (and wraps around) values above positive 2**63.
917<P>
918
919In addition, script arguments given at the end of the command line may
920be inserted. Use
921<B>$1 ... $&lt;NN&gt;</B>
922
923for insertion unquoted,
924<B>@1 ... @&lt;NN&gt;</B>
925
926for insertion as a string literal. The number of arguments may be accessed
927through
928<B>$#</B>
929
930(as an unquoted number) or through
931<B>@#</B>
932
933(as a quoted number). These may be used at any place a token may begin,
934including within the preprocessing stage. Reference to an argument
935number beyond what was actually given is an error.
936<P>
937<A NAME="lbAI">&nbsp;</A>
938<H3>PREPROCESSING</H3>
939
940A simple conditional preprocessing stage is run as a part of parsing.
941The general form is similar to the
942cond<B> ? </B>exp1<B> : </B>exp2
943
944ternary operator:
945
946<BR>
947
948<P>
949
950<DL COMPACT><DT><DD>
951<PRE>
952<B>%(</B> CONDITION <B>%?</B> TRUE-TOKENS <B>%)</B>
953<B>%(</B> CONDITION <B>%?</B> TRUE-TOKENS <B>%:</B> FALSE-TOKENS <B>%)</B>
954
955</PRE>
956
957</DL>
958
959
960<P>
961
962The CONDITION is either an expression whose format is determined by its
963first keyword, or a string literals comparison or a numeric literals
964comparison. It can be also composed of many alternatives and conjunctions
965of CONDITIONs (meant as in previous sentence) using || and &amp;&amp; respectively.
966However, parentheses are not supported yet, so remembering that conjunction
967takes precedence over alternative is important.
968<P>
969
970If the first part is the identifier
971<B>kernel_vr</B> or <B>kernel_v</B>
972
973to refer to the kernel version number, with (&quot;2.6.13-1.322FC3smp&quot;) or
974without (&quot;2.6.13&quot;) the release code suffix, then
975the second part is one of the six standard numeric comparison operators
976<B>&lt;</B>, <B>&lt;=</B>, <B>==</B>, <B>!=</B>, <B>&gt;</B>, and <B>&gt;=</B>,
977
978and the third part is a string literal that contains an RPM-style
979version-release value. The condition is deemed satisfied if the
980version of the target kernel (as optionally overridden by the
981<B>-r</B>
982
983option) compares to the given version string. The comparison is
984performed by the glibc function
985<B>strverscmp</B>.
986
987As a special case, if the operator is for simple equality
988(<B>==</B>),
989
990or inequality
991(<B>!=</B>),
992
993and the third part contains any wildcard characters
994(<B>*</B> or <B>?</B> or <B>[</B>),
995
996then the expression is treated as a wildcard (mis)match as evaluated
997by
998<B>fnmatch</B>.
999
1000<P>
1001
1002If, on the other hand, the first part is the identifier
1003<B>arch</B>
1004
1005to refer to the processor architecture (as named by the kernel
1006build system ARCH/SUBARCH), then the second
1007part is one of the two string comparison operators
1008<B>==</B> or <B>!=</B>,
1009
1010and the third part is a string literal for matching it. This
1011comparison is a wildcard (mis)match.
1012<P>
1013
1014Similarly, if the first part is an identifier like
1015<B>CONFIG_something</B>
1016
1017to refer to a kernel configuration option, then the second part is
1018<B>==</B> or <B>!=</B>,
1019
1020and the third part is a string literal for matching the value
1021(commonly &quot;y&quot; or &quot;m&quot;). Nonexistent or unset kernel configuration
1022options are represented by the empty string. This comparison is also
1023a wildcard (mis)match.
1024<P>
1025
1026If the first part is the identifier
1027<B>systemtap_v</B>,
1028
1029the test refers to the systemtap compatibility version, which may be
1030overridden for old scripts with the
1031<B>--compatible</B>
1032
1033flag. The comparison operator is as is for
1034<B>kernel_v</B>
1035
1036and the right operand is a version string. See also the DEPRECATION
1037section below.
1038<P>
1039
1040If the first part is the identifier
1041<B>systemtap_privilege</B>,
1042
1043the test refers to the privilege level that the systemtap script is
1044compiled with. Here the second part is
1045<B>==</B> or <B>!=</B>,
1046
1047and the third part is a string literal, either &quot;stapusr&quot; or &quot;stapsys&quot;
1048or &quot;stapdev&quot;.
1049<P>
1050
1051If the first part is the identifier
1052<B>guru_mode</B>,
1053
1054the test refers to if the systemtap script is
1055compiled with guru_mode. Here the second part is
1056<B>==</B> or <B>!=</B>,
1057
1058and the third part is a number, either 1 or 0.
1059<P>
1060
1061If the first part is the identifier
1062<B>runtime</B>,
1063
1064the test refers to the systemtap runtime mode. See
1065<B>ALTERNATE&nbsp;RUNTIMES</B>
1066
1067below for more information on runtimes.
1068The second
1069part is one of the two string comparison operators
1070<B>==</B> or <B>!=</B>,
1071
1072and the third part is a string literal for matching it. This
1073comparison is a wildcard (mis)match.
1074<P>
1075
1076Otherwise, the CONDITION is expected to be a comparison between two string
1077literals or two numeric literals. In this case, the arguments are the only
1078variables usable.
1079<P>
1080
1081The TRUE-TOKENS and FALSE-TOKENS are zero or more general parser
1082tokens (possibly including nested preprocessor conditionals), and are
1083passed into the input stream if the condition is true or false. For
1084example, the following code induces a parse error unless the target
1085kernel version is newer than 2.6.5:
1086
1087<BR>
1088
1089<P>
1090
1091<DL COMPACT><DT><DD>
1092<PRE>
1093%( kernel_v &lt;= &quot;2.6.5&quot; %? **ERROR** %) # invalid token sequence
1094
1095</PRE>
1096
1097</DL>
1098
1099
1100<P>
1101
1102The following code might adapt to hypothetical kernel version drift:
1103
1104<BR>
1105
1106<P>
1107
1108<DL COMPACT><DT><DD>
1109<PRE>
1110probe kernel.function (
1111 %( kernel_v &lt;= &quot;2.6.12&quot; %? &quot;__mm_do_fault&quot; %:
1112 %( kernel_vr == &quot;2.6.13*smp&quot; %? &quot;do_page_fault&quot; %:
1113 UNSUPPORTED %) %)
1114) { /* ... */ }
1115
1116%( arch == &quot;ia64&quot; %?
1117 probe syscall.vliw = kernel.function(&quot;vliw_widget&quot;) {}
1118%)
1119
1120</PRE>
1121
1122</DL>
1123
1124
1125<P>
1126
1127<P>
1128<A NAME="lbAJ">&nbsp;</A>
1129<H3>PREPROCESSOR MACROS</H3>
1130
1131The preprocessor also supports a simple macro facility, run as a
1132separate pass before conditional preprocessing.
1133<P>
1134
1135Macros are defined using the following construct:
1136
1137<BR>
1138
1139<P>
1140
1141<DL COMPACT><DT><DD>
1142<PRE>
1143@define NAME %( BODY %)
1144@define NAME(PARAM_1, PARAM_2, ...) %( BODY %)
1145
1146</PRE>
1147
1148</DL>
1149
1150
1151<P>
1152
1153Macros, and parameters inside a macro body, are both invoked by
1154prefixing the macro name with an @ symbol:
1155
1156<BR>
1157
1158<P>
1159
1160<DL COMPACT><DT><DD>
1161<PRE>
1162@define foo %( x %)
1163@define add(a,b) %( ((@a)+(@b)) %)
1164
1165 @foo = @add(2,2)
1166
1167</PRE>
1168
1169</DL>
1170
1171
1172<P>
1173
1174<P>
1175
1176Macro expansion is currently performed in a separate pass before
1177conditional compilation. Therefore, both TRUE- and FALSE-tokens in
1178conditional expressions will be macroexpanded regardless of how the
1179condition is evaluated. This can sometimes lead to errors:
1180
1181<BR>
1182
1183<P>
1184
1185<DL COMPACT><DT><DD>
1186<PRE>
1187// The following results in a conflict:
1188%( CONFIG_UTRACE == &quot;y&quot; %?
1189 @define foo %( process.syscall %)
1190%:
1191 @define foo %( **ERROR** %)
1192%)
1193
1194// The following works properly as expected:
1195@define foo %(
1196 %( CONFIG_UTRACE == &quot;y&quot; %? process.syscall %: **ERROR** %)
1197%)
1198
1199</PRE>
1200
1201</DL>
1202
1203
1204<P>
1205
1206The first example is incorrect because both @defines are evaluated in
1207a pass prior to the conditional being evaluated.
1208<P>
1209Normally, a macro definition is local to the file it occurs in. Thus,
1210defining a macro in a tapset does not make it available to the user of
1211the tapset. Publically available library macros can be defined by
1212including .stpm files on the tapset search path. These files may only
1213contain @define constructs, which become visible across all tapsets
1214and user scripts.
1215<P>
1216<A NAME="lbAK">&nbsp;</A>
1217<H3>VARIABLES</H3>
1218
1219Identifiers for variables and functions are an alphanumeric sequence,
1220and may include &quot;_&quot; and &quot;$&quot; characters. They may not start with a
1221plain digit, as in C. Each variable is by default local to the probe
1222or function statement block within which it is mentioned, and therefore
1223its scope and lifetime is limited to a particular probe or function
1224invocation.
1225
1226<P>
1227
1228Scalar variables are implicitly typed as either string or integer.
1229Associative arrays also have a string or integer value, and a
1230tuple of strings and/or integers serving as a key. Here are a
1231few basic expressions.
1232
1233<BR>
1234
1235<P>
1236
1237<DL COMPACT><DT><DD>
1238<PRE>
1239var1 = 5
1240var2 = &quot;bar&quot;
1241array1 [pid()] = &quot;name&quot; # single numeric key
1242array2 [&quot;foo&quot;,4,i++] += 5 # vector of string/num/num keys
1243if ([&quot;hello&quot;,5,4] in array2) println (&quot;yes&quot;) # membership test
1244
1245</PRE>
1246
1247</DL>
1248
1249
1250<P>
1251
1252<P>
1253
1254The translator performs
1255<I>type inference</I>
1256
1257on all identifiers, including array indexes and function parameters.
1258Inconsistent type-related use of identifiers signals an error.
1259<P>
1260
1261Variables may be declared global, so that they are shared amongst all
1262probes and live as long as the entire systemtap session. There is one
1263namespace for all global variables, regardless of which script file
1264they are found within. Concurrent access to global variables is
1265automatically protected with locks, see the
1266<B>SAFETY AND SECURITY</B>
1267
1268section for more details. A global declaration may be written at the
1269outermost level anywhere, not within a block of code. Global
1270variables which are written but never read will be displayed
1271automatically at session shutdown. The translator will
1272infer for each its value type, and if it is used as an array, its key
1273types. Optionally, scalar globals may be initialized with a string
1274or number literal. The following declaration marks variables as global.
1275
1276<BR>
1277
1278<P>
1279
1280<DL COMPACT><DT><DD>
1281<PRE>
1282<B>global</B> var1<B>,</B> var2<B>,</B> var3=4
1283
1284</PRE>
1285
1286</DL>
1287
1288
1289<P>
1290
1291<P>
1292
1293Global variables can also be set as module options. One can do this by either
1294using the -G option, or the module must first be compiled using stap -p4.
1295Global variables can then be set on the command line when calling staprun on
1296the module generated by stap -p4. See
1297<I><A HREF="staprun.8.html">staprun</A></I>(8)
1298
1299for more information.
1300<P>
1301
1302Arrays are limited in size by the MAXMAPENTRIES variable -- see the
1303<B>SAFETY AND SECURITY</B>
1304
1305section for details. Optionally, global arrays may be declared with a
1306maximum size in brackets, overriding MAXMAPENTRIES for that array only.
1307Note that this doesn't indicate the type of keys for the array, just the
1308size.
1309
1310<BR>
1311
1312<P>
1313
1314<DL COMPACT><DT><DD>
1315<PRE>
1316<B>global</B> tiny_array[10]<B>,</B> normal_array<B>,</B> big_array[50000]
1317
1318</PRE>
1319
1320</DL>
1321
1322
1323<P>
1324
1325<P>
1326
1327Arrays may be configured for wrapping using the '%' suffix. This
1328causes older elements to be overwritten if more elements are inserted
1329than the array can hold. This works for both associative and statistics
1330typed arrays.
1331
1332<BR>
1333
1334<P>
1335
1336<DL COMPACT><DT><DD>
1337<PRE>
1338<B>global</B> wrapped_array1%[10],<B> wrapped_array2%</B>
1339
1340</PRE>
1341
1342</DL>
1343
1344
1345<P>
1346
1347<P>
1348<A NAME="lbAL">&nbsp;</A>
1349<H3>STATEMENTS</H3>
1350
1351Statements enable procedural control flow. They may occur within
1352functions and probe handlers. The total number of statements executed
1353in response to any single probe event is limited to some number
1354defined by a macro in the translated C code, and is in the
1355neighbourhood of 1000.
1356<DL COMPACT>
1357<DT>EXP<DD>
1358Execute the string- or integer-valued expression and throw away
1359the value.
1360<DT><B>{</B> STMT1 STMT2 ... <B>}</B>
1361
1362<DD>
1363Execute each statement in sequence in this block. Note that
1364separators or terminators are generally not necessary between statements.
1365<DT><B>;</B>
1366
1367<DD>
1368Null statement, do nothing. It is useful as an optional separator between
1369statements to improve syntax-error detection and to handle certain
1370grammar ambiguities.
1371<DT><B>if</B> (EXP) STMT1 [ <B>else</B> STMT2 ]
1372
1373<DD>
1374Compare integer-valued EXP to zero. Execute the first (non-zero)
1375or second STMT (zero).
1376<DT><B>while</B> (EXP) STMT
1377
1378<DD>
1379While integer-valued EXP evaluates to non-zero, execute STMT.
1380<DT><B>for</B> (EXP1; EXP2; EXP3) STMT
1381
1382<DD>
1383Execute EXP1 as initialization. While EXP2 is non-zero, execute
1384STMT, then the iteration expression EXP3.
1385<DT><B>foreach</B> (VAR <B>in</B> ARRAY [ limit<B> EXP ]) STMT</B>
1386
1387<DD>
1388Loop over each element of the named global array, assigning current
1389key to VAR. The array may not be modified within the statement.
1390By adding a single
1391<B>+</B> or <B>-</B>
1392
1393operator after the VAR or the ARRAY identifier, the iteration will
1394proceed in a sorted order, by ascending or descending index or value.
1395If the array contains statistics aggregates, adding the desired
1396<B>@operator</B>
1397
1398between the ARRAY identifier and the
1399<B>+</B> or <B>-</B>
1400
1401will specify the sorting aggregate function. See the STATISTICS
1402section below for the ones available. Default is
1403<B>@count</B>.
1404
1405Using the optional
1406<B>limit</B>
1407
1408keyword limits the number of loop iterations to EXP times. EXP is
1409evaluated once at the beginning of the loop.
1410<DT><B>foreach</B> ([VAR1, VAR2, ...] <B>in</B> ARRAY [ limit<B> EXP ]) STMT</B>
1411
1412<DD>
1413Same as above, used when the array is indexed with a tuple of keys.
1414A sorting suffix may be used on at most one VAR or ARRAY identifier.
1415<DT><B>foreach</B> (VALUE = VAR <B>in</B> ARRAY [ limit<B> EXP ]) STMT</B>
1416
1417<DD>
1418This variant of foreach saves current value into VALUE on each
1419iteration, so it is the same as ARRAY[VAR]. This also works with a
1420tuple of keys. Sorting suffixes on VALUE have the same effect as on ARRAY.
1421<DT><B>break</B>, <B>continue</B>
1422
1423<DD>
1424Exit or iterate the innermost nesting loop
1425(<B>while</B> or <B>for</B> or <B>foreach</B>)
1426
1427statement.
1428<DT><B>return</B> EXP
1429
1430<DD>
1431Return EXP value from enclosing function. If the function's value is
1432not taken anywhere, then a return statement is not needed, and the
1433function will have a special &quot;unknown&quot; type with no return value.
1434<DT><B>next</B>
1435
1436<DD>
1437Return now from enclosing probe handler. This is especially useful in
1438probe aliases that apply event filtering predicates.
1439<DT><B>try</B> { STMT1 } <B>catch</B> { STMT2 }
1440
1441<DD>
1442Run the statements in the first block. Upon any run-time errors, abort
1443STMT1 and start executing STMT2. Any errors in STMT2 will propagate to
1444outer try/catch blocks, if any.
1445<DT><B>try</B> { STMT1 } <B>catch</B>(VAR) { STMT2 }
1446
1447<DD>
1448Same as above, plus assign the error message to the string scalar variable VAR.
1449<DT><B>delete</B> ARRAY[INDEX1, INDEX2, ...]
1450
1451<DD>
1452Remove from ARRAY the element specified by the index tuple. The value will no
1453longer be available, and subsequent iterations will not report the element.
1454It is not an error to delete an element that does not exist.
1455<DT><B>delete</B> ARRAY
1456
1457<DD>
1458Remove all elements from ARRAY.
1459<DT><B>delete</B> SCALAR
1460
1461<DD>
1462Removes the value of SCALAR. Integers and strings are cleared to 0 and &quot;&quot;
1463respectively, while statistics are reset to the initial empty state.
1464<P>
1465</DL>
1466<A NAME="lbAM">&nbsp;</A>
1467<H3>EXPRESSIONS</H3>
1468
1469Systemtap supports a number of operators that have the same general syntax,
1470semantics, and precedence as in C and awk. Arithmetic is performed as per
1471typical C rules for signed integers. Division by zero or overflow is
1472detected and results in an error.
1473<DL COMPACT>
1474<DT>binary numeric operators<DD>
1475<B>* / % + - &gt;&gt; &lt;&lt; &amp; ^ | &amp;&amp; ||</B>
1476
1477<DT>binary string operators<DD>
1478<B>.</B>
1479
1480(string concatenation)
1481<DT>numeric assignment operators<DD>
1482<B>= *= /= %= += -= &gt;&gt;= &lt;&lt;= &amp;= ^= |=</B>
1483
1484<DT>string assignment operators<DD>
1485<B>= .=</B>
1486
1487<DT>unary numeric operators<DD>
1488<B>+ - ! ~ ++ --</B>
1489
1490<DT>binary numeric, string comparison or regex matching operators<DD>
1491<B>&lt; &gt; &lt;= &gt;= == != =~ !~</B>
1492
1493<DT>ternary operator<DD>
1494cond<B> ? </B>exp1<B> : </B>exp2
1495
1496<DT>grouping operator<DD>
1497<B>(</B> exp <B>)</B>
1498
1499<DT>function call<DD>
1500fn <B>(</B>[ arg1, arg2, ... ]<B>)</B>
1501
1502<DT>array membership check<DD>
1503exp<B> in </B>array
1504
1505<BR>
1506
1507<B>[</B>exp1<B>, </B>exp2<B>, </B>...<B>] in </B>array
1508
1509<P>
1510</DL>
1511<A NAME="lbAN">&nbsp;</A>
1512<H3>REGULAR EXPRESSION MATCHING</H3>
1513
1514The scripting language supports regular expression matching.
1515The basic syntax is as follows:
1516
1517<BR>
1518
1519<P>
1520
1521<DL COMPACT><DT><DD>
1522<PRE>
1523<B>exp</B> =~ <B>regex</B>
1524<B>exp</B> !~ <B>regex</B>
1525
1526</PRE>
1527
1528</DL>
1529
1530
1531<P>
1532
1533(The first operand must be an expression evaluating to a string; the
1534second operand must be a string literal containing a syntactically
1535valid regular expression.)
1536<P>
1537
1538The regular expression syntax supports most of the features of POSIX
1539Extended Regular Expressions, except for subexpression reuse (&quot;\1&quot;)
1540functionality. The ability to capture and extract the contents of the
1541matched string and subexpressions has not yet been implemented.
1542<P>
1543<A NAME="lbAO">&nbsp;</A>
1544<H3>PROBES</H3>
1545
1546The main construct in the scripting language identifies probes.
1547Probes associate abstract events with a statement block (&quot;probe
1548handler&quot;) that is to be executed when any of those events occur. The
1549general syntax is as follows:
1550
1551<BR>
1552
1553<P>
1554
1555<DL COMPACT><DT><DD>
1556<PRE>
1557<B>probe</B> PROBEPOINT [<B>,</B> PROBEPOINT] <B>{</B> [STMT ...] <B>}</B>
1558
1559</PRE>
1560
1561</DL>
1562
1563
1564<P>
1565
1566<P>
1567
1568Events are specified in a special syntax called &quot;probe points&quot;. There
1569are several varieties of probe points defined by the translator, and
1570tapset scripts may define further ones using aliases. Probe points
1571may be wildcarded, grouped, or listed in preference sequences, or
1572declared optional. More details on probe point syntax and semantics
1573are listed on the
1574<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap)
1575
1576manual page.
1577<P>
1578
1579The probe handler is interpreted relative to the context of each
1580event. For events associated with kernel code, this context may
1581include
1582<I>variables</I>
1583
1584defined in the
1585<I>source code</I>
1586
1587at that spot. These &quot;context variables&quot; are presented to the script
1588as variables whose names are prefixed with &quot;$&quot;. They may be accessed
1589only if the kernel's compiler preserved them despite optimization.
1590This is the same constraint that a debugger user faces when working
1591with optimized code. In addition, the objects must exist in paged-in
1592memory at the moment of the systemtap probe handler's execution,
1593because systemtap must not cause (suppresses) any additional paging.
1594Some probe types have very little context.
1595See the
1596<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap)
1597
1598man pages to see the kinds of context variables available at each kind
1599of probe point.
1600<P>
1601
1602New probe points may be defined using &quot;aliases&quot;. Probe point aliases
1603look similar to probe definitions, but instead of activating a probe
1604at the given point, it just defines a new probe point name as an alias
1605to an existing one. There are two types of alias, i.e. the prologue
1606style and the epilogue style which are identified by &quot;=&quot; and &quot;+=&quot;
1607respectively.
1608<P>
1609
1610For prologue style alias, the statement block that follows an alias
1611definition is implicitly added as a prologue to any probe that refers
1612to the alias. While for the epilogue style alias, the statement block
1613that follows an alias definition is implicitly added as an epilogue to
1614any probe that refers to the alias. For example:
1615
1616<BR>
1617
1618<P>
1619
1620<DL COMPACT><DT><DD>
1621<PRE>
1622probe syscall.read = kernel.function(&quot;sys_read&quot;) {
1623 fildes = $fd
1624 if (execname() == &quot;init&quot;) next # skip rest of probe
1625}
1626
1627</PRE>
1628
1629</DL>
1630
1631
1632<P>
1633
1634defines a new probe point
1635
1636<I>syscall.read</I>,
1637
1638
1639which expands to
1640
1641<I>kernel.function(sys_read)</I>,
1642
1643
1644with the given statement as a prologue, which is useful to predefine
1645some variables for the alias user and/or to skip probe processing
1646entirely based on some conditions. And
1647
1648<BR>
1649
1650<P>
1651
1652<DL COMPACT><DT><DD>
1653<PRE>
1654probe syscall.read += kernel.function(&quot;sys_read&quot;) {
1655 if (tracethis) println ($fd)
1656}
1657
1658</PRE>
1659
1660</DL>
1661
1662
1663<P>
1664
1665defines a new probe point with the given statement as an epilogue, which
1666is useful to take actions based upon variables set or left over by the
1667the alias user. Please note that in each case, the statements in the
1668alias handler block are treated ordinarily, so that variables assigned
1669there constitute mere initialization, not a macro substitution.
1670<P>
1671An alias is used just like a built-in probe type.
1672
1673<BR>
1674
1675<P>
1676
1677<DL COMPACT><DT><DD>
1678<PRE>
1679probe syscall.read {
1680 printf(&quot;reading fd=%d, fildes)
1681 if (fildes &gt; 10) tracethis = 1
1682}
1683
1684</PRE>
1685
1686</DL>
1687
1688
1689<P>
1690
1691<P>
1692<A NAME="lbAP">&nbsp;</A>
1693<H3>FUNCTIONS</H3>
1694
1695Systemtap scripts may define subroutines to factor out common work.
1696Functions take any number of scalar (integer or string) arguments, and
1697must return a single scalar (integer or string). An example function
1698declaration looks like this:
1699
1700<BR>
1701
1702<P>
1703
1704<DL COMPACT><DT><DD>
1705<PRE>
1706function thisfn (arg1, arg2) {
1707 return arg1 + arg2
1708}
1709
1710</PRE>
1711
1712</DL>
1713
1714
1715<P>
1716
1717Note the general absence of type declarations, which are instead
1718inferred by the translator. However, if desired, a function
1719definition may include explicit type declarations for its return value
1720and/or its arguments. This is especially helpful for embedded-C
1721functions. In the following example, the type inference engine need
1722only infer type type of arg2 (a string).
1723
1724<BR>
1725
1726<P>
1727
1728<DL COMPACT><DT><DD>
1729<PRE>
1730function thatfn:string (arg1:long, arg2) {
1731 return sprint(arg1) . arg2
1732}
1733
1734</PRE>
1735
1736</DL>
1737
1738
1739<P>
1740
1741Functions may call others or themselves
1742recursively, up to a fixed nesting limit. This limit is defined by
1743a macro in the translated C code and is in the neighbourhood of 10.
1744<P>
1745<A NAME="lbAQ">&nbsp;</A>
1746<H3>PRINTING</H3>
1747
1748There are a set of function names that are specially treated by the
1749translator. They format values for printing to the standard systemtap
1750output stream in a more convenient way. The
1751<I>sprint*</I>
1752
1753variants return the formatted string instead of printing it.
1754<DL COMPACT>
1755<DT><B>print</B>, <B>sprint</B>
1756
1757<DD>
1758Print one or more values of any type, concatenated directly together.
1759<DT><B>println</B>, <B>sprintln</B>
1760
1761<DD>
1762Print values like
1763<I>print</I> and <I>sprint</I>,
1764
1765but also append a newline.
1766<DT><B>printd</B>, <B>sprintd</B>
1767
1768<DD>
1769Take a string delimiter and two or more values of any type, and print the
1770values with the delimiter interposed. The delimiter must be a literal
1771string constant.
1772<DT><B>printdln</B>, <B>sprintdln</B>
1773
1774<DD>
1775Print values with a delimiter like
1776<I>printd</I> and <I>sprintd</I>,
1777
1778but also append a newline.
1779<DT><B>printf</B>, <B>sprintf</B>
1780
1781<DD>
1782Take a formatting string and a number of values of corresponding types,
1783and print them all. The format must be a literal string constant.
1784</DL>
1785<P>
1786
1787The
1788<I>printf</I>
1789
1790formatting directives similar to those of C, except that they are
1791fully type-checked by the translator:
1792<DL COMPACT><DT><DD>
1793<DL COMPACT>
1794<DT>%b<DD>
1795Writes a binary blob of the value given, instead of ASCII text. The width specifier determines the number of bytes to write; valid specifiers are %b %1b %2b %4b %8b. Default (%b) is 8 bytes.
1796<DT>%c<DD>
1797Character.
1798<DT>%d,%i<DD>
1799Signed decimal.
1800<DT>%m<DD>
1801Safely reads kernel memory at the given address, outputs its content. The optional precision specifier (not field width) determines the number of bytes to read - default is 1 byte. %10.4m prints 4 bytes of the memory in a 10-character-wide field.
1802<DT>%M<DD>
1803Same as %m, but outputs in hexadecimal. The minimal size of output is double the optional precision specifier - default is 1 byte (2 hex chars). %10.4M prints 4 bytes of the memory as 8 hexadecimal characters in a 10-character-wide field.
1804<DT>%o<DD>
1805Unsigned octal.
1806<DT>%p<DD>
1807Unsigned pointer address.
1808<DT>%s<DD>
1809String.
1810<DT>%u<DD>
1811Unsigned decimal.
1812<DT>%x<DD>
1813Unsigned hex value, in all lower-case.
1814<DT>%X<DD>
1815Unsigned hex value, in all upper-case.
1816<DT>%%<DD>
1817Writes a %.
1818</DL>
1819</DL>
1820
1821<P>
1822
1823The
1824<I>#</I>
1825
1826flag selects the alternate forms. For octal, this prefixes a 0. For hex, this
1827prefixes 0x or 0X, depending on case. For characters, this escapes
1828non-printing values with either C-like escapes or raw octal.
1829<P>
1830
1831Examples:
1832
1833<BR>
1834
1835<P>
1836
1837<DL COMPACT><DT><DD>
1838<PRE>
1839a = &quot;alice&quot;, b = &quot;bob&quot;, p = 0x1234abcd, i = 123, j = -1, id[a] = 1234, id[b] = 4567
1840print(&quot;hello&quot;)
1841 Prints: hello
1842println(b)
1843 Prints: bob\n
1844println(a . &quot; is &quot; . sprint(16))
1845 Prints: alice is 16
1846foreach (name in id) printdln(&quot;|&quot;, strlen(name), name, id[name])
1847 Prints: 5|alice|1234\n3|bob|4567
1848printf(&quot;%c is %s; %x or %X or %p; %d or %u\n&quot;,97,a,p,p,p,j,j)
1849 Prints: a is alice; 1234abcd or 1234ABCD or 0x1234abcd; -1 or 18446744073709551615\n
1850printf(&quot;2 bytes of kernel buffer at address %p: %2m&quot;, p, p)
1851 Prints: 2 byte of kernel buffer at address 0x1234abcd: &lt;binary data&gt;
1852printf(&quot;%4b&quot;, p)
1853 Prints (these values as binary data): 0x1234abcd
1854printf(&quot;%#o %#x %#X\n&quot;, 1, 2, 3)
1855 Prints: 01 0x2 0X3
1856printf(&quot;%#c %#c %#c\n&quot;, 0, 9, 42)
1857 Prints: \000 \t *
1858
1859</PRE>
1860
1861</DL>
1862
1863
1864<P>
1865
1866<P>
1867<A NAME="lbAR">&nbsp;</A>
1868<H3>STATISTICS</H3>
1869
1870It is often desirable to collect statistics in a way that avoids the
1871penalties of repeatedly exclusive locking the global variables those
1872numbers are being put into. Systemtap provides a solution using a
1873special operator to accumulate values, and several pseudo-functions to
1874extract the statistical aggregates.
1875<P>
1876
1877The aggregation operator is
1878<I>&lt;&lt;&lt;</I>,
1879
1880and resembles an assignment, or a C++ output-streaming operation.
1881The left operand specifies a scalar or array-index lvalue, which must
1882be declared global. The right operand is a numeric expression. The
1883meaning is intuitive: add the given number to the pile of numbers to
1884compute statistics of. (The specific list of statistics to gather
1885is given separately, by the extraction functions.)
1886
1887<BR>
1888
1889<P>
1890
1891<DL COMPACT><DT><DD>
1892<PRE>
1893foo &lt;&lt;&lt; 1
1894stats[pid()] &lt;&lt;&lt; memsize
1895
1896</PRE>
1897
1898</DL>
1899
1900
1901<P>
1902
1903<P>
1904
1905The extraction functions are also special. For each appearance of a
1906distinct extraction function operating on a given identifier, the
1907translator arranges to compute a set of statistics that satisfy it.
1908The statistics system is thereby &quot;on-demand&quot;. Each execution of
1909an extraction function causes the aggregation to be computed for
1910that moment across all processors.
1911<P>
1912
1913Here is the set of extractor functions. The first argument of each is
1914the same style of lvalue used on the left hand side of the accumulate
1915operation. The
1916<I>@count(v)</I>, <I>@sum(v)</I>, <I>@min(v)</I>, <I>@max(v)</I>, <I>@avg(v)</I>
1917
1918extractor functions compute the number/total/minimum/maximum/average
1919of all accumulated values. The resulting values are all simple
1920integers. Arrays containing aggregates may be sorted and iterated.
1921See the
1922<B>foreach</B>
1923
1924construct above.
1925<P>
1926
1927Histograms are also available, but are more complicated because they
1928have a vector rather than scalar value.
1929<I>@hist_linear(v,start,stop,interval)</I>
1930
1931represents a linear histogram from &quot;start&quot; to &quot;stop&quot; by increments
1932of &quot;interval&quot;. The interval must be positive. Similarly,
1933<I>@hist_log(v)</I>
1934
1935represents a base-2 logarithmic histogram. Printing a histogram
1936with the
1937<I>print</I>
1938
1939family of functions renders a histogram object as a tabular
1940&quot;ASCII art&quot; bar chart.
1941
1942<BR>
1943
1944<P>
1945
1946<DL COMPACT><DT><DD>
1947<PRE>
1948probe timer.profile {
1949 x[1] &lt;&lt;&lt; pid()
1950 x[2] &lt;&lt;&lt; uid()
1951 y &lt;&lt;&lt; tid()
1952}
1953global x // an array containing aggregates
1954global y // a scalar
1955probe end {
1956 foreach ([i] in x @count+) {
1957 printf (&quot;x[%d]: avg %d = sum %d / count %d\n&quot;,
1958 i, @avg(x[i]), @sum(x[i]), @count(x[i]))
1959 println (@hist_log(x[i]))
1960 }
1961 println (&quot;y:&quot;)
1962 println (@hist_log(y))
1963}
1964
1965</PRE>
1966
1967</DL>
1968
1969
1970<P>
1971
1972<P>
1973<A NAME="lbAS">&nbsp;</A>
1974<H3>TYPECASTING</H3>
1975
1976Once a pointer has been saved into a script integer variable, the
1977translator loses the type information necessary to access members from
1978that pointer. Using the
1979<I>@cast()</I>
1980
1981operator tells the translator how to read a pointer.
1982
1983<BR>
1984
1985<P>
1986
1987<DL COMPACT><DT><DD>
1988<PRE>
1989@cast(p, &quot;type_name&quot;[, &quot;module&quot;])-&gt;member
1990
1991</PRE>
1992
1993</DL>
1994
1995
1996<P>
1997
1998<P>
1999
2000This will interpret
2001<I>p</I>
2002
2003as a pointer to a struct/union named
2004<I>type_name</I>
2005
2006and dereference the
2007<I>member</I>
2008
2009value. Further
2010<I>-&gt;subfield</I>
2011
2012expressions may be appended to dereference more levels.
2013
2014NOTE:
2015the same dereferencing operator
2016<I>-&gt;</I>
2017
2018is used to refer to both direct containment or pointer indirection.
2019Systemtap automatically determines which. The optional
2020<I>module</I>
2021
2022tells the translator where to look for information about that type.
2023Multiple modules may be specified as a list with
2024<I>:</I>
2025
2026separators. If the module is not specified, it will default either to
2027the probe module for dwarf probes, or to &quot;kernel&quot; for functions and all
2028other probes types.
2029<P>
2030
2031The translator can create its own module with type information from a header
2032surrounded by angle brackets, in case normal debuginfo is not available. For
2033kernel headers, prefix it with &quot;kernel&quot; to use the appropriate build system.
2034All other headers are build with default GCC parameters into a user module.
2035Multiple headers may be specified in sequence to resolve a codependency.
2036
2037<BR>
2038
2039<P>
2040
2041<DL COMPACT><DT><DD>
2042<PRE>
2043@cast(tv, &quot;timeval&quot;, &quot;&lt;<A HREF="file:///usr/include/sys/time.h">sys/time.h</A>&gt;&quot;)-&gt;tv_sec
2044@cast(task, &quot;task_struct&quot;, &quot;kernel&lt;<A HREF="file:///usr/include/linux/sched.h">linux/sched.h</A>&gt;&quot;)-&gt;tgid
2045@cast(task, &quot;task_struct&quot;,
2046 &quot;kernel&lt;<A HREF="file:///usr/include/linux/sched.h">linux/sched.h</A>&gt;&lt;<A HREF="file:///usr/include/linux/fs_struct.h">linux/fs_struct.h</A>&gt;&quot;)-&gt;fs-&gt;umask
2047
2048</PRE>
2049
2050</DL>
2051
2052
2053<P>
2054
2055Values acquired by
2056<B>@cast</B>
2057
2058may be pretty-printed by the
2059
2060$ &quot; and &quot; $$
2061suffix operators, the same way as described in the CONTEXT VARIABLES
2062section of the
2063<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap)
2064
2065manual page.
2066<P>
2067<P>
2068
2069When in guru mode, the translator will also allow scripts to assign new
2070values to members of typecasted pointers.
2071<P>
2072
2073Typecasting is also useful in the case of
2074<I>void*</I>
2075
2076members whose type may be determinable at runtime.
2077
2078<BR>
2079
2080<P>
2081
2082<DL COMPACT><DT><DD>
2083<PRE>
2084probe foo {
2085 if ($var-&gt;type == 1) {
2086 value = @cast($var-&gt;data, &quot;type1&quot;)-&gt;bar
2087 } else {
2088 value = @cast($var-&gt;data, &quot;type2&quot;)-&gt;baz
2089 }
2090 print(value)
2091}
2092
2093</PRE>
2094
2095</DL>
2096
2097
2098<P>
2099
2100<P>
2101<A NAME="lbAT">&nbsp;</A>
2102<H3>EMBEDDED C</H3>
2103
2104When in guru mode, the translator accepts embedded code in the
2105top level of the script. Such code is enclosed between
2106<I>%{</I>
2107
2108and
2109<I>%}</I>
2110
2111markers, and is transcribed verbatim, without analysis, in some
2112sequence, into the top level of the generated C code. At the
2113outermost level, this may be useful to add
2114<I>#include</I>
2115
2116instructions, and any auxiliary definitions for use by other embedded
2117code.
2118<P>
2119
2120Another place where embedded code is permitted is as a function body.
2121In this case, the script language body is replaced entirely by a piece
2122of C code enclosed again between
2123<I>%{</I> and <I>%}</I>
2124
2125markers.
2126This C code may do anything reasonable and safe. There are a number
2127of undocumented but complex safety constraints on atomicity,
2128concurrency, resource consumption, and run time limits, so this
2129is an advanced technique.
2130<P>
2131
2132The memory locations set aside for input and output values
2133are made available to it using macros
2134<I>STAP_ARG_*</I>
2135
2136and
2137<I>STAP_RETVALUE</I>.
2138
2139Errors may be signalled with STAP_ERROR. The function may return
2140early with STAP_RETURN. Here are some examples:
2141
2142<BR>
2143
2144<P>
2145
2146<DL COMPACT><DT><DD>
2147<PRE>
2148function integer_ops (val) %{
2149 STAP_RETVALUE = STAP_ARG_val + 1;
2150 if (STAP_RETVALUE == 4)
2151 STAP_ERROR(&quot;wrong guess: %d&quot;, (int) STAP_RETVALUE);
2152 if (STAP_RETVALUE == 3)
2153 STAP_RETURN(0);
2154 STAP_RETVALUE ++;
2155%}
2156function string_ops (val) %{
2157 strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN);
2158 strlcat (STAP_RETVALUE, &quot;one&quot;, MAXSTRINGLEN);
2159 if (strcmp (STAP_RETVALUE, &quot;three-two-one&quot;))
2160 STAP_RETURN(&quot;parameter should be three-two-&quot;);
2161%}
2162function no_ops () %{
2163 STAP_RETURN(); /* function inferred with no return value */
2164%}
2165
2166</PRE>
2167
2168</DL>
2169
2170
2171<P>
2172
2173The function argument and return value types have to be inferred by
2174the translator from the call sites in order for this to work. The
2175user should examine C code generated for ordinary script-language
2176functions in order to write compatible embedded-C ones.
2177<P>
2178
2179The last place where embedded code is permitted is as an expression rvalue.
2180In this case, the C code enclosed between
2181<I>%{</I> and <I>%}</I>
2182
2183markers is interpreted as an ordinary expression value. It is assumed
2184to be a normal 64-bit signed number, unless the marker
2185<I>/* string */</I>
2186
2187is included, in which case it's treated as a string.
2188
2189<BR>
2190
2191<P>
2192
2193<DL COMPACT><DT><DD>
2194<PRE>
2195function add_one (val) {
2196 return val + %{ 1 %}
2197}
2198function add_string_two (val) {
2199 return val . %{ /* string */ &quot;two&quot; %}
2200}
2201
2202</PRE>
2203
2204</DL>
2205
2206
2207<P>
2208
2209<P>
2210
2211The embedded-C code may contain markers to assert optimization
2212and safety properties.
2213<DL COMPACT>
2214<DT><I>/* pure */</I>
2215
2216<DD>
2217means that the C code has no side effects and may be elided entirely if its
2218value is not used by script code.
2219<DT><I>/* unprivileged */</I>
2220
2221<DD>
2222means that the C code is so safe that even unprivileged users are permitted
2223to use it.
2224<DT><I>/* myproc-unprivileged */</I>
2225
2226<DD>
2227means that the C code is so safe that even unprivileged users are permitted
2228to use it, provided that the target of the current probe is within the user's
2229own process.
2230<DT><I>/* guru */</I>
2231
2232<DD>
2233means that the C code is so unsafe that a systemtap user must specify
2234<I>-g</I>
2235
2236(guru mode) to use this.
2237<DT><I>/* unmangled */</I>
2238
2239<DD>
2240in an embedded-C function, means that the legacy (pre-1.8) argument
2241access syntax should be made available inside the function. Hence, in
2242addition to
2243<I>STAP_ARG_foo</I>
2244
2245and
2246<I>STAP_RETVALUE</I>
2247
2248one can use
2249<I>THIS-&gt;foo</I>
2250
2251and
2252<I>THIS-&gt;__retvalue</I>
2253
2254respectively inside the function. This is useful for quickly migrating code written for SystemTap version 1.7 and earlier.
2255<DT><I>/* string */</I>
2256
2257<DD>
2258in embedded-C expressions only, means that the expression has
2259<I>const char *</I>
2260
2261type and should be treated as a string value, instead of
2262the default long numeric.
2263<P>
2264</DL>
2265<A NAME="lbAU">&nbsp;</A>
2266<H3>BUILT-INS</H3>
2267
2268A set of builtin probe point aliases are provided
2269by the scripts installed in the directory specified in the
2270<I><A HREF="stappaths.7.html">stappaths</A></I>(7)
2271
2272manual page. The functions are described in the
2273<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap)
2274
2275manual page.
2276<P>
2277<A NAME="lbAV">&nbsp;</A>
2278<H2>PROCESSING</H2>
2279
2280The translator begins pass 1 by parsing the given input script,
2281and all scripts (files named
2282<I>*.stp</I>)
2283
2284found in a tapset directory. The directories listed
2285with
2286<B>-I</B>
2287
2288are processed in sequence, each processed in &quot;guru mode&quot;. For each
2289directory, a number of subdirectories are also searched. These
2290subdirectories are derived from the selected kernel version (the
2291<B>-R</B>
2292
2293option),
2294in order to allow more kernel-version-specific scripts to override less
2295specific ones. For example, for a kernel version
2296<I>2.6.12-23.FC3</I>
2297
2298the following patterns would be searched, in sequence:
2299<I>2.6.12-23.FC3/*.stp</I>,
2300
2301<I>2.6.12/*.stp</I>,
2302
2303<I>2.6/*.stp</I>,
2304
2305and finally
2306<I>*.stp</I>.
2307
2308Stopping the translator after pass 1 causes it to print the parse trees.
2309<P>
2310<P>
2311
2312In pass 2, the translator analyzes the input script to resolve symbols
2313and types. References to variables, functions, and probe aliases that
2314are unresolved internally are satisfied by searching through the
2315parsed tapset script files. If any tapset script file is selected
2316because it defines an unresolved symbol, then the entirety of that
2317file is added to the translator's resolution queue. This process
2318iterates until all symbols are resolved and a subset of tapset script
2319files is selected.
2320<P>
2321
2322Next, all probe point descriptions are validated
2323against the wide variety supported by the translator. Probe points that
2324refer to code locations (&quot;synchronous probe points&quot;) require the
2325appropriate kernel debugging information to be installed. In the
2326associated probe handlers, target-side variables (whose names begin
2327with &quot;$&quot;) are found and have their run-time locations decoded.
2328<P>
2329
2330Next, all probes and functions are analyzed for optimization
2331opportunities, in order to remove variables, expressions, and
2332functions that have no useful value and no side-effect. Embedded-C
2333functions are assumed to have side-effects unless they include the
2334magic string
2335<B>/*&nbsp;pure&nbsp;*/</B>.
2336
2337Since this optimization can hide latent code errors such as type
2338mismatches or invalid $context variables, it sometimes may be useful
2339to disable the optimizations with the
2340<B>-u</B>
2341
2342option.
2343<P>
2344
2345Finally, all variable, function, parameter, array, and index types are
2346inferred from context (literals and operators). Stopping the
2347translator after pass 2 causes it to list all the probes, functions,
2348and variables, along with all inferred types. Any inconsistent or
2349unresolved types cause an error.
2350<P>
2351<P>
2352
2353In pass 3, the translator writes C code that represents the actions
2354of all selected script files, and creates a
2355<I>Makefile</I>
2356
2357to build that into a kernel object. These files are placed into a
2358temporary directory. Stopping the translator at this point causes
2359it to print the contents of the C file.
2360<P>
2361<P>
2362
2363In pass 4, the translator invokes the Linux kernel build system to
2364create the actual kernel object file. This involves running
2365<I>make</I>
2366
2367in the temporary directory, and requires a kernel module build
2368system (headers, config and Makefiles) to be installed in the usual
2369spot
2370<I>/lib/modules/VERSION/build</I>.
2371
2372Stopping the translator after pass 4 is the last chance before
2373running the kernel object. This may be useful if you want to
2374archive the file.
2375<P>
2376<P>
2377
2378In pass 5, the translator invokes the systemtap auxiliary program
2379<I>staprun</I>
2380
2381program for the given kernel object. This program arranges to load
2382the module then communicates with it, copying trace data from the
2383kernel into temporary files, until the user sends an interrupt signal.
2384Any run-time error encountered by the probe handlers, such as running
2385out of memory, division by zero, exceeding nesting or runtime limits,
2386results in a soft error indication. Soft errors in excess of
2387MAXERRORS block of all subsequent probes (except error-handling
2388probes), and terminate the session. Finally,
2389<I>staprun</I>
2390
2391unloads the module, and cleans up.
2392<P>
2393<A NAME="lbAW">&nbsp;</A>
2394<H3>ABNORMAL TERMINATION</H3>
2395
2396<P>
2397One should avoid killing the stap process forcibly, for example with
2398SIGKILL, because the stapio process (a child process of the stap
2399process) and the loaded module may be left running on the system. If
2400this happens, send SIGTERM or SIGINT to any remaining stapio
2401processes, then use rmmod to unload the systemtap module.
2402<P>
2403<P>
2404<A NAME="lbAX">&nbsp;</A>
2405<H2>EXAMPLES</H2>
2406
2407See the
2408<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap)
2409
2410manual page for a collection of samples.
2411<P>
2412<A NAME="lbAY">&nbsp;</A>
2413<H2>CACHING</H2>
2414
2415The systemtap translator caches the pass 3 output (the generated C
2416code) and the pass 4 output (the compiled kernel module) if pass 4
2417completes successfully. This cached output is reused if the same
2418script is translated again assuming the same conditions exist (same kernel
2419version, same systemtap version, etc.). Cached files are stored in
2420the
2421<I>$SYSTEMTAP_DIR/cache</I>
2422
2423directory. The cache can be limited by having the file
2424<I>cache_mb_limit</I>
2425
2426placed in the cache directory (shown above) containing only an ASCII
2427integer representing how many MiB the cache should not exceed. In the
2428absence of this file, a default will be created with the limit set to 256MiB.
2429This is a 'soft' limit in that the cache will be cleaned after a new entry
2430is added if the cache clean interval is exceeded, so the total cache size may
2431temporarily exceed this limit. This interval can be specified by having the
2432file
2433<I>cache_clean_interval_s</I>
2434
2435placed in the cache directory (shown above) containing only an ASCII integer
2436representing the interval in seconds. In the absence of this file, a default
2437will be created with the interval set to 300 s.
2438<P>
2439<A NAME="lbAZ">&nbsp;</A>
2440<H2>SAFETY AND SECURITY</H2>
2441
2442Systemtap is an administrative tool. It exposes kernel internal data
2443structures and potentially private user information.
2444<P>
2445To actually run the kernel objects it builds, a user must be one of
2446the following:
2447<DL COMPACT>
2448<DT>&bull;<DD>
2449the root user;
2450<DT>&bull;<DD>
2451a member of the
2452<I>stapdev</I>
2453
2454and
2455<I>stapusr</I>
2456
2457groups;
2458<DT>&bull;<DD>
2459a member of the
2460<I>stapsys</I>
2461
2462and
2463<I>stapusr</I>
2464
2465groups; or
2466<DT>&bull;<DD>
2467a member of the
2468<I>stapusr</I>
2469
2470group.
2471</DL>
2472<P>
2473
2474The root user or a user who is a member of both the
2475<I>stapdev</I>
2476
2477and
2478<I>stapusr</I>
2479
2480groups can build and run any systemtap script.
2481<P>
2482
2483A user who is a member of both the
2484<I>stapsys</I>
2485
2486and
2487<I>stapusr</I>
2488
2489groups can only use pre-built modules under the following conditions:
2490<DL COMPACT>
2491<DT>&bull;<DD>
2492The module has been signed by a trusted signer. Trusted signers are normally
2493systemtap compile-servers which sign modules when the <I>--privilege</I> option is
2494specified by the client. See the
2495<I><A HREF="stap-server.8.html">stap-server</A></I>(8)
2496
2497manual page for more information.
2498<DT>&bull;<DD>
2499The module was built using the <I>--privilege=stapsys</I> or the <I>--privilege=stapusr</I>
2500options.
2501</DL>
2502<P>
2503
2504Members of only the
2505<I>stapusr</I>
2506
2507group can only use pre-built modules under the following conditions:
2508<DL COMPACT>
2509<DT>&bull;<DD>
2510The module is located in
2511the /lib/modules/VERSION/systemtap directory. This directory
2512must be owned by root and not be world writable.
2513</DL>
2514<P>
2515
2516or
2517<DL COMPACT>
2518<DT>&bull;<DD>
2519The module has been signed by a trusted signer. Trusted signers are normally
2520systemtap compile-servers which sign modules when the <I>--privilege</I> option is
2521specified by the client. See the
2522<I><A HREF="stap-server.8.html">stap-server</A></I>(8)
2523
2524manual page for more information.
2525<DT>&bull;<DD>
2526The module was built using the FI--privilege=stapusr option.
2527</DL>
2528<P>
2529
2530The kernel modules generated by
2531<I>stap</I>
2532
2533program are run by the
2534<I>staprun</I>
2535
2536program. The latter is a part of the Systemtap package, dedicated to
2537module loading and unloading (but only in the white zone), and
2538kernel-to-user data transfer. Since
2539<I>staprun</I>
2540
2541does not perform any additional security checks on the kernel objects
2542it is given, it would be unwise for a system administrator to add
2543untrusted users to the
2544<I>stapdev</I>
2545
2546or
2547<I>stapusr</I>
2548
2549groups.
2550<P>
2551
2552The translator asserts certain safety constraints. It aims to ensure
2553that no handler routine can run for very long, allocate memory,
2554perform unsafe operations, or in unintentionally interfere with the
2555kernel. Uses of script global variables are automatically read/write
2556locked as appropriate, to protect against manipulation by concurrent probe
2557handlers. (Deadlocks are detected with timeouts. Use the
2558<B>-t</B>
2559
2560flag to receive reports of excessive lock contention.) Use of guru mode
2561constructs such as embedded C can violate these constraints, leading
2562to kernel crash or data corruption.
2563<P>
2564
2565The resource use limits are set by macros in the generated C code.
2566These may be overridden with the
2567<B>-D</B>
2568
2569flag. A selection of these is as follows:
2570<DL COMPACT>
2571<DT>MAXNESTING<DD>
2572Maximum number of nested function calls. Default determined by
2573script analysis, with a bonus 10 slots added for recursive
2574scripts.
2575<DT>MAXSTRINGLEN<DD>
2576Maximum length of strings, default 128.
2577<DT>MAXTRYLOCK<DD>
2578Maximum number of iterations to wait for locks on global variables
2579before declaring possible deadlock and skipping the probe, default 1000.
2580<DT>MAXACTION<DD>
2581Maximum number of statements to execute during any single probe hit
2582(with interrupts disabled),
2583default 1000.
2584<DT>MAXACTION_INTERRUPTIBLE<DD>
2585Maximum number of statements to execute during any single probe hit
2586which is executed with interrupts enabled (such as begin/end probes),
2587default (MAXACTION * 10).
2588<DT>MAXBACKTRACE<DD>
2589Maximum number of stack frames that will be be processed by the stap
2590runtime unwinder as produced by the backtrace functions in the
2591[u]context-unwind.stp tapsets, default 20.
2592<DT>MAXMAPENTRIES<DD>
2593Default maximum number of rows in any single global array, default 2048.
2594Individual arrays may be declared with a larger or smaller limit instead:
2595
2596<BR>
2597
2598<P>
2599
2600<DL COMPACT><DT><DD>
2601<PRE>
2602global big[10000],little[5]
2603
2604</PRE>
2605
2606</DL>
2607
2608
2609<P>
2610
2611or denoted with
2612<I>%</I>
2613
2614to make them wrap-around automatically.
2615<DT>MAXERRORS<DD>
2616Maximum number of soft errors before an exit is triggered, default 0, which
2617means that the first error will exit the script. Note that with the
2618<B>--suppress-handler-errors</B>
2619
2620option, this limit is not enforced.
2621<DT>MAXSKIPPED<DD>
2622Maximum number of skipped probes before an exit is triggered, default 100.
2623Running systemtap with -t (timing) mode gives more details about skipped
2624probes. With the default -DINTERRUPTIBLE=1 setting, probes skipped due to
2625reentrancy are not accumulated against this limit. Note that with the
2626<B>--suppress-handler-errors</B>
2627
2628option, this limit is not enforced.
2629<DT>MINSTACKSPACE<DD>
2630Minimum number of free kernel stack bytes required in order to
2631run a probe handler, default 1024. This number should be large enough
2632for the probe handler's own needs, plus a safety margin.
2633<DT>MAXUPROBES<DD>
2634Maximum number of concurrently armed user-space probes (uprobes), default
2635somewhat larger than the number of user-space probe points named in the script.
2636This pool needs to be potentialy large because individual uprobe objects (about
263764 bytes each) are allocated for each process for each matching script-level probe.
2638<DT>STP_MAXMEMORY<DD>
2639Maximum amount of memory (in kilobytes) that the systemtap module
2640should use, default unlimited. The memory size includes the size of
2641the module itself, plus any additional allocations. This only tracks
2642direct allocations by the systemtap runtime. This does not track
2643indirect allocations (as done by kprobes/uprobes/etc. internals).
2644<DT>STP_PROCFS_BUFSIZE<DD>
2645Size of procfs probe read buffers (in bytes). Defaults to
2646<I>MAXSTRINGLEN</I>.
2647
2648This value can be overridden on a per-procfs file basis using the
2649procfs read probe
2650<I>.maxsize(MAXSIZE)</I>
2651
2652parameter.
2653</DL>
2654<P>
2655
2656With scripts that contain probes on any interrupt path, it is possible that
2657those interrupts may occur in the middle of another probe handler. The probe
2658in the interrupt handler would be skipped in this case to avoid reentrance.
2659To work around this issue, execute stap with the option
2660<B>-DINTERRUPTIBLE=0</B>
2661
2662to mask interrupts throughout the probe handler. This does add some extra
2663overhead to the probes, but it may prevent reentrance for common problem
2664cases. However, probes in NMI handlers and in the callpath of the stap
2665runtime may still be skipped due to reentrance.
2666<P>
2667<P>
2668
2669Multiple scripts can write data into a relay buffer concurrently. A host
2670script provides an interface for accessing its relay buffer to guest scripts.
2671Then, the output of the guests are merged into the output of the host.
2672To run a script as a host, execute stap with
2673<B>-DRELAYHOST[=name]</B>
2674
2675option. The
2676<B>name</B>
2677
2678identifies your host script among several hosts.
2679While running the host, execute stap with
2680<B>-DRELAYGUEST[=name]</B>
2681
2682to add a guest script to the host.
2683Note that you must unload guests before unloading a host. If there are some
2684guests connected to the host, unloading the host will be failed.
2685<P>
2686<P>
2687
2688In case something goes wrong with
2689<I>stap</I> or <I>staprun</I>
2690
2691after a probe has already started running, one may safely kill both
2692user processes, and remove the active probe kernel module with
2693<I>rmmod</I>.
2694
2695Any pending trace messages may be lost.
2696<P>
2697<P>
2698
2699In addition to the methods outlined above, the generated kernel module
2700also uses overload processing to make sure that probes can't run for
2701too long. If more than STP_OVERLOAD_THRESHOLD cycles (default
2702500000000) have been spent in all the probes on a single cpu during
2703the last STP_OVERLOAD_INTERVAL cycles (default 1000000000), the probes
2704have overloaded the system and an exit is triggered.
2705<P>
2706
2707By default, overload processing is turned on for all modules. If you
2708would like to disable overload processing, define STP_NO_OVERLOAD (or
2709its alias STAP_NO_OVERLOAD).
2710<P>
2711<A NAME="lbBA">&nbsp;</A>
2712<H2>UNPRIVILEGED USERS</H2>
2713
2714<P>
2715Systemtap exposes kernel internal data
2716structures and potentially private user information. Because of this, use of
2717systemtap's full capabilities are restricted to root and to users who are
2718members of the groups stapdev and stapusr.
2719<P>
2720However, a restricted set of systemtap's features can be made available to
2721trusted, unprivileged users. These users are members of the group stapusr
2722only, or members of the groups stapusr and stapsys.
2723These users can load systemtap modules which have been compiled and
2724certified by a trusted systemtap compile-server. See the descriptions of the
2725options <I>--privilege</I> and <I>--use-server</I>. See
2726<I>README.unprivileged</I> in the systemtap source code for information about
2727setting up a trusted compile server.
2728<P>
2729The restrictions enforced when <I>--privilege=stapsys</I> is specified are designed
2730to prevent unprivileged users from:
2731<DL COMPACT><DT><DD>
2732<DL COMPACT>
2733<DT>&bull;<DD>
2734harming the system maliciously.
2735</DL>
2736</DL>
2737
2738<P>
2739The restrictions enforced when <I>--privilege=stapusr</I> is specified are designed
2740to prevent unprivileged users from:
2741<DL COMPACT><DT><DD>
2742<DL COMPACT>
2743<DT>&bull;<DD>
2744harming the system maliciously.
2745<DT>&bull;<DD>
2746gaining access to information which would not normally be available to an
2747unprivileged user.
2748<DT>&bull;<DD>
2749disrupting the performance of processes owned by other users of the system.
2750Some overhead to the system in general is unavoidable since the
2751unprivileged user's probes
2752will be triggered at the appropriate times. What we would like to avoid is
2753targeted interruption of another user's processes which would not normally be
2754possible by an unprivileged user.
2755</DL>
2756</DL>
2757
2758<P>
2759<A NAME="lbBB">&nbsp;</A>
2760<H3>PROBE RESTRICTIONS</H3>
2761
2762A member of the groups stapusr and stapsys may use all probe points.
2763<P>
2764
2765A member of only the group stapusr may use only the following probes:
2766<DL COMPACT><DT><DD>
2767<DL COMPACT>
2768<DT>&bull;<DD>
2769begin, <A HREF="../mann/begin.n.html">begin</A>(n)
2770<DT>&bull;<DD>
2771end, <A HREF="../mann/end.n.html">end</A>(n)
2772<DT>&bull;<DD>
2773<A HREF="../mann/error.n.html">error</A>(n)
2774<DT>&bull;<DD>
2775never
2776<DT>&bull;<DD>
2777process.*, where the target process is owned by the user.
2778<DT>&bull;<DD>
2779timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)*
2780<DT>&bull;<DD>
2781<A HREF="../mann/timer.hz.n.html">timer.hz</A>(n)
2782</DL>
2783</DL>
2784
2785<P>
2786<A NAME="lbBC">&nbsp;</A>
2787<H3>SCRIPTING LANGUAGE RESTRICTIONS</H3>
2788
2789The following scripting language features are unavailable to all unprivileged users:
2790<P>
2791<DL COMPACT><DT><DD>
2792<DL COMPACT>
2793<DT>&bull;<DD>
2794any feature enabled by the Guru Mode (-g) option.
2795<DT>&bull;<DD>
2796embedded C code.
2797</DL>
2798</DL>
2799
2800<P>
2801<A NAME="lbBD">&nbsp;</A>
2802<H3>RUNTIME RESTRICTIONS</H3>
2803
2804The following runtime restrictions are placed upon all unprivileged users:
2805<DL COMPACT><DT><DD>
2806<DL COMPACT>
2807<DT>&bull;<DD>
2808Only the default runtime code (see <I>-R</I>) may be used.
2809</DL>
2810</DL>
2811
2812<P>
2813Additional restrictions are placed on members of only the group stapusr:
2814<DL COMPACT><DT><DD>
2815<DL COMPACT>
2816<DT>&bull;<DD>
2817Probing of processes owned by other users is not permitted.
2818<DT>&bull;<DD>
2819Access of kernel memory (read and write) is not permitted.
2820</DL>
2821</DL>
2822
2823<P>
2824<A NAME="lbBE">&nbsp;</A>
2825<H3>COMMAND LINE OPTION RESTRICTIONS</H3>
2826
2827Some command line options provide access to features which must not be available
2828to all unprivileged users:
2829<P>
2830<DL COMPACT><DT><DD>
2831<DL COMPACT>
2832<DT>&bull;<DD>
2833-g may not be specified.
2834<DT>&bull;<DD>
2835The following options may not be used by the compile-server client:
2836
2837<BR>
2838
2839<P>
2840
2841<DL COMPACT><DT><DD>
2842<PRE>
2843 -a, -B, -D, -I, -r, -R
2844
2845</PRE>
2846
2847</DL>
2848
2849
2850<P>
2851
2852</DL>
2853</DL>
2854
2855<P>
2856<A NAME="lbBF">&nbsp;</A>
2857<H3>ENVIRONMENT RESTRICTIONS</H3>
2858
2859The following environment variables must not be set for all unprivileged users:
2860
2861<BR>
2862
2863<P>
2864
2865<DL COMPACT><DT><DD>
2866<PRE>
2867SYSTEMTAP_RUNTIME
2868SYSTEMTAP_TAPSET
2869SYSTEMTAP_DEBUGINFO_PATH
2870
2871</PRE>
2872
2873</DL>
2874
2875
2876<P>
2877
2878<P>
2879<A NAME="lbBG">&nbsp;</A>
2880<H3>TAPSET RESTRICTIONS</H3>
2881
2882In general, tapset functions are only available for members of the
2883group stapusr when they do not gather information that an ordinary
2884program running with that user's privileges would be denied access to.
2885<P>
2886There are two categories of unprivileged tapset functions. The first
2887category consists of utility functions that are unconditionally
2888available to all users; these include such things as:
2889
2890<BR>
2891
2892<P>
2893
2894<DL COMPACT><DT><DD>
2895<PRE>
2896cpu:long ()
2897exit ()
2898str_replace:string (prnt_str:string, srch_str:string, rplc_str:string)
2899
2900</PRE>
2901
2902</DL>
2903
2904
2905<P>
2906
2907<P>
2908The second category consists of so-called
2909<I>myproc-unprivileged</I>
2910
2911functions that can only gather information within their own
2912processes. Scripts that wish to use these functions must test the
2913result of the tapset function <I>is_myproc</I> and only call these
2914functions if the result is 1. The script will exit immediately if any
2915of these functions are called by an unprivileged user within a probe
2916within a process which is not owned by that user. Examples of
2917<I>myproc-unprivileged</I>
2918
2919functions include:
2920
2921<BR>
2922
2923<P>
2924
2925<DL COMPACT><DT><DD>
2926<PRE>
2927print_usyms (stk:string)
2928user_int:long (addr:long)
2929usymname:string (addr:long)
2930
2931</PRE>
2932
2933</DL>
2934
2935
2936<P>
2937
2938<P>
2939A compile error is triggered when any function not in either of the
2940above categories is used by members of only the group stapusr.
2941<P>
2942No other built-in tapset functions may be used by members of only the
2943group stapusr.
2944<P>
2945<A NAME="lbBH">&nbsp;</A>
2946<H2>ALTERNATE RUNTIMES</H2>
2947
2948<P>
2949As described above, systemtap's default runtime mode involves building and
2950loading kernel modules, with various security tradeoffs presented. Systemtap
2951now includes a new prototype backend, selected with <I>--runtime=dyninst</I>,
2952which uses Dyninst to instrument a user's own processes at runtime. This
2953backend does not use kernel modules, and does not require root privileges, but
2954is restricted with respect to the kinds of probes and other constructs that a
2955script may use.
2956<P>
2957The <I>dyninst</I> runtime operates in target-attach mode, so it does require
2958a <I>-c COMMAND</I> or <I>-x PID</I> process. For example:
2959
2960<BR>
2961
2962<P>
2963
2964<DL COMPACT><DT><DD>
2965<PRE>
2966stap --runtime=dyninst -c 'stap -V' \
2967 -e 'probe process.function(&quot;main&quot;)
2968 { println(&quot;hi from dyninst!&quot;) }'
2969
2970</PRE>
2971
2972</DL>
2973
2974
2975<P>
2976
2977<P>
2978It may be necessary to disable a conflicting selinux check with
2979
2980<BR>
2981
2982<P>
2983
2984<DL COMPACT><DT><DD>
2985<PRE>
2986# setsebool allow_execstack 1
2987
2988</PRE>
2989
2990</DL>
2991
2992
2993<P>
2994
2995<P>
2996<A NAME="lbBI">&nbsp;</A>
2997<H2>EXIT STATUS</H2>
2998
2999<P>
3000The systemtap translator generally returns with a success code of 0 if
3001the requested script was processed and executed successfully through
3002the requested pass. Otherwise, errors may be printed to stderr and
3003a failure code is returned. Use
3004<I>-v</I>
3005
3006or
3007<I>-vp N</I>
3008
3009to increase (global or per-pass) verbosity to identify the source of the
3010trouble.
3011<P>
3012In listings mode
3013(<I>-l</I> and <I>-L</I>),
3014
3015error messages are normally suppressed. A success code of 0 is returned
3016if at least one matching probe was found.
3017<P>
3018A script executing in pass 5 that is interrupted with ^C / SIGINT is
3019considered to be successful.
3020<P>
3021<A NAME="lbBJ">&nbsp;</A>
3022<H2>DEPRECATION</H2>
3023
3024<P>
3025Over time, some features of the script language and the tapset library
3026may undergo incompatible changes, so that a script written against
3027an old version of systemtap may no longer run. In these cases, it may
3028help to run systemtap with the
3029<I>--compatible VERSION</I>
3030
3031flag, specifying the last known working version. Running
3032systemtap with the
3033<I>--check-version</I>
3034
3035flag will output a warning if any possible incompatible elements have
3036been parsed. Deprecation historical details may be found in the NEWS file.
3037<P>
3038<A NAME="lbBK">&nbsp;</A>
3039<H2>FILES</H2>
3040
3041<DL COMPACT>
3042<DT>Important files and their corresponding paths can be located in the <DD>
3043stappaths (7) manual page.
3044<P>
3045</DL>
3046<A NAME="lbBL">&nbsp;</A>
3047<H2>SEE ALSO</H2>
3048
3049
3050<PRE>
3051<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
3052<I>function::*</I>(3stap),
3053<I>probe::*</I>(3stap),
3054<I>tapset::*</I>(3stap),
3055<I><A HREF="stappaths.7.html">stappaths</A></I>(7),
3056<I><A HREF="staprun.8.html">staprun</A></I>(8),
3057<I><A HREF="stapdyn.8.html">stapdyn</A></I>(8),
3058<I><A HREF="systemtap.8.html">systemtap</A></I>(8),
3059<I><A HREF="stapvars.3stap.html">stapvars</A></I>(3stap),
3060<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap),
3061<I><A HREF="stap-server.8.html">stap-server</A></I>(8),
3062<I><A HREF="stap-prep.1.html">stap-prep</A></I>(1),
3063<I><A HREF="awk.1.html">awk</A></I>(1),
3064<I><A HREF="gdb.1.html">gdb</A></I>(1)
3065
3066</PRE><A NAME="lbBM">&nbsp;</A>
3067<H2>BUGS</H2>
3068
3069Use the Bugzilla link of the project web page or our mailing list.
3070
3071<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>, <B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
3072
3073
3074<P>
3075
3076<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap),
3077
3078
3079<B><A HREF="https://sourceware.org/systemtap/wiki/HowToReportBugs">https://sourceware.org/systemtap/wiki/HowToReportBugs</A></B>
3080
3081
3082<P>
3083
3084<HR>
3085<A NAME="index">&nbsp;</A><H2>Index</H2>
3086<DL>
3087<DT><A HREF="#lbAB">NAME</A><DD>
3088<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
3089<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
3090<DT><A HREF="#lbAE">OPTIONS</A><DD>
3091<DT><A HREF="#lbAF">ARGUMENTS</A><DD>
3092<DT><A HREF="#lbAG">SCRIPT LANGUAGE</A><DD>
3093<DL>
3094<DT><A HREF="#lbAH">GENERAL SYNTAX</A><DD>
3095<DT><A HREF="#lbAI">PREPROCESSING</A><DD>
3096<DT><A HREF="#lbAJ">PREPROCESSOR MACROS</A><DD>
3097<DT><A HREF="#lbAK">VARIABLES</A><DD>
3098<DT><A HREF="#lbAL">STATEMENTS</A><DD>
3099<DT><A HREF="#lbAM">EXPRESSIONS</A><DD>
3100<DT><A HREF="#lbAN">REGULAR EXPRESSION MATCHING</A><DD>
3101<DT><A HREF="#lbAO">PROBES</A><DD>
3102<DT><A HREF="#lbAP">FUNCTIONS</A><DD>
3103<DT><A HREF="#lbAQ">PRINTING</A><DD>
3104<DT><A HREF="#lbAR">STATISTICS</A><DD>
3105<DT><A HREF="#lbAS">TYPECASTING</A><DD>
3106<DT><A HREF="#lbAT">EMBEDDED C</A><DD>
3107<DT><A HREF="#lbAU">BUILT-INS</A><DD>
3108</DL>
3109<DT><A HREF="#lbAV">PROCESSING</A><DD>
3110<DL>
3111<DT><A HREF="#lbAW">ABNORMAL TERMINATION</A><DD>
3112</DL>
3113<DT><A HREF="#lbAX">EXAMPLES</A><DD>
3114<DT><A HREF="#lbAY">CACHING</A><DD>
3115<DT><A HREF="#lbAZ">SAFETY AND SECURITY</A><DD>
3116<DT><A HREF="#lbBA">UNPRIVILEGED USERS</A><DD>
3117<DL>
3118<DT><A HREF="#lbBB">PROBE RESTRICTIONS</A><DD>
3119<DT><A HREF="#lbBC">SCRIPTING LANGUAGE RESTRICTIONS</A><DD>
3120<DT><A HREF="#lbBD">RUNTIME RESTRICTIONS</A><DD>
3121<DT><A HREF="#lbBE">COMMAND LINE OPTION RESTRICTIONS</A><DD>
3122<DT><A HREF="#lbBF">ENVIRONMENT RESTRICTIONS</A><DD>
3123<DT><A HREF="#lbBG">TAPSET RESTRICTIONS</A><DD>
3124</DL>
3125<DT><A HREF="#lbBH">ALTERNATE RUNTIMES</A><DD>
3126<DT><A HREF="#lbBI">EXIT STATUS</A><DD>
3127<DT><A HREF="#lbBJ">DEPRECATION</A><DD>
3128<DT><A HREF="#lbBK">FILES</A><DD>
3129<DT><A HREF="#lbBL">SEE ALSO</A><DD>
3130<DT><A HREF="#lbBM">BUGS</A><DD>
3131</DL>
3132<HR>
3133This document was created by
3134<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
3135using the manual pages.<BR>
3136Time: 17:59:59 GMT, May 16, 2014
3137</BODY>
3138</HTML>
diff --git a/man/stapdyn.8.html b/man/stapdyn.8.html
new file mode 100644
index 00000000..981a3b29
--- /dev/null
+++ b/man/stapdyn.8.html
@@ -0,0 +1,250 @@
1
2<HTML><HEAD><TITLE>Manpage of STAPDYN</TITLE>
3</HEAD><BODY>
4<H1>STAPDYN</H1>
5Section: Maintenance Commands (8)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stapdyn - systemtap dyninst runtime
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>SYNOPSIS</H2>
15
16<P>
17<BR>
18
19<B>stapdyn</B>
20
21[
22<I>OPTIONS</I>
23
24]
25<I>MODULE</I>
26
27[
28<I>MODULE-OPTIONS</I>
29
30]
31<P>
32<A NAME="lbAD">&nbsp;</A>
33<H2>DESCRIPTION</H2>
34
35<P>
36The
37<I>stapdyn</I>
38
39program is the dyninst back-end of the Systemtap tool. It expects a
40shared library produced by the front-end
41<I>stap</I>
42
43tool, when run with
44<I>--dyninst</I>.
45
46<P>
47<P>
48
49Splitting the systemtap tool into a front-end and a back-end allows a
50user to compile a systemtap script on a development machine that has
51the debugging information (need to compile the script) and then
52transfer the resulting shared objevct to a production machine that
53doesn't have any development tools or debugging information installed.
54<P>
55
56Please refer to stappaths (7) for the version number, or run
57rpm -q systemtap (fedora/red hat)
58apt-get -v systemtap (ubuntu)
59<P>
60<A NAME="lbAE">&nbsp;</A>
61<H2>OPTIONS</H2>
62
63The
64<I>stapdyn</I>
65
66program supports the following options. Any other option
67prints a list of supported options.
68<DL COMPACT>
69<DT><B>-v</B>
70
71<DD>
72Verbose mode.
73<DT><B>-V</B>
74
75<DD>
76Print version number and exit.
77<DT><B>-w</B>
78
79<DD>
80Suppress warnings from the script.
81<DT><B>-c CMD</B>
82
83<DD>
84Command CMD will be run and the
85<I>stapdyn</I>
86
87program will exit when CMD
88does. The '_stp_target' variable will contain the pid for CMD.
89<DT><B>-x PID</B>
90
91<DD>
92The '_stp_target' variable will be set to PID.
93<DT><B>-o FILE</B>
94
95<DD>
96Send output to FILE. If the module uses bulk mode, the output will
97be in percpu files FILE_x(FILE_cpux in background and bulk mode)
98where 'x' is the cpu number. This supports <A HREF="strftime.3.html">strftime</A>(3) formats
99for FILE.
100<DT><B>-C WHEN</B>
101
102<DD>
103Control coloring of error messages. WHEN must be either
104
105&quot;never&quot;, &quot;always&quot;, or &quot;auto&quot;
106
107(i.e. enable only if at a terminal). If the option is missing, then &quot;auto&quot;
108is assumed. Colors can be modified using the SYSTEMTAP_COLORS environment
109variable. See the
110<I><A HREF="stap.1.html">stap</A></I>(1)
111
112manual page for more information on syntax and behaviour.
113<DT><B>var1=val</B>
114
115<DD>
116Sets the value of global variable var1 to val. Global variables contained
117within a script are treated as options and can be set from the
118stapdyn command line.
119<P>
120</DL>
121<A NAME="lbAF">&nbsp;</A>
122<H2>ARGUMENTS</H2>
123
124<B>MODULE</B>
125
126is either a module path or a module name. If it is a module name,
127the module will be looked for in the following directory
128(where 'VERSION' is the output of &quot;uname -r&quot;):
129<DL COMPACT>
130<DT><DD>
131/lib/modules/VERSION/systemtap
132</DL>
133<P>
134
135<P>
136 $ stap --dyninst -p4 -m mod1 -e&nbsp;'global var1=&quot;foo&quot;; probe begin{printf(&quot;%s\n&quot;, var1); exit()}'
137<BR>
138
139<P>
140
141Running this with an additional module argument:
142<P>
143
144<P>
145 $ stapdyn mod1.so var1=&quot;HelloWorld&quot;
146<BR>
147
148 HelloWorld
149<P>
150
151Spaces and exclamation marks currently cannot be passed into global variables
152this way.
153<P>
154<A NAME="lbAG">&nbsp;</A>
155<H2>EXAMPLES</H2>
156
157See the
158<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap)
159
160manual page for a collection of sample scripts.
161<P>
162
163Here is a very basic example of how to use
164<I>stapdyn.</I>
165
166First, use
167<I>stap</I>
168
169to compile a script. The
170<I>stap</I>
171
172program will report the pathname to the resulting module.
173<P>
174
175 $ stap --dyninst -p4 -e 'probe begin { printf(&quot;Hello World!\n&quot;); exit() }'
176<BR>
177
178 /home/user/.systemtap/cache/85/stap_8553d83f78c_265.so
179<P>
180
181Run
182<I>stapdyn</I>
183
184with the pathname to the module as an argument.
185<P>
186
187 $ stapdyn /home/user/.systemtap/cache/85/stap_8553d83f78c_265.so
188<BR>
189
190 Hello World!
191<P>
192<A NAME="lbAH">&nbsp;</A>
193<H2>SAFETY AND SECURITY</H2>
194
195Systemtap, in DynInst mode, is a developer tool, and runs completely
196unprivileged. The Linux kernel will only permit one's own processes
197to be accessed, which is enforced by the
198<I><A HREF="ptrace.2.html">ptrace</A></I>(2)
199
200system call.
201See the
202<I><A HREF="stap.1.html">stap</A></I>(1)
203
204manual page for additional information on safety and security.
205<P>
206<A NAME="lbAI">&nbsp;</A>
207<H2>SEE ALSO</H2>
208
209<I><A HREF="stap.1.html">stap</A></I>(1),
210
211<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
212
213<I><A HREF="stap-server.8.html">stap-server</A></I>(8),
214
215<I><A HREF="staprun.8.html">staprun</A></I>(8),
216
217<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap)
218
219<P>
220<A NAME="lbAJ">&nbsp;</A>
221<H2>BUGS</H2>
222
223Use the Bugzilla link of the project web page or our mailing list.
224
225<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>, <B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
226
227
228<P>
229<P>
230
231<HR>
232<A NAME="index">&nbsp;</A><H2>Index</H2>
233<DL>
234<DT><A HREF="#lbAB">NAME</A><DD>
235<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
236<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
237<DT><A HREF="#lbAE">OPTIONS</A><DD>
238<DT><A HREF="#lbAF">ARGUMENTS</A><DD>
239<DT><A HREF="#lbAG">EXAMPLES</A><DD>
240<DT><A HREF="#lbAH">SAFETY AND SECURITY</A><DD>
241<DT><A HREF="#lbAI">SEE ALSO</A><DD>
242<DT><A HREF="#lbAJ">BUGS</A><DD>
243</DL>
244<HR>
245This document was created by
246<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
247using the manual pages.<BR>
248Time: 18:00:00 GMT, May 16, 2014
249</BODY>
250</HTML>
diff --git a/man/stapex.3stap.html b/man/stapex.3stap.html
new file mode 100644
index 00000000..492b878b
--- /dev/null
+++ b/man/stapex.3stap.html
@@ -0,0 +1,246 @@
1
2<HTML><HEAD><TITLE>Manpage of STAPEX</TITLE>
3</HEAD><BODY>
4<H1>STAPEX</H1>
5Section: Misc. Reference Manual Pages (3stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stapex - systemtap examples
12<P>
13
14
15
16<P>
17<A NAME="lbAC">&nbsp;</A>
18<H2>LANGUAGE BASICS</H2>
19
20These examples give a feel for basic systemtap syntax and
21control structures.
22<P>
23
24<P>
25
26<BR>
27
28<DL COMPACT><DT><DD>
29<PRE>
30global odds, evens
31
32probe begin {
33 # &quot;no&quot; and &quot;ne&quot; are local integers
34 for (i=0; i&lt;10; i++) {
35 if (i % 2) odds [no++] = i
36 else evens [ne++] = i
37 }
38 delete odds[2]
39 delete evens[3]
40 exit ()
41}
42
43probe end {
44 foreach (x+ in odds) {
45 printf (&quot;odds[%d] = %d, x, odds[x])
46 }
47 foreach (x in evens-) {
48 printf (&quot;evens[%d] = %d, x, evens[x])
49 }
50}
51
52</PRE>
53
54</DL>
55
56
57<P>
58
59This prints:
60
61<P>
62
63<BR>
64
65<DL COMPACT><DT><DD>
66<PRE>
67odds[1] = 1
68odds[3] = 5
69odds[4] = 7
70odds[5] = 9
71evens[5] = 8
72evens[4] = 6
73evens[2] = 2
74evens[1] = 0
75
76</PRE>
77
78</DL>
79
80
81<P>
82
83Note that all variables types are inferred, and that all locals
84and globals are automatically initialized.
85<P>
86<P>
87
88This script prints the primes between 0 and 49.
89
90<P>
91
92<BR>
93
94<DL COMPACT><DT><DD>
95<PRE>
96function isprime (x) {
97 if (x &lt; 2) return 0
98 for (i=2; i&lt;x; i++) {
99 if (x % i == 0) return 0
100 if (i * i &gt; x) break
101 }
102 return 1
103}
104probe begin {
105 for (i=0; i&lt;50; i++)
106 if (isprime (i)) printf(&quot;%d, i)
107 exit()
108}
109
110</PRE>
111
112</DL>
113
114
115<P>
116
117<P>
118<P>
119
120This script demonstrates recursive functions.
121
122<P>
123
124<BR>
125
126<DL COMPACT><DT><DD>
127<PRE>
128function fibonacci(i) {
129 if (i &lt; 1) error (&quot;bad number&quot;)
130 if (i == 1) return 1
131 if (i == 2) return 2
132 return fibonacci (i-1) + fibonacci (i-2)
133}
134probe begin {
135 printf (&quot;11th fibonacci number: %d, fibonacci (11))
136 exit ()
137}
138
139</PRE>
140
141</DL>
142
143
144<P>
145
146Any larger number may exceed the MAXACTION or MAXNESTING
147limits, and result in an error.
148<P>
149<P>
150<A NAME="lbAD">&nbsp;</A>
151<H2>PROBING</H2>
152
153<P>
154To trace entry and exit from a function, use a pair of probes:
155
156<P>
157
158<BR>
159
160<DL COMPACT><DT><DD>
161<PRE>
162probe kernel.function(&quot;sys_mkdir&quot;) { println (&quot;enter&quot;) }
163probe kernel.function(&quot;sys_mkdir&quot;).return { println (&quot;exit&quot;) }
164
165</PRE>
166
167</DL>
168
169
170<P>
171
172<P>
173To list the probeable functions in the kernel, use the listings mode.
174
175<P>
176
177<BR>
178
179<DL COMPACT><DT><DD>
180<PRE>
181% stap -l 'kernel.function(&quot;*&quot;)'
182
183</PRE>
184
185</DL>
186
187
188<P>
189
190<P>
191To list the probeable functions and local variables in the kernel, use another listings mode.
192
193<P>
194
195<BR>
196
197<DL COMPACT><DT><DD>
198<PRE>
199% stap -L 'kernel.function(&quot;*&quot;)'
200
201</PRE>
202
203</DL>
204
205
206<P>
207
208<P>
209<A NAME="lbAE">&nbsp;</A>
210<H2>MORE EXAMPLES</H2>
211
212<P>
213The directory to find more examples can be found in the stappaths (7) manual page,
214and online at
215
216<B><A HREF="http://sourceware.org/systemtap/examples/">http://sourceware.org/systemtap/examples/</A></B>
217
218
219<P>
220<A NAME="lbAF">&nbsp;</A>
221<H2>SEE ALSO</H2>
222
223
224<PRE>
225<I><A HREF="stap.1.html">stap</A></I>(1)
226<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap)
227<I><A HREF="stappaths.7.html">stappaths</A></I>(7)
228
229
230</PRE>
231<HR>
232<A NAME="index">&nbsp;</A><H2>Index</H2>
233<DL>
234<DT><A HREF="#lbAB">NAME</A><DD>
235<DT><A HREF="#lbAC">LANGUAGE BASICS</A><DD>
236<DT><A HREF="#lbAD">PROBING</A><DD>
237<DT><A HREF="#lbAE">MORE EXAMPLES</A><DD>
238<DT><A HREF="#lbAF">SEE ALSO</A><DD>
239</DL>
240<HR>
241This document was created by
242<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
243using the manual pages.<BR>
244Time: 17:59:59 GMT, May 16, 2014
245</BODY>
246</HTML>
diff --git a/man/stapfuncs.3stap.html b/man/stapfuncs.3stap.html
new file mode 100644
index 00000000..25f50521
--- /dev/null
+++ b/man/stapfuncs.3stap.html
@@ -0,0 +1,54 @@
1
2<HTML><HEAD><TITLE>Manpage of STAPFUNCS</TITLE>
3</HEAD><BODY>
4<H1>STAPFUNCS</H1>
5Section: Misc. Reference Manual Pages (3stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stapfuncs - systemtap functions
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>DESCRIPTION</H2>
15
16Functions in the standard systemtap tapset are individually documented
17in the
18<I>3stap</I>
19
20manual section, with the
21<I>function::</I>
22
23prefix. Some built-in functions such as
24<I>printf</I>
25
26are documented on the
27<I><A HREF="stap.1.html">stap</A></I>(1)
28
29man page.
30<P>
31<A NAME="lbAD">&nbsp;</A>
32<H2>SEE ALSO</H2>
33
34
35<PRE>
36<I><A HREF="stap.1.html">stap</A></I>(1),
37<I>function::*</I>(3stap),
38<I>tapset::*</I>(3stap)
39
40</PRE>
41<HR>
42<A NAME="index">&nbsp;</A><H2>Index</H2>
43<DL>
44<DT><A HREF="#lbAB">NAME</A><DD>
45<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
46<DT><A HREF="#lbAD">SEE ALSO</A><DD>
47</DL>
48<HR>
49This document was created by
50<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
51using the manual pages.<BR>
52Time: 17:59:59 GMT, May 16, 2014
53</BODY>
54</HTML>
diff --git a/man/stappaths.7.html b/man/stappaths.7.html
new file mode 100644
index 00000000..4310b7c4
--- /dev/null
+++ b/man/stappaths.7.html
@@ -0,0 +1,182 @@
1
2<HTML><HEAD><TITLE>Manpage of STAP</TITLE>
3</HEAD><BODY>
4<H1>STAP</H1>
5Section: Environments, Tables, and Troff Macros (7)<BR>Updated: Systemtap Team<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11<P>
12stappaths - systemtap configurable file paths
13<P>
14<P>
15
16
17
18<P>
19<A NAME="lbAC">&nbsp;</A>
20<H2>DESCRIPTION</H2>
21
22This manual page was generated on 2014-05-16 for systemtap 2.6.
23The following section will list the main paths in systemtap that are
24important to know and may be required to reference.
25<DL COMPACT>
26<DT>share/systemtap/tapset/<DD>
27The directory for the standard probe-alias / function tapset library,
28unless overridden by the
29<I>SYSTEMTAP_TAPSET</I>
30
31environment variable or the
32<I>XDG_DATA_DIRS</I>
33
34environment variable.
35These are described in the
36<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
37
38<I>probe::*</I>(3stap),
39
40and
41<I>function::*</I>(3stap)
42
43manual pages.
44<DT>share/systemtap/runtime/<DD>
45The runtime sources, unless overridden by the
46<I>SYSTEMTAP_RUNTIME</I>
47
48environment variable.
49<DT>bin/staprun<DD>
50The auxiliary program supervising module loading, interaction, and
51unloading.
52<DT>${exec_prefix}/libexec/systemtap/stapio<DD>
53The auxiliary program for module input and output handling.
54<DT>/usr/include/sys/sdt.h<DD>
55Location of the &lt;<A HREF="file:///usr/include/sys/sdt.h">sys/sdt.h</A>&gt; headers.
56<DT>Kernel debuginfo Path: /usr/lib/debug/lib/modules/$(uname -r)/<DD>
57The location of kernel debugging information when packaged into the
58<I>kernel-debuginfo</I>
59
60RPM, unless overridden by the
61<I>SYSTEMTAP_DEBUGINFO_PATH</I>
62
63environment variable. The default value for this variable is
64<I>+:.debug:/usr/lib/debug:build</I>.
65
66elfutils searches vmlinux in this path and it interprets the path as a base
67directory of which various subdirectories will be searched for finding debuginfo
68for the kernel, kernel modules, and user-space binaries.
69By default, systemtap will also look for vmlinux in these locations:
70<P>
71
72<BR>
73
74<DL COMPACT><DT><DD>
75<PRE>
76/boot/vmlinux-`uname -r`
77/lib/modules/`uname -r`/vmlinux
78/lib/modules/`uname -r`/vmlinux.debug
79/lib/modules/`uname -r`/build/vmlinux
80/lib/modules/`uname -r`/.debug/vmlinux.debug
81/usr/lib/debug/lib/modules/`uname -r`/vmlinux.debug
82/var/cache/abrt-di/usr/debug/lib/modules/`uname -r`/
83/var/cache/abrt-di/usr/lib/debug/lib/modules/`uname -r`/vmlinux.debug
84
85
86</PRE>
87
88</DL>
89
90
91<DT><DD>
92<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
93Corresponding source files are usually located under /usr/src/debug/.
94Further file information on user-space applications can be determined per-basis using
95rpm -ql &lt;package&gt;-debuginfo. For supported user-space applications information please
96visit the systemtap wiki.
97<DT>$HOME/.systemtap<DD>
98Systemtap data directory for cached systemtap files, unless overridden
99by the
100<I>SYSTEMTAP_DIR</I>
101
102environment variable.
103<DT>/tmp/stapXXXXXX<DD>
104Temporary directory for systemtap files, including translated C code
105and kernel object.
106<DT>/lib/modules/VERSION/build<DD>
107The location of kernel module building infrastructure.
108<DT>share/doc/systemtap*/examples<DD>
109Examples with greater detail can be found here. Each example comes with a .txt
110or .meta file explaining what the example, sample or demo does and how it is
111ordinarily run.
112<DT>$SYSTEMTAP_DIR/ssl/server<DD>
113User's server-side SSL certificate database. If SYSTEMTAP_DIR is not
114set, the default is $HOME/.systemtap.
115<DT>$SYSTEMTAP_DIR/ssl/client<DD>
116User's private client-side SSL certificate database. If SYSTEMTAP_DIR is not
117set, the default is $HOME/.systemtap.
118<DT>${prefix}/etc/systemtap/ssl/client<DD>
119Global client-side SSL certificate database.
120<DT>${prefix}/etc/systemtap/staprun/<DD>
121<I>staprun</I>'s trusted signer certificate database.
122<DT>${prefix}/etc/sysconfig/stap-server/<DD>
123stap-server service global configuration file.
124<DT>${prefix}/etc/stap-server/conf.d/*.conf<DD>
125stap-server service configuration files for default servers.
126<DT>/var/run/stap-server/<DD>
127stap-server service default location of status files for running servers.
128<DT>/var/log/stap-server/log<DD>
129stap-server service default log file.
130<P>
131<P>
132</DL>
133<P>
134
135<A NAME="lbAD">&nbsp;</A>
136<H2>FILES</H2>
137
138
139<I>share/systemtap/tapset</I>
140
141
142<P>
143<A NAME="lbAE">&nbsp;</A>
144<H2>SEE ALSO</H2>
145
146
147<PRE>
148<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
149<I><A HREF="staprun.8.html">staprun</A></I>(8),
150<I><A HREF="stapvars.3stap.html">stapvars</A></I>(3stap),
151<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap),
152<I><A HREF="stap-server.8.html">stap-server</A></I>(8),
153<I><A HREF="awk.1.html">awk</A></I>(1),
154<I><A HREF="gdb.1.html">gdb</A></I>(1)
155
156
157</PRE><A NAME="lbAF">&nbsp;</A>
158<H2>BUGS</H2>
159
160Use the Bugzilla link of the project web page or our mailing list.
161
162<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>,<B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
163
164
165<P>
166
167<HR>
168<A NAME="index">&nbsp;</A><H2>Index</H2>
169<DL>
170<DT><A HREF="#lbAB">NAME</A><DD>
171<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
172<DT><A HREF="#lbAD">FILES</A><DD>
173<DT><A HREF="#lbAE">SEE ALSO</A><DD>
174<DT><A HREF="#lbAF">BUGS</A><DD>
175</DL>
176<HR>
177This document was created by
178<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
179using the manual pages.<BR>
180Time: 18:00:00 GMT, May 16, 2014
181</BODY>
182</HTML>
diff --git a/man/stapprobes.3stap.html b/man/stapprobes.3stap.html
new file mode 100644
index 00000000..042f2269
--- /dev/null
+++ b/man/stapprobes.3stap.html
@@ -0,0 +1,2023 @@
1
2<HTML><HEAD><TITLE>Manpage of STAPPROBES</TITLE>
3</HEAD><BODY>
4<H1>STAPPROBES</H1>
5Section: Misc. Reference Manual Pages (3stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stapprobes - systemtap probe points
12<P>
13
14
15
16<P>
17<A NAME="lbAC">&nbsp;</A>
18<H2>DESCRIPTION</H2>
19
20The following sections enumerate the variety of probe points supported
21by the systemtap translator, and some of the additional aliases defined by
22standard tapset scripts. Many are individually documented in the
23<I>3stap</I>
24
25manual section, with the
26<I>probe::</I>
27
28prefix.
29<P>
30<A NAME="lbAD">&nbsp;</A>
31<H2>SYNTAX</H2>
32
33<P>
34<P>
35
36
37<P>
38
39<BR>
40
41<DL COMPACT><DT><DD>
42<PRE>
43<B>probe</B> PROBEPOINT [<B>,</B> PROBEPOINT] <B>{</B> [STMT ...] <B>}</B>
44
45</PRE>
46
47</DL>
48
49
50<P>
51
52<P>
53
54A probe declaration may list multiple comma-separated probe points in
55order to attach a handler to all of the named events. Normally, the
56handler statements are run whenever any of events occur.
57<P>
58
59The syntax of a single probe point is a general dotted-symbol
60sequence. This allows a breakdown of the event namespace into parts,
61somewhat like the Domain Name System does on the Internet. Each
62component identifier may be parametrized by a string or number
63literal, with a syntax like a function call. A component may include
64a &quot;*&quot; character, to expand to a set of matching probe points. It may
65also include &quot;**&quot; to match multiple sequential components at once.
66Probe aliases likewise expand to other probe points.
67<P>
68
69Probe aliases can be given on their own, or with a suffix. The suffix
70attaches to the underlying probe point that the alias is expanded
71to. For example,
72
73<P>
74
75<BR>
76
77<DL COMPACT><DT><DD>
78<PRE>
79syscall.read.return.maxactive(10)
80
81</PRE>
82
83</DL>
84
85
86<P>
87
88expands to
89
90<P>
91
92<BR>
93
94<DL COMPACT><DT><DD>
95<PRE>
96kernel.function(&quot;sys_read&quot;).return.maxactive(10)
97
98</PRE>
99
100</DL>
101
102
103<P>
104
105with the component
106<I>maxactive(10)</I>
107
108being recognized as a suffix.
109<P>
110
111Normally, each and every probe point resulting from wildcard- and
112alias-expansion must be resolved to some low-level system
113instrumentation facility (e.g., a kprobe address, marker, or a timer
114configuration), otherwise the elaboration phase will fail.
115<P>
116
117However, a probe point may be followed by a &quot;?&quot; character, to indicate
118that it is optional, and that no error should result if it fails to
119resolve. Optionalness passes down through all levels of
120alias/wildcard expansion. Alternately, a probe point may be followed
121by a &quot;!&quot; character, to indicate that it is both optional and
122sufficient. (Think vaguely of the Prolog cut operator.) If it does
123resolve, then no further probe points in the same comma-separated list
124will be resolved. Therefore, the &quot;!&quot; sufficiency mark only makes
125sense in a list of probe point alternatives.
126<P>
127
128Additionally, a probe point may be followed by a &quot;if (expr)&quot; statement, in
129order to enable/disable the probe point on-the-fly. With the &quot;if&quot; statement,
130if the &quot;expr&quot; is false when the probe point is hit, the whole probe body
131including alias's body is skipped. The condition is stacked up through
132all levels of alias/wildcard expansion. So the final condition becomes
133the logical-and of conditions of all expanded alias/wildcard. The expressions
134are necessarily restricted to global variables.
135<P>
136
137These are all
138<B>syntactically</B>
139
140valid probe points. (They are generally
141<B>semantically</B>
142
143invalid, depending on the contents of the tapsets, and the versions of
144kernel/user software installed.)
145<P>
146
147<P>
148
149<BR>
150
151<DL COMPACT><DT><DD>
152<PRE>
153kernel.function(&quot;foo&quot;).return
154process(&quot;/bin/vi&quot;).statement(0x2222)
155end
156syscall.*
157syscall.*.return.maxactive(10)
158sys**open
159kernel.function(&quot;no_such_function&quot;) ?
160module(&quot;awol&quot;).function(&quot;no_such_function&quot;) !
161signal.*? if (switch)
162kprobe.function(&quot;foo&quot;)
163
164</PRE>
165
166</DL>
167
168
169<P>
170
171<P>
172Probes may be broadly classified into &quot;synchronous&quot; and
173&quot;asynchronous&quot;. A &quot;synchronous&quot; event is deemed to occur when any
174processor executes an instruction matched by the specification. This
175gives these probes a reference point (instruction address) from which
176more contextual data may be available. Other families of probe points
177refer to &quot;asynchronous&quot; events such as timers/counters rolling over,
178where there is no fixed reference point that is related. Each probe
179point specification may match multiple locations (for example, using
180wildcards or aliases), and all them are then probed. A probe
181declaration may also contain several comma-separated specifications,
182all of which are probed.
183<P>
184<A NAME="lbAE">&nbsp;</A>
185<H2>DWARF DEBUGINFO</H2>
186
187<P>
188Resolving some probe points requires DWARF debuginfo or &quot;debug
189symbols&quot; for the specific part being instrumented. For some others,
190DWARF is automatically synthesized on the fly from source code header
191files. For others, it is not needed at all. Since a systemtap script
192may use any mixture of probe points together, the union of their DWARF
193requirements has to be met on the computer where script compilation
194occurs. (See the <I>--use-server</I> option and the <B><A HREF="stap-server.8.html">stap-server</A>(8)</B> man page for information about the remote compilation facility,
195which allows these requirements to be met on a different machine.)
196<P>
197
198The following point lists many of the available probe point families,
199to classify them with respect to their need for DWARF debuginfo.
200<P>
201<TABLE>
202<TR VALIGN=top><TD><B>DWARF</B></TD><TD>NON-DWARF</TD><TD><BR></TD></TR>
203<TR VALIGN=top><TD></TD><TD></TD><TD><BR></TD></TR>
204<TR VALIGN=top><TD>kernel.function, .statement</TD><TD>kernel.mark</TD><TD><BR></TD></TR>
205<TR VALIGN=top><TD>module.function, .statement</TD><TD>process.mark, process.plt</TD><TD><BR></TD></TR>
206<TR VALIGN=top><TD>process.function, .statement</TD><TD>begin, end, error, never</TD><TD><BR></TD></TR>
207<TR VALIGN=top><TD>process.mark <I>(backup)</I></TD><TD>timer</TD><TD><BR></TD></TR>
208<TR VALIGN=top><TD></TD><TD>perf</TD><TD><BR></TD></TR>
209<TR VALIGN=top><TD></TD><TD>procfs</TD><TD><BR></TD></TR>
210<TR VALIGN=top><TD><B>AUTO-DWARF</B></TD><TD>kernel.statement.absolute</TD><TD><BR></TD></TR>
211<TR VALIGN=top><TD></TD><TD>kernel.data</TD><TD><BR></TD></TR>
212<TR VALIGN=top><TD>kernel.trace</TD><TD>kprobe.function</TD><TD><BR></TD></TR>
213<TR VALIGN=top><TD></TD><TD>process.statement.absolute</TD><TD><BR></TD></TR>
214<TR VALIGN=top><TD></TD><TD>process.begin, .end, .error</TD><TD><BR></TD></TR>
215</TABLE>
216
217<P>
218<A NAME="lbAF">&nbsp;</A>
219<H2>PROBE POINT FAMILIES</H2>
220
221<P>
222<A NAME="lbAG">&nbsp;</A>
223<H3>BEGIN/END/ERROR</H3>
224
225<P>
226The probe points
227<I>begin</I> and <I>end</I>
228
229are defined by the translator to refer to the time of session startup
230and shutdown. All &quot;begin&quot; probe handlers are run, in some sequence,
231during the startup of the session. All global variables will have
232been initialized prior to this point. All &quot;end&quot; probes are run, in
233some sequence, during the
234<I>normal</I>
235
236shutdown of a session, such as in the aftermath of an
237<I>exit ()</I>
238
239function call, or an interruption from the user. In the case of an
240error-triggered shutdown, &quot;end&quot; probes are not run. There are no
241target variables available in either context.
242<P>
243
244If the order of execution among &quot;begin&quot; or &quot;end&quot; probes is significant,
245then an optional sequence number may be provided:
246<P>
247
248<P>
249
250<BR>
251
252<DL COMPACT><DT><DD>
253<PRE>
254begin(N)
255end(N)
256
257</PRE>
258
259</DL>
260
261
262<P>
263
264<P>
265The number N may be positive or negative. The probe handlers are run in
266increasing order, and the order between handlers with the same sequence
267number is unspecified. When &quot;begin&quot; or &quot;end&quot; are given without a
268sequence, they are effectively sequence zero.
269<P>
270The
271<I>error</I>
272
273probe point is similar to the
274<I>end</I>
275
276probe, except that each such probe handler run when the session ends
277after errors have occurred. In such cases, &quot;end&quot; probes are skipped,
278but each &quot;error&quot; probe is still attempted. This kind of probe can be
279used to clean up or emit a &quot;final gasp&quot;. It may also be numerically
280parametrized to set a sequence.
281<P>
282<A NAME="lbAH">&nbsp;</A>
283<H3>NEVER</H3>
284
285The probe point
286<I>never</I>
287
288is specially defined by the translator to mean &quot;never&quot;. Its probe
289handler is never run, though its statements are analyzed for symbol /
290type correctness as usual. This probe point may be useful in
291conjunction with optional probes.
292<P>
293<A NAME="lbAI">&nbsp;</A>
294<H3>SYSCALL and ND_SYSCALL</H3>
295
296<P>
297The
298<I>syscall.*</I> and <I>nd_syscall.*</I>
299
300aliases define several hundred probes, too many to
301detail here. They are of the general form:
302<P>
303
304<P>
305
306<BR>
307
308<DL COMPACT><DT><DD>
309<PRE>
310syscall.NAME
311<BR>
312nd_syscall.NAME
313<BR>
314syscall.NAME.return
315<BR>
316nd_syscall.NAME.return
317
318</PRE>
319
320</DL>
321
322
323<P>
324
325<P>
326Generally, a pair of probes are defined for each normal system call as listed in the
327<I><A HREF="syscalls.2.html">syscalls</A>(2)</I>
328
329manual page, one for entry and one for return. Those system calls that never
330return do not have a corresponding
331<I>.return</I>
332
333probe. The nd_* family of probes are about the same, except it uses
334<B>non-DWARF</B>
335
336based searching mechanisms, which may result in a lower quality of symbolic
337context data (parameters), and may miss some system calls. You may want to
338try them first, in case kernel debugging information is not immediately available.
339<P>
340
341Each probe alias provides a variety of variables. Looking at the tapset source
342code is the most reliable way. Generally, each variable listed in the standard
343manual page is made available as a script-level variable, so
344<I>syscall.open</I>
345
346exposes
347<I>filename</I>, <I>flags</I>, and <I>mode</I>.
348
349In addition, a standard suite of variables is available at most aliases:
350<DL COMPACT>
351<DT><I>argstr</I>
352
353<DD>
354A pretty-printed form of the entire argument list, without parentheses.
355<DT><I>name</I>
356
357<DD>
358The name of the system call.
359<DT><I>retstr</I>
360
361<DD>
362For return probes, a pretty-printed form of the system-call result.
363</DL>
364<P>
365
366As usual for probe aliases, these variables are all simply initialized
367once from the underlying $context variables, so that later changes to
368$context variables are not automatically reflected. Not all probe
369aliases obey all of these general guidelines. Please report any
370bothersome ones you encounter as a bug.
371<P>
372
373If debuginfo availability is a problem, you may try using the
374non-DWARF syscall probe aliases instead. Use the
375<I>nd_syscall.</I>
376
377prefix instead of
378<I>syscall.</I>
379
380The same context variables are available, as far as possible.
381<P>
382<A NAME="lbAJ">&nbsp;</A>
383<H3>TIMERS</H3>
384
385<P>
386Intervals defined by the standard kernel &quot;jiffies&quot; timer may be used
387to trigger probe handlers asynchronously. Two probe point variants
388are supported by the translator:
389<P>
390
391<P>
392
393<BR>
394
395<DL COMPACT><DT><DD>
396<PRE>
397timer.jiffies(N)
398timer.jiffies(N).randomize(M)
399
400</PRE>
401
402</DL>
403
404
405<P>
406
407<P>
408The probe handler is run every N jiffies (a kernel-defined unit of
409time, typically between 1 and 60 ms). If the &quot;randomize&quot; component is
410given, a linearly distributed random value in the range [-M..+M] is
411added to N every time the handler is run. N is restricted to a
412reasonable range (1 to around a million), and M is restricted to be
413smaller than N. There are no target variables provided in either
414context. It is possible for such probes to be run concurrently on
415a multi-processor computer.
416<P>
417
418Alternatively, intervals may be specified in units of time.
419There are two probe point variants similar to the jiffies timer:
420<P>
421
422<P>
423
424<BR>
425
426<DL COMPACT><DT><DD>
427<PRE>
428timer.ms(N)
429timer.ms(N).randomize(M)
430
431</PRE>
432
433</DL>
434
435
436<P>
437
438<P>
439Here, N and M are specified in milliseconds, but the full options for units
440are seconds (s/sec), milliseconds (ms/msec), microseconds (us/usec),
441nanoseconds (ns/nsec), and hertz (hz). Randomization is not supported for
442hertz timers.
443<P>
444The actual resolution of the timers depends on the target kernel. For
445kernels prior to 2.6.17, timers are limited to jiffies resolution, so
446intervals are rounded up to the nearest jiffies interval. After 2.6.17,
447the implementation uses hrtimers for tighter precision, though the actual
448resolution will be arch-dependent. In either case, if the &quot;randomize&quot;
449component is given, then the random value will be added to the interval
450before any rounding occurs.
451<P>
452
453Profiling timers are also available to provide probes that execute on
454all CPUs at the rate of the system tick (CONFIG_HZ). This probe takes
455no parameters. On some kernels, this is a one-concurrent-user-only or
456disabled facility, resulting in error -16 (EBUSY) during probe
457registration.
458<P>
459
460<P>
461
462<BR>
463
464<DL COMPACT><DT><DD>
465<PRE>
466timer.profile.tick
467
468</PRE>
469
470</DL>
471
472
473<P>
474
475<P>
476Full context information of the interrupted process is available, making
477this probe suitable for a time-based sampling profiler.
478<P>
479
480It is recommended to use the tapset probe
481<I>timer.profile</I>
482
483rather than timer.profile.tick. This probe point behaves identically
484to timer.profile.tick when the underlying functionality is available,
485and falls back to using perf.sw.cpu_clock on some recent kernels which
486lack the corresponding profile timer facility.
487<P>
488<A NAME="lbAK">&nbsp;</A>
489<H3>DWARF</H3>
490
491<P>
492This family of probe points uses symbolic debugging information for
493the target kernel/module/program, as may be found in unstripped
494executables, or the separate
495<I>debuginfo</I>
496
497packages. They allow placement of probes logically into the execution
498path of the target program, by specifying a set of points in the
499source or object code. When a matching statement executes on any
500processor, the probe handler is run in that context.
501<P>
502
503Probe points in the DWARF family can be identified by the target kernel
504module (or user process), source file, line number, function name, or
505some combination of these.
506<P>
507
508Here is a list of DWARF probe points currently supported:
509
510<P>
511
512<BR>
513
514<DL COMPACT><DT><DD>
515<PRE>
516kernel.function(PATTERN)
517kernel.function(PATTERN).call
518kernel.function(PATTERN).callee(PATTERN)
519kernel.function(PATTERN).callees(DEPTH)
520kernel.function(PATTERN).return
521kernel.function(PATTERN).inline
522kernel.function(PATTERN).label(LPATTERN)
523module(MPATTERN).function(PATTERN)
524module(MPATTERN).function(PATTERN).call
525module(MPATTERN).function(PATTERN).callee(PATTERN)
526module(MPATTERN).function(PATTERN).callees(DEPTH)
527module(MPATTERN).function(PATTERN).return
528module(MPATTERN).function(PATTERN).inline
529module(MPATTERN).function(PATTERN).label(LPATTERN)
530kernel.statement(PATTERN)
531kernel.statement(ADDRESS).absolute
532module(MPATTERN).statement(PATTERN)
533process(&quot;PATH&quot;).function(&quot;NAME&quot;)
534process(&quot;PATH&quot;).statement(&quot;*@FILE.c:123&quot;)
535process(&quot;PATH&quot;).library(&quot;PATH&quot;).function(&quot;NAME&quot;)
536process(&quot;PATH&quot;).library(&quot;PATH&quot;).statement(&quot;*@FILE.c:123&quot;)
537process(&quot;PATH&quot;).function(&quot;*&quot;).return
538process(&quot;PATH&quot;).function(&quot;myfun&quot;).label(&quot;foo&quot;)
539process(&quot;PATH&quot;).function(&quot;foo&quot;).callee(&quot;bar&quot;)
540process(&quot;PATH&quot;).function(&quot;foo&quot;).callees(DEPTH)
541process(PID).statement(ADDRESS).absolute
542
543</PRE>
544
545</DL>
546
547
548<P>
549
550(See the USER-SPACE section below for more information on the process
551probes.)
552<P>
553
554The list above includes multiple variants and modifiers which provide
555additional functionality or filters. They are:
556<DL COMPACT><DT><DD>
557<DL COMPACT>
558<DT><B>.function</B><DD>
559Places a probe near the beginning of the named function, so that
560parameters are available as context variables.
561<DT><B>.return</B><DD>
562Places a probe at the moment <B>after</B> the return from the named
563function, so the return value is available as the &quot;$return&quot; context
564variable.
565<DT><B>.inline</B><DD>
566Filters the results to include only instances of inlined functions. Note
567that inlined functions do not have an identifiable return point, so
568<B>.return</B> is not supported on <B>.inline</B> probes.
569<DT><B>.call</B><DD>
570Filters the results to include only non-inlined functions (the opposite
571set of <B>.inline</B>)
572<DT><B>.exported</B><DD>
573Filters the results to include only exported functions.
574<DT><B>.statement</B><DD>
575Places a probe at the exact spot, exposing those local variables that
576are visible there.
577<DT><B>.callee</B><DD>
578Places a probe on the callee function given in the <B>.callee</B>
579modifier, where the callee must be a function called by the target
580function given in <B>.function</B>. The advantage of doing this over
581directly probing the callee function is that this probe point is run
582only when the callee is called from the target function (add the
583-DSTAP_CALLEE_MATCHALL directive to override this when calling
584<B><A HREF="stap.1.html">stap</A></B>(1)).
585<P>
586Note that only callees that can be statically determined are available.
587For example, calls through function pointers are not available.
588Additionally, calls to functions located in other objects (e.g.
589libraries) are not available (instead use another probe point). This
590feature will only work for code compiled with GCC 4.7+.
591<DT><B>.callees</B><DD>
592Shortcut for <B>.callee(&quot;*&quot;)</B>, which places a probe on all callees of
593the function.
594<DT><B>.callees</B>(DEPTH)<DD>
595Recursively places probes on callees. For example, <B><A HREF=".callees.2.html">.callees</A>(2)</B>
596will probe both callees of the target function, as well as callees of
597those callees. And <B><A HREF=".callees.3.html">.callees</A>(3)</B> goes one level deeper, etc...
598A callee probe at depth N is only triggered when the N callers in the
599callstack match those that were statically determined during analysis
600(this also may be overriden using -DSTAP_CALLEE_MATCHALL).
601</DL>
602</DL>
603
604<P>
605
606In the above list of probe points, MPATTERN stands for a string literal
607that aims to identify the loaded kernel module of interest and LPATTERN
608stands for a source program label. Both MPATTERN and LPATTERN may
609include the &quot;*&quot; &quot;[]&quot;, and &quot;?&quot; wildcards.
610PATTERN stands for a string literal that
611aims to identify a point in the program. It is made up of three
612parts:
613<DL COMPACT>
614<DT>&bull;<DD>
615The first part is the name of a function, as would appear in the
616<I>nm</I>
617
618program's output. This part may use the &quot;*&quot; and &quot;?&quot; wildcarding
619operators to match multiple names.
620<DT>&bull;<DD>
621The second part is optional and begins with the &quot;@&quot; character.
622It is followed by the path to the source file containing the function,
623which may include a wildcard pattern, such as mm/slab*.
624If it does not match as is, an implicit &quot;*/&quot; is optionally added
625<I>before</I>
626
627the pattern, so that a script need only name the last few components
628of a possibly long source directory path.
629<DT>&bull;<DD>
630Finally, the third part is optional if the file name part was given,
631and identifies the line number in the source file preceded by a &quot;:&quot;
632or a &quot;+&quot;. The line number is assumed to be an
633absolute line number if preceded by a &quot;:&quot;, or relative to the entry of
634the function if preceded by a &quot;+&quot;.
635All the lines in the function can be matched with &quot;:*&quot;.
636A range of lines x through y can be matched with &quot;:x-y&quot;.
637</DL>
638<P>
639
640As an alternative, PATTERN may be a numeric constant, indicating an
641address. Such an address may be found from symbol tables of the
642appropriate kernel / module object file. It is verified against
643known statement code boundaries, and will be relocated for use at
644run time.
645<P>
646
647In guru mode only, absolute kernel-space addresses may be specified with
648the &quot;.absolute&quot; suffix. Such an address is considered already relocated,
649as if it came from
650<B>/proc/kallsyms</B>,
651
652so it cannot be checked against statement/instruction boundaries.
653<A NAME="lbAL">&nbsp;</A>
654<H3>CONTEXT VARIABLES</H3>
655
656<P>
657<P>
658
659Many of the source-level context variables, such as function parameters,
660locals, globals visible in the compilation unit, may be visible to
661probe handlers. They may refer to these variables by prefixing their
662name with &quot;$&quot; within the scripts. In addition, a special syntax
663allows limited traversal of structures, pointers, and arrays. More
664syntax allows pretty-printing of individual variables or their groups.
665See also
666<B>@cast</B>.
667
668Note that variables may be inaccessible due to them being paged out,
669or for a few other reasons. See also man
670<I><A HREF="./error::fault.7stap.html">error::fault</A></I>(7stap).
671
672<P>
673<DL COMPACT>
674<DT>$var<DD>
675refers to an in-scope variable &quot;var&quot;. If it's an integer-like type,
676it will be cast to a 64-bit int for systemtap script use. String-like
677pointers (char *) may be copied to systemtap string values using the
678<I>kernel_string</I> or <I>user_string</I>
679
680functions.
681<DT>@var(&quot;varname&quot;)<DD>
682an alternative syntax for
683<I>$varname</I>
684
685<DT>@var(&quot;varname@src/file.c&quot;)<DD>
686refers to the global (either file local or external) variable
687<I>varname</I>
688
689defined when the file
690<I>src/file.c</I>
691
692was compiled. The CU in which the variable is resolved is the first CU
693in the module of the probe point which matches the given file name at
694the end and has the shortest file name path (e.g. given
695<I>@var(foo@bar/baz.c)</I>
696
697and CUs with file name paths
698<I>src/sub/module/bar/baz.c</I>
699
700and
701<I>src/bar/baz.c</I>
702
703the second CU will be chosen to resolve the (file) global variable
704<I>foo</I>
705
706<DT>$var-&gt;field traversal via a structure's or a pointer's field. This<DD>
707generalized indirection operator may be repeated to follow more
708levels. Note that the
709<I>.</I>
710
711operator is not used for plain structure
712members, only
713<I>-&gt;</I>
714
715for both purposes. (This is because &quot;.&quot; is reserved for string
716concatenation.)
717<DT>$return<DD>
718is available in return probes only for functions that are declared
719with a return value, which can be determined using @defined($return).
720<DT>$var[N]<DD>
721indexes into an array. The index given with a literal number or even
722an arbitrary numeric expression.
723</DL>
724<P>
725
726A number of operators exist for such basic context variable expressions:
727<DL COMPACT>
728<DT>$$vars<DD>
729expands to a character string that is equivalent to
730
731<P>
732
733<BR>
734
735<DL COMPACT><DT><DD>
736<PRE>
737sprintf(&quot;parm1=%x ... parmN=%x var1=%x ... varN=%x&quot;,
738 parm1, ..., parmN, var1, ..., varN)
739
740</PRE>
741
742</DL>
743
744
745<P>
746
747for each variable in scope at the probe point. Some values may be
748printed as
749<I>=?</I>
750
751if their run-time location cannot be found.
752<DT>$$locals<DD>
753expands to a subset of $$vars for only local variables.
754<DT>$$parms<DD>
755expands to a subset of $$vars for only function parameters.
756<DT>$$return<DD>
757is available in return probes only. It expands to a string that
758is equivalent to sprintf(&quot;return=%x&quot;, $return)
759if the probed function has a return value, or else an empty string.
760<DT>&amp; $EXPR<DD>
761expands to the address of the given context variable expression, if it
762is addressable.
763<DT>@defined($EXPR)<DD>
764expands to 1 or 0 iff the given context variable expression is resolvable,
765for use in conditionals such as
766
767<P>
768
769<BR>
770
771<DL COMPACT><DT><DD>
772<PRE>
773@defined($foo-&gt;bar) ? $foo-&gt;bar : 0
774
775</PRE>
776
777</DL>
778
779
780<P>
781
782<DT>$EXPR$<DD>
783expands to a string with all of $EXPR's members, equivalent to
784
785<P>
786
787<BR>
788
789<DL COMPACT><DT><DD>
790<PRE>
791sprintf(&quot;{.a=%i, .b=%u, .c={...}, .d=[...]}&quot;,
792 $EXPR-&gt;a, $EXPR-&gt;b)
793
794</PRE>
795
796</DL>
797
798
799<P>
800
801<DT>$EXPR$$<DD>
802expands to a string with all of $var's members and submembers, equivalent to
803
804<P>
805
806<BR>
807
808<DL COMPACT><DT><DD>
809<PRE>
810sprintf(&quot;{.a=%i, .b=%u, .c={.x=%p, .y=%c}, .d=[%i, ...]}&quot;,
811 $EXPR-&gt;a, $EXPR-&gt;b, $EXPR-&gt;c-&gt;x, $EXPR-&gt;c-&gt;y, $EXPR-&gt;d[0])
812
813</PRE>
814
815</DL>
816
817
818<P>
819
820<P>
821</DL>
822<A NAME="lbAM">&nbsp;</A>
823<H3>MORE ON RETURN PROBES</H3>
824
825<P>
826<P>
827
828For the kernel &quot;.return&quot; probes, only a certain fixed number of
829returns may be outstanding. The default is a relatively small number,
830on the order of a few times the number of physical CPUs. If many
831different threads concurrently call the same blocking function, such
832as <A HREF="futex.2.html">futex</A>(2) or <A HREF="read.2.html">read</A>(2), this limit could be exceeded, and skipped
833&quot;kretprobes&quot; would be reported by &quot;stap -t&quot;. To work around this,
834specify a
835
836<P>
837
838<BR>
839
840<DL COMPACT><DT><DD>
841<PRE>
842probe FOO.return.maxactive(NNN)
843
844</PRE>
845
846</DL>
847
848
849<P>
850
851suffix, with a large enough NNN to cover all expected concurrently blocked
852threads. Alternately, use the
853
854<P>
855
856<BR>
857
858<DL COMPACT><DT><DD>
859<PRE>
860stap -DKRETACTIVE=NNNN
861
862</PRE>
863
864</DL>
865
866
867<P>
868
869stap command line macro setting to override the default for all
870&quot;.return&quot; probes.
871<P>
872<P>
873
874For &quot;.return&quot; probes, context variables other than the &quot;$return&quot; may
875be accessible, as a convenience for a script programmer wishing to
876access function parameters. These values are <B>snapshots</B>
877taken at the time of function entry. Local variables within the
878function are <B>not</B> generally accessible, since those variables did
879not exist in allocated/initialized form at the snapshot moment.
880<P>
881
882In addition, arbitrary entry-time expressions can also be saved for
883&quot;.return&quot; probes using the
884<I>@entry(expr)</I>
885
886operator. For example, one can compute the elapsed time of a function:
887
888<P>
889
890<BR>
891
892<DL COMPACT><DT><DD>
893<PRE>
894probe kernel.function(&quot;do_filp_open&quot;).return {
895 println( get_timeofday_us() - @entry(get_timeofday_us()) )
896}
897
898</PRE>
899
900</DL>
901
902
903<P>
904
905<P>
906<P>
907
908The following table summarizes how values related to a function
909parameter context variable, a pointer named <B>addr</B>, may be
910accessed from a
911<I>.return</I>
912
913probe.
914
915<TABLE>
916<TR VALIGN=top><TD><B>at-entry value</B></TD><TD>past-exit value</TD><TD><BR></TD></TR>
917<TR VALIGN=top><TD></TD><TD></TD><TD><BR></TD></TR>
918<TR VALIGN=top><TD>$addr</TD><TD><I>not available</I></TD><TD><BR></TD></TR>
919<TR VALIGN=top><TD>$addr-&gt;x-&gt;y</TD><TD>@cast(@entry($addr),&quot;struct zz&quot;)-&gt;x-&gt;y</TD><TD><BR></TD></TR>
920<TR VALIGN=top><TD>$addr[0]</TD><TD>{kernel,user}_{char,int,...}(&amp; $addr[0])</TD><TD><BR></TD></TR>
921</TABLE>
922
923<P>
924<P>
925<A NAME="lbAN">&nbsp;</A>
926<H3>DWARFLESS</H3>
927
928In absence of debugging information, entry &amp; exit points of kernel &amp; module
929functions can be probed using the &quot;kprobe&quot; family of probes.
930However, these do not permit looking up the arguments / local variables
931of the function.
932Following constructs are supported :
933
934<P>
935
936<BR>
937
938<DL COMPACT><DT><DD>
939<PRE>
940kprobe.function(FUNCTION)
941kprobe.function(FUNCTION).call
942kprobe.function(FUNCTION).return
943kprobe.module(NAME).function(FUNCTION)
944kprobe.module(NAME).function(FUNCTION).call
945kprobe.module(NAME).function(FUNCTION).return
946kprobe.statement.(ADDRESS).absolute
947
948</PRE>
949
950</DL>
951
952
953<P>
954
955<P>
956
957Probes of type
958<B>function</B>
959
960are recommended for kernel functions, whereas probes of type
961<B>module</B>
962
963are recommended for probing functions of the specified module.
964In case the absolute address of a kernel or module function is known,
965<B>statement</B>
966
967probes can be utilized.
968<P>
969
970Note that
971<I>FUNCTION</I>
972
973and
974<I>MODULE</I>
975
976names
977<B>must not</B>
978
979contain wildcards, or the probe will not be registered.
980Also, statement probes must be run under guru-mode only.
981<P>
982<P>
983<A NAME="lbAO">&nbsp;</A>
984<H3>USER-SPACE</H3>
985
986Support for user-space probing is available for kernels that are
987configured with the utrace extensions, or have the uprobes facility in
988linux 3.5. (Various kernel build configuration options need to be
989enabled; systemtap will advise if these are missing.)
990<P>
991<P>
992
993There are several forms. First, a non-symbolic probe point:
994
995<P>
996
997<BR>
998
999<DL COMPACT><DT><DD>
1000<PRE>
1001process(PID).statement(ADDRESS).absolute
1002
1003</PRE>
1004
1005</DL>
1006
1007
1008<P>
1009
1010is analogous to
1011
1012kernel.statement(ADDRESS).absolute
1013in that both use raw (unverified) virtual addresses and provide
1014no $variables. The target PID parameter must identify a running
1015process, and ADDRESS should identify a valid instruction address.
1016All threads of that process will be probed.
1017<P>
1018
1019Second, non-symbolic user-kernel interface events handled by
1020utrace may be probed:
1021
1022<P>
1023
1024<BR>
1025
1026<DL COMPACT><DT><DD>
1027<PRE>
1028process(PID).begin
1029process(&quot;FULLPATH&quot;).begin
1030process.begin
1031process(PID).thread.begin
1032process(&quot;FULLPATH&quot;).thread.begin
1033process.thread.begin
1034process(PID).end
1035process(&quot;FULLPATH&quot;).end
1036process.end
1037process(PID).thread.end
1038process(&quot;FULLPATH&quot;).thread.end
1039process.thread.end
1040process(PID).syscall
1041process(&quot;FULLPATH&quot;).syscall
1042process.syscall
1043process(PID).syscall.return
1044process(&quot;FULLPATH&quot;).syscall.return
1045process.syscall.return
1046process(PID).insn
1047process(&quot;FULLPATH&quot;).insn
1048process(PID).insn.block
1049process(&quot;FULLPATH&quot;).insn.block
1050
1051</PRE>
1052
1053</DL>
1054
1055
1056<P>
1057
1058<P>
1059
1060A
1061<B>.begin</B>
1062
1063probe gets called when new process described by PID or FULLPATH gets created.
1064A
1065<B>.thread.begin</B>
1066
1067probe gets called when a new thread described by PID or FULLPATH gets created.
1068A
1069<B>.end</B>
1070
1071probe gets called when process described by PID or FULLPATH dies.
1072A
1073<B>.thread.end</B>
1074
1075probe gets called when a thread described by PID or FULLPATH dies.
1076A
1077<B>.syscall</B>
1078
1079probe gets called when a thread described by PID or FULLPATH makes a
1080system call. The system call number is available in the
1081<B>$syscall</B>
1082
1083context variable, and the first 6 arguments of the system call
1084are available in the
1085<B>$argN</B>
1086
1087(ex. $arg1, $arg2, ...) context variable.
1088A
1089<B>.syscall.return</B>
1090
1091probe gets called when a thread described by PID or FULLPATH returns from a
1092system call. The system call number is available in the
1093<B>$syscall</B>
1094
1095context variable, and the return value of the system call is available
1096in the
1097<B>$return</B>
1098
1099context variable.
1100A
1101<B>.insn</B>
1102
1103probe gets called for every single-stepped instruction of the process described by PID or FULLPATH.
1104A
1105<B>.insn.block</B>
1106
1107probe gets called for every block-stepped instruction of the process described by PID or FULLPATH.
1108<P>
1109
1110If a process probe is specified without a PID or FULLPATH, all user
1111threads will be probed. However, if systemtap was invoked with the
1112<I>-c</I> or <I>-x</I>
1113
1114options, then process probes are restricted to the process
1115hierarchy associated with the target process. If a process probe is
1116unspecified (i.e. without a PID or FULLPATH), but with the
1117<I>-c</I>
1118
1119option, the PATH of the
1120<I>-c</I>
1121
1122cmd will be heuristically filled into the process PATH. In that case,
1123only command parameters are allowed in the <I>-c</I> command (i.e. no
1124command substitution allowed and no occurrences of any of these
1125characters: '|&amp;;&lt;&gt;(){}').
1126<P>
1127<P>
1128
1129Third, symbolic static instrumentation compiled into programs and
1130shared libraries may be
1131probed:
1132
1133<P>
1134
1135<BR>
1136
1137<DL COMPACT><DT><DD>
1138<PRE>
1139process(&quot;PATH&quot;).mark(&quot;LABEL&quot;)
1140process(&quot;PATH&quot;).provider(&quot;PROVIDER&quot;).mark(&quot;LABEL&quot;)
1141
1142</PRE>
1143
1144</DL>
1145
1146
1147<P>
1148
1149<P>
1150
1151A
1152<B>.mark</B>
1153
1154probe gets called via a static probe which is defined in the
1155application by STAP_PROBE1(PROVIDER,LABEL,arg1), which are macros defined in
1156<B>sys/sdt.h</B>.
1157
1158The PROVIDER is an arbitrary application identifier, LABEL is the
1159marker site identifier, and arg1 is the integer-typed argument.
1160STAP_PROBE1 is used for probes with 1 argument, STAP_PROBE2 is used
1161for probes with 2 arguments, and so on. The arguments of the probe
1162are available in the context variables $arg1, $arg2, ... An
1163alternative to using the STAP_PROBE macros is to use the dtrace script
1164to create custom macros. Additionally, the variables $$name and
1165$$provider are available as parts of the probe point name. The
1166<B>sys/sdt.h </B>
1167
1168macro names DTRACE_PROBE* are available as aliases for STAP_PROBE*.
1169<P>
1170<P>
1171
1172Finally, full symbolic source-level probes in user-space programs and
1173shared libraries are supported. These are exactly analogous to the
1174symbolic DWARF-based kernel/module probes described above. They
1175expose the same sorts of context $variables for function parameters,
1176local variables, and so on.
1177
1178<P>
1179
1180<BR>
1181
1182<DL COMPACT><DT><DD>
1183<PRE>
1184process(&quot;PATH&quot;).function(&quot;NAME&quot;)
1185process(&quot;PATH&quot;).statement(&quot;*@FILE.c:123&quot;)
1186process(&quot;PATH&quot;).plt(&quot;NAME&quot;)
1187process(&quot;PATH&quot;).library(&quot;PATH&quot;).plt(&quot;NAME&quot;)
1188process(&quot;PATH&quot;).library(&quot;PATH&quot;).function(&quot;NAME&quot;)
1189process(&quot;PATH&quot;).library(&quot;PATH&quot;).statement(&quot;*@FILE.c:123&quot;)
1190process(&quot;PATH&quot;).function(&quot;*&quot;).return
1191process(&quot;PATH&quot;).function(&quot;myfun&quot;).label(&quot;foo&quot;)
1192process(&quot;PATH&quot;).function(&quot;foo&quot;).callee(&quot;bar&quot;)
1193
1194</PRE>
1195
1196</DL>
1197
1198
1199<P>
1200
1201<P>
1202<P>
1203
1204Note that for all process probes,
1205<I>PATH</I>
1206
1207names refer to executables that are searched the same way shells do: relative
1208to the working directory if they contain a &quot;/&quot; character, otherwise in
1209<B>$PATH</B>.
1210
1211If PATH names refer to scripts, the actual interpreters (specified in the
1212script in the first line after the #! characters) are probed.
1213If PATH is a process component parameter referring to shared libraries
1214then all processes that map it at runtime would be selected for
1215probing. If PATH is a library component parameter referring to shared
1216libraries then the process specified by the process component would be
1217selected.
1218<P>
1219<P>
1220
1221A .plt probe will probe functions in the program linkage table
1222corresponding to the rest of the probe point. .plt can be specified
1223as a shorthand for .plt(&quot;*&quot;). The symbol name is available as a
1224$$name context variable; function arguments are not available, since
1225PLTs are processed without debuginfo.
1226<P>
1227<P>
1228
1229If the PATH string contains wildcards as in the MPATTERN case, then
1230standard globbing is performed to find all matching paths. In this
1231case, the
1232<B>$PATH</B>
1233
1234environment variable is not used.
1235<P>
1236<P>
1237
1238If systemtap was invoked with the
1239<I>-c</I> or <I>-x</I>
1240
1241options, then process probes are restricted to the process
1242hierarchy associated with the target process.
1243<P>
1244<A NAME="lbAP">&nbsp;</A>
1245<H3>JAVA</H3>
1246
1247Support for probing Java methods is available using Byteman as a
1248backend. Byteman is an instrumentation tool from the JBoss project
1249which systemtap can use to monitor invocations for a specific method
1250or line in a Java program.
1251<P>
1252
1253Systemtap does so by generating a Byteman script listing the probes to
1254instrument and then invoking the Byteman
1255<I>bminstall</I>
1256
1257utility.
1258<P>
1259
1260This Java instrumentation support is currently a prototype feature
1261with major limitations. Moreover, Java probing currently does not
1262work across users; the stap script must run (with appropriate
1263permissions) under the same user that the Java process being
1264probed. (Thus a stap script under root currently cannot probe Java
1265methods in a non-root-user Java process.)
1266<P>
1267<P>
1268
1269The first probe type refers to Java processes by the name of the Java process:
1270
1271<P>
1272
1273<BR>
1274
1275<DL COMPACT><DT><DD>
1276<PRE>
1277java(&quot;PNAME&quot;).class(&quot;CLASSNAME&quot;).method(&quot;PATTERN&quot;)
1278java(&quot;PNAME&quot;).class(&quot;CLASSNAME&quot;).method(&quot;PATTERN&quot;).return
1279
1280</PRE>
1281
1282</DL>
1283
1284
1285<P>
1286
1287The PNAME argument must be a pre-existing jvm pid, and be identifiable
1288via a jps listing.
1289<P>
1290
1291The PATTERN parameter specifies the signature of the Java method to
1292probe. The signature must consist of the exact name of the method,
1293followed by a bracketed list of the types of the arguments, for
1294instance &quot;myMethod(int,double,Foo)&quot;. Wildcards are not supported.
1295<P>
1296
1297The probe can be set to trigger at a specific line within the method
1298by appending a line number with colon, just as in other types of
1299probes: &quot;myMethod(int,double,Foo):245&quot;.
1300<P>
1301
1302The CLASSNAME parameter identifies the Java class the method belongs
1303to, either with or without the package qualification. By default, the
1304probe only triggers on descendants of the class that do not override
1305the method definition of the original class. However, CLASSNAME can
1306take an optional caret prefix, as in
1307<I>^org.my.MyClass,</I>
1308
1309which specifies that the probe should also trigger on all descendants
1310of MyClass that override the original method. For instance, every method
1311with signature foo(int) in program org.my.MyApp can be probed at once using
1312
1313<P>
1314
1315<BR>
1316
1317<DL COMPACT><DT><DD>
1318<PRE>
1319java(&quot;org.my.MyApp&quot;).class(&quot;^java.lang.Object&quot;).method(&quot;foo(int)&quot;)
1320
1321</PRE>
1322
1323</DL>
1324
1325
1326<P>
1327
1328<P>
1329
1330The second probe type works analogously, but refers to Java processes by PID:
1331
1332<P>
1333
1334<BR>
1335
1336<DL COMPACT><DT><DD>
1337<PRE>
1338java(PID).class(&quot;CLASSNAME&quot;).method(&quot;PATTERN&quot;)
1339java(PID).class(&quot;CLASSNAME&quot;).method(&quot;PATTERN&quot;).return
1340
1341</PRE>
1342
1343</DL>
1344
1345
1346<P>
1347
1348(PIDs for an already running process can be obtained using the
1349<I><A HREF="jps.1.html">jps</A></I>(1)
1350
1351utility.)
1352<P>
1353
1354Context variables defined within java probes include
1355<I>$arg1</I>
1356
1357through
1358<I>$arg10</I>
1359
1360(for up to the first 10 arguments of a method), represented as integers or strings.
1361<P>
1362<A NAME="lbAQ">&nbsp;</A>
1363<H3>PROCFS</H3>
1364
1365<P>
1366These probe points allow procfs &quot;files&quot; in
1367/proc/systemtap/MODNAME to be created, read and written using a
1368permission that may be modified using the proper umask value. Default permissions are 0400 for read
1369probes, and 0200 for write probes. If both a read and write probe are being
1370used on the same file, a default permission of 0600 will be used.
1371Using procfs.umask(0040).read would
1372result in a 0404 permission set for the file.
1373(<I>MODNAME</I>
1374
1375is the name of the systemtap module). The
1376<I>proc</I>
1377
1378filesystem is a pseudo-filesystem which is used an an interface to
1379kernel data structures. There are several probe point variants supported
1380by the translator:
1381<P>
1382
1383<P>
1384
1385<BR>
1386
1387<DL COMPACT><DT><DD>
1388<PRE>
1389procfs(&quot;PATH&quot;).read
1390procfs(&quot;PATH&quot;).umask(UMASK).read
1391procfs(&quot;PATH&quot;).read.maxsize(MAXSIZE)
1392procfs(&quot;PATH&quot;).umask(UMASK).maxsize(MAXSIZE)
1393procfs(&quot;PATH&quot;).write
1394procfs(&quot;PATH&quot;).umask(UMASK).write
1395procfs.read
1396procfs.umask(UMASK).read
1397procfs.read.maxsize(MAXSIZE)
1398procfs.umask(UMASK).read.maxsize(MAXSIZE)
1399procfs.write
1400procfs.umask(UMASK).write
1401
1402</PRE>
1403
1404</DL>
1405
1406
1407<P>
1408
1409<P>
1410<I>PATH</I>
1411
1412is the file name (relative to /proc/systemtap/MODNAME) to be created.
1413If no
1414<I>PATH</I>
1415
1416is specified (as in the last two variants above),
1417<I>PATH</I>
1418
1419defaults to &quot;command&quot;.
1420<P>
1421
1422When a user reads /proc/systemtap/MODNAME/PATH, the corresponding
1423procfs
1424<I>read</I>
1425
1426probe is triggered. The string data to be read should be assigned to
1427a variable named
1428<I>$value</I>,
1429
1430like this:
1431<P>
1432
1433<P>
1434
1435<BR>
1436
1437<DL COMPACT><DT><DD>
1438<PRE>
1439procfs(&quot;PATH&quot;).read { $value = &quot;100\n&quot; }
1440
1441</PRE>
1442
1443</DL>
1444
1445
1446<P>
1447
1448<P>
1449
1450When a user writes into /proc/systemtap/MODNAME/PATH, the
1451corresponding procfs
1452<I>write</I>
1453
1454probe is triggered. The data the user wrote is available in the
1455string variable named
1456<I>$value</I>,
1457
1458like this:
1459<P>
1460
1461<P>
1462
1463<BR>
1464
1465<DL COMPACT><DT><DD>
1466<PRE>
1467procfs(&quot;PATH&quot;).write { printf(&quot;user wrote: %s&quot;, $value) }
1468
1469</PRE>
1470
1471</DL>
1472
1473
1474<P>
1475
1476<P>
1477
1478<I>MAXSIZE</I>
1479
1480is the size of the procfs read buffer. Specifying
1481<I>MAXSIZE</I>
1482
1483allows larger procfs output. If no
1484<I>MAXSIZE</I>
1485
1486is specified, the procfs read buffer defaults to
1487<I>STP_PROCFS_BUFSIZE</I>
1488
1489(which defaults to
1490<I>MAXSTRINGLEN</I>,
1491
1492the maximum length of a string).
1493If setting the procfs read buffers for more than one file is needed,
1494it may be easiest to override the
1495<I>STP_PROCFS_BUFSIZE</I>
1496
1497definition.
1498Here's an example of using
1499<I>MAXSIZE</I>:
1500
1501<P>
1502
1503<P>
1504
1505<BR>
1506
1507<DL COMPACT><DT><DD>
1508<PRE>
1509procfs.read.maxsize(1024) {
1510 $value = &quot;long string...&quot;
1511 $value .= &quot;another long string...&quot;
1512 $value .= &quot;another long string...&quot;
1513 $value .= &quot;another long string...&quot;
1514}
1515
1516</PRE>
1517
1518</DL>
1519
1520
1521<P>
1522
1523<P>
1524<A NAME="lbAR">&nbsp;</A>
1525<H3>NETFILTER HOOKS</H3>
1526
1527<P>
1528These probe points allow observation of network packets using the
1529netfilter mechanism. A netfilter probe in systemtap corresponds to a
1530netfilter hook function in the original netfilter probes API. It is
1531probably more convenient to use
1532<I><A HREF="./tapset::netfilter.3stap.html">tapset::netfilter</A></I>(3stap),
1533
1534which wraps the primitive netfilter hooks and does the work of
1535extracting useful information from the context variables.
1536<P>
1537<P>
1538
1539There are several probe point variants supported by the translator:
1540<P>
1541
1542<P>
1543
1544<BR>
1545
1546<DL COMPACT><DT><DD>
1547<PRE>
1548netfilter.hook(&quot;HOOKNAME&quot;).pf(&quot;PROTOCOL_F&quot;)
1549netfilter.pf(&quot;PROTOCOL_F&quot;).hook(&quot;HOOKNAME&quot;)
1550netfilter.hook(&quot;HOOKNAME&quot;).pf(&quot;PROTOCOL_F&quot;).priority(&quot;PRIORITY&quot;)
1551netfilter.pf(&quot;PROTOCOL_F&quot;).hook(&quot;HOOKNAME&quot;).priority(&quot;PRIORITY&quot;)
1552
1553</PRE>
1554
1555</DL>
1556
1557
1558<P>
1559
1560<P>
1561<P>
1562
1563<I>PROTOCOL_F</I>
1564
1565is the protocol family to listen for, currently one of
1566<I>NFPROTO_IPV4,</I>
1567
1568<I>NFPROTO_IPV6,</I>
1569
1570<I>NFPROTO_ARP,</I>
1571
1572or
1573<I>NFPROTO_BRIDGE.</I>
1574
1575<P>
1576<P>
1577
1578<I>HOOKNAME</I>
1579
1580is the point, or 'hook', in the protocol stack at which to intercept
1581the packet. The available hook names for each protocol family are
1582taken from the kernel header files &lt;<A HREF="file:///usr/include/linux/netfilter_ipv4.h">linux/netfilter_ipv4.h</A>&gt;,
1583&lt;<A HREF="file:///usr/include/linux/netfilter_ipv6.h">linux/netfilter_ipv6.h</A>&gt;, &lt;<A HREF="file:///usr/include/linux/netfilter_arp.h">linux/netfilter_arp.h</A>&gt; and
1584&lt;<A HREF="file:///usr/include/linux/netfilter_bridge.h">linux/netfilter_bridge.h</A>&gt;. For instance, allowable hook names for
1585<I>NFPROTO_IPV4</I>
1586
1587are
1588<I>NF_INET_PRE_ROUTING,</I>
1589
1590<I>NF_INET_LOCAL_IN,</I>
1591
1592<I>NF_INET_FORWARD,</I>
1593
1594<I>NF_INET_LOCAL_OUT,</I>
1595
1596and
1597<I>NF_INET_POST_ROUTING.</I>
1598
1599<P>
1600<P>
1601
1602<I>PRIORITY</I>
1603
1604is an integer priority giving the order in which the probe point
1605should be triggered relative to any other netfilter hook functions
1606which trigger on the same packet. Hook functions execute on each
1607packet in order from smallest priority number to largest priority number. If no
1608<I>PRIORITY</I>
1609
1610is specified (as in the first two probe point variants above),
1611<I>PRIORITY</I>
1612
1613defaults to &quot;0&quot;.
1614<P>
1615There are a number of predefined priority names of the form
1616<I>NF_IP_PRI_*</I>
1617
1618and
1619<I>NF_IP6_PRI_*</I>
1620
1621which are defined in the kernel header files &lt;<A HREF="file:///usr/include/linux/netfilter_ipv4.h">linux/netfilter_ipv4.h</A>&gt; and &lt;<A HREF="file:///usr/include/linux/netfilter_ipv6.h">linux/netfilter_ipv6.h</A>&gt; respectively. The script is permitted to use these
1622instead of specifying an integer priority. (The probe points for
1623<I>NFPROTO_ARP</I>
1624
1625and
1626<I>NFPROTO_BRIDGE</I>
1627
1628currently do not expose any named hook priorities to the script writer.)
1629Thus, allowable ways to specify the priority include:
1630<P>
1631
1632<P>
1633
1634<BR>
1635
1636<DL COMPACT><DT><DD>
1637<PRE>
1638priority(&quot;255&quot;)
1639priority(&quot;NF_IP_PRI_SELINUX_LAST&quot;)
1640
1641</PRE>
1642
1643</DL>
1644
1645
1646<P>
1647
1648<P>
1649A script using guru mode is permitted to specify any identifier or
1650number as the parameter for hook, pf, and priority. This feature
1651should be used with caution, as the parameter is inserted verbatim into
1652the C code generated by systemtap.
1653<P>
1654The netfilter probe points define the following context variables:
1655<DL COMPACT>
1656<DT><I>$hooknum</I>
1657
1658<DD>
1659The hook number.
1660<DT><I>$skb</I>
1661
1662<DD>
1663The address of the sk_buff struct representing the packet. See
1664&lt;<A HREF="file:///usr/include/linux/skbuff.h">linux/skbuff.h</A>&gt; for details on how to use this struct, or
1665alternatively use the tapset
1666<I><A HREF="./tapset::netfilter.3stap.html">tapset::netfilter</A></I>(3stap)
1667
1668for easy access to key information.
1669<P>
1670<DT><I>$in</I>
1671
1672<DD>
1673The address of the net_device struct representing the network device
1674on which the packet was received (if any). May be 0 if the device is
1675unknown or undefined at that stage in the protocol stack.
1676<P>
1677<DT><I>$out</I>
1678
1679<DD>
1680The address of the net_device struct representing the network device
1681on which the packet will be sent (if any). May be 0 if the device is
1682unknown or undefined at that stage in the protocol stack.
1683<P>
1684<DT><I>$verdict</I>
1685
1686<DD>
1687(Guru mode only.) Assigning one of the verdict values defined in
1688&lt;<A HREF="file:///usr/include/linux/netfilter.h">linux/netfilter.h</A>&gt; to this variable alters the further progress of
1689the packet through the protocol stack. For instance, the following
1690guru mode script forces all ipv6 network packets to be dropped:
1691<P>
1692
1693<P>
1694
1695<BR>
1696
1697<DL COMPACT><DT><DD>
1698<PRE>
1699probe netfilter.pf(&quot;NFPROTO_IPV6&quot;).hook(&quot;NF_IP6_PRE_ROUTING&quot;) {
1700 $verdict = 0 /* nf_drop */
1701}
1702
1703</PRE>
1704
1705</DL>
1706
1707
1708<P>
1709
1710<P>
1711For convenience, unlike the primitive probe points discussed here, the
1712probes defined in
1713<I><A HREF="./tapset::netfilter.3stap.html">tapset::netfilter</A></I>(3stap)
1714
1715export the lowercase names of the verdict constants (e.g. NF_DROP
1716becomes nf_drop) as local variables.
1717<P>
1718</DL>
1719<A NAME="lbAS">&nbsp;</A>
1720<H3>MARKERS</H3>
1721
1722<P>
1723This family of probe points hooks up to static probing markers
1724inserted into the kernel or modules. These markers are special macro
1725calls inserted by kernel developers to make probing faster and more
1726reliable than with DWARF-based probes. Further, DWARF debugging
1727information is
1728<I>not</I>
1729
1730required to probe markers.
1731<P>
1732Marker probe points begin with
1733<B>kernel</B>.
1734
1735The next part names the marker itself:
1736<B>mark(name)</B>.
1737
1738The marker name string, which may contain the usual wildcard characters,
1739is matched against the names given to the marker macros when the kernel
1740and/or module was compiled. Optionally, you can specify
1741<B>format(format)</B>.
1742
1743Specifying the marker format string allows differentiation between two
1744markers with the same name but different marker format strings.
1745<P>
1746The handler associated with a marker-based probe may read the
1747optional parameters specified at the macro call site. These are
1748named
1749<B>$arg1</B> through <B>$argNN</B>,
1750
1751where NN is the number of parameters supplied by the macro. Number
1752and string parameters are passed in a type-safe manner.
1753<P>
1754The marker format string associated with a marker is available in
1755<B>$format</B>.
1756
1757And also the marker name string is available in
1758<B>$name</B>.
1759
1760<P>
1761<A NAME="lbAT">&nbsp;</A>
1762<H3>TRACEPOINTS</H3>
1763
1764<P>
1765This family of probe points hooks up to static probing tracepoints
1766inserted into the kernel or modules. As with markers, these
1767tracepoints are special macro calls inserted by kernel developers to
1768make probing faster and more reliable than with DWARF-based probes,
1769and DWARF debugging information is not required to probe tracepoints.
1770Tracepoints have an extra advantage of more strongly-typed parameters
1771than markers.
1772<P>
1773Tracepoint probes begin with
1774<B>kernel</B>.
1775
1776The next part names the tracepoint itself:
1777<B>trace(name)</B>.
1778
1779The tracepoint name string, which may contain the usual wildcard
1780characters, is matched against the names defined by the kernel
1781developers in the tracepoint header files.
1782<P>
1783The handler associated with a tracepoint-based probe may read the
1784optional parameters specified at the macro call site. These are
1785named according to the declaration by the tracepoint author. For
1786example, the tracepoint probe
1787<B>kernel.trace(sched_switch)</B>
1788
1789provides the parameters
1790<B>$rq</B>, <B>$prev</B>, and <B>$next</B>.
1791
1792If the parameter is a complex type, as in a struct pointer, then a
1793script can access fields with the same syntax as DWARF $target
1794variables. Also, tracepoint parameters cannot be modified, but in
1795guru-mode a script may modify fields of parameters.
1796<P>
1797The name of the tracepoint is available in
1798<B>$$name</B>,
1799
1800and a string of name=value pairs for all parameters of the tracepoint
1801is available in
1802<B>$$vars</B> or <B>$$parms</B>.
1803
1804<P>
1805<A NAME="lbAU">&nbsp;</A>
1806<H3>HARDWARE BREAKPOINTS</H3>
1807
1808This family of probes is used to set hardware watchpoints for a given
1809<BR>&nbsp;(global)&nbsp;kernel&nbsp;symbol.&nbsp;The&nbsp;probes&nbsp;take&nbsp;three&nbsp;components&nbsp;as&nbsp;inputs&nbsp;:
1810<P>
18111. The
1812<B>virtual</B>address<B>/</B>name
1813
1814of the kernel symbol to be traced is supplied as argument to this class
1815of probes. ( Probes for only data segment variables are supported. Probing
1816local variables of a function cannot be done.)
1817<P>
18182. Nature of access to be probed :
1819a.
1820<I>.write</I>
1821
1822probe gets triggered when a write happens at the specified address/symbol
1823name.
1824b.
1825<I>rw</I>
1826
1827probe is triggered when either a read or write happens.
1828<P>
18293.
1830<B>.length</B>
1831
1832(optional)
1833Users have the option of specifying the address interval to be probed
1834using &quot;length&quot; constructs. The user-specified length gets approximated
1835to the closest possible address length that the architecture can
1836support. If the specified length exceeds the limits imposed by
1837architecture, an error message is flagged and probe registration fails.
1838Wherever 'length' is not specified, the translator requests a hardware
1839breakpoint probe of length 1. It should be noted that the &quot;length&quot;
1840construct is not valid with symbol names.
1841<P>
1842Following constructs are supported :
1843
1844<P>
1845
1846<BR>
1847
1848<DL COMPACT><DT><DD>
1849<PRE>
1850probe kernel.data(ADDRESS).write
1851probe kernel.data(ADDRESS).rw
1852probe kernel.data(ADDRESS).length(LEN).write
1853probe kernel.data(ADDRESS).length(LEN).rw
1854probe kernel.data(&quot;SYMBOL_NAME&quot;).write
1855probe kernel.data(&quot;SYMBOL_NAME&quot;).rw
1856
1857</PRE>
1858
1859</DL>
1860
1861
1862<P>
1863
1864<P>
1865This set of probes make use of the debug registers of the processor,
1866which is a scarce resource. (4 on x86 , 1 on powerpc ) The script
1867translation flags a warning if a user requests more hardware breakpoint probes
1868than the limits set by architecture. For example,a pass-2 warning is flashed
1869when an input script requests 5 hardware breakpoint probes on an x86
1870system while x86 architecture supports a maximum of 4 breakpoints.
1871Users are cautioned to set probes judiciously.
1872<P>
1873<A NAME="lbAV">&nbsp;</A>
1874<H3>PERF</H3>
1875
1876<P>
1877This family of probe points interfaces to the kernel &quot;perf event&quot;
1878infrastructure for controlling hardware performance counters.
1879The events being attached to are described by the &quot;type&quot;,
1880&quot;config&quot; fields of the
1881<I>perf_event_attr</I>
1882
1883structure, and are sampled at an interval governed by the
1884&quot;sample_period&quot; field.
1885<P>
1886These fields are made available to systemtap scripts using
1887the following syntax:
1888
1889<P>
1890
1891<BR>
1892
1893<DL COMPACT><DT><DD>
1894<PRE>
1895probe perf.type(NN).config(MM).sample(XX)
1896probe perf.type(NN).config(MM)
1897probe perf.type(NN).config(MM).process(&quot;PROC&quot;)
1898probe perf.type(NN).config(MM).counter(&quot;COUNTER&quot;)
1899probe perf.type(NN).config(MM).process(&quot;PROC&quot;).counter(&quot;COUNTER&quot;)
1900
1901</PRE>
1902
1903</DL>
1904
1905
1906<P>
1907
1908The systemtap probe handler is called once per XX increments
1909of the underlying performance counter. The default sampling
1910count is 1000000.
1911The range of valid type/config is described by the
1912<I><A HREF="perf_event_open.2.html">perf_event_open</A></I>(2)
1913
1914system call, and/or the
1915<I>linux/perf_event.h</I>
1916
1917file. Invalid combinations or exhausted hardware counter resources
1918result in errors during systemtap script startup. Systemtap does
1919not sanity-check the values: it merely passes them through to
1920the kernel for error- and safety-checking. By default the perf event
1921probe is systemwide unless .process is specified, which will bind the
1922probe to a specific task. If the name is omitted then it
1923is inferred from the stap -c argument. A perf event can be read on
1924demand using .counter. The body of the perf probe handler will not be
1925invoked for a .counter probe; instead, the counter is read in a user
1926space probe via:
1927<DL COMPACT>
1928<DT><BR>&nbsp;&nbsp;&nbsp;process(&quot;PROCESS&quot;).statement(&quot;<A HREF="mailto:func@file">func@file</A>&quot;)&nbsp;{stat&nbsp;&lt;&lt;&lt;&nbsp;@perf(&quot;NAME&quot;)}&nbsp;<DD>
1929<P>
1930<P>
1931</DL>
1932<A NAME="lbAW">&nbsp;</A>
1933<H2>EXAMPLES</H2>
1934
1935<P>
1936
1937Here are some example probe points, defining the associated events.
1938<DL COMPACT>
1939<DT>begin, end, end<DD>
1940refers to the startup and normal shutdown of the session. In this
1941case, the handler would run once during startup and twice during
1942shutdown.
1943<DT>timer.jiffies(1000).randomize(200)<DD>
1944refers to a periodic interrupt, every 1000 +/- 200 jiffies.
1945<DT>kernel.function(&quot;*init*&quot;), kernel.function(&quot;*exit*&quot;)<DD>
1946refers to all kernel functions with &quot;init&quot; or &quot;exit&quot; in the name.
1947<DT>kernel.function(&quot;*@kernel/time.c:240&quot;)<DD>
1948refers to any functions within the &quot;kernel/time.c&quot; file that span
1949line 240.
1950
1951Note
1952that this is
1953<B>not</B>
1954
1955a probe at the statement at that line number. Use the
1956
1957kernel.statement
1958probe instead.
1959<DT>kernel.mark(&quot;getuid&quot;)<DD>
1960refers to an STAP_MARK(getuid, ...) macro call in the kernel.
1961<DT>module(&quot;usb*&quot;).function(&quot;*sync*&quot;).return<DD>
1962refers to the moment of return from all functions with &quot;sync&quot; in the
1963name in any of the USB drivers.
1964<DT>kernel.statement(0xc0044852)<DD>
1965refers to the first byte of the statement whose compiled instructions
1966include the given address in the kernel.
1967<DT>kernel.statement(&quot;*@kernel/time.c:296&quot;)<DD>
1968refers to the statement of line 296 within &quot;kernel/time.c&quot;.
1969<DT>kernel.statement(&quot;bio_init@fs/bio.c+3&quot;)<DD>
1970refers to the statement at line bio_init+3 within &quot;fs/bio.c&quot;.
1971<DT>kernel.data(&quot;pid_max&quot;).write<DD>
1972refers to a hardware breakpoint of type &quot;write&quot; set on pid_max
1973<DT>syscall.*.return<DD>
1974refers to the group of probe aliases with any name in the third position
1975<P>
1976</DL>
1977<A NAME="lbAX">&nbsp;</A>
1978<H2>SEE ALSO</H2>
1979
1980
1981<PRE>
1982<I><A HREF="stap.1.html">stap</A></I>(1),
1983<I>probe::*</I>(3stap),
1984<I>tapset::*</I>(3stap)
1985
1986
1987</PRE>
1988<HR>
1989<A NAME="index">&nbsp;</A><H2>Index</H2>
1990<DL>
1991<DT><A HREF="#lbAB">NAME</A><DD>
1992<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
1993<DT><A HREF="#lbAD">SYNTAX</A><DD>
1994<DT><A HREF="#lbAE">DWARF DEBUGINFO</A><DD>
1995<DT><A HREF="#lbAF">PROBE POINT FAMILIES</A><DD>
1996<DL>
1997<DT><A HREF="#lbAG">BEGIN/END/ERROR</A><DD>
1998<DT><A HREF="#lbAH">NEVER</A><DD>
1999<DT><A HREF="#lbAI">SYSCALL and ND_SYSCALL</A><DD>
2000<DT><A HREF="#lbAJ">TIMERS</A><DD>
2001<DT><A HREF="#lbAK">DWARF</A><DD>
2002<DT><A HREF="#lbAL">CONTEXT VARIABLES</A><DD>
2003<DT><A HREF="#lbAM">MORE ON RETURN PROBES</A><DD>
2004<DT><A HREF="#lbAN">DWARFLESS</A><DD>
2005<DT><A HREF="#lbAO">USER-SPACE</A><DD>
2006<DT><A HREF="#lbAP">JAVA</A><DD>
2007<DT><A HREF="#lbAQ">PROCFS</A><DD>
2008<DT><A HREF="#lbAR">NETFILTER HOOKS</A><DD>
2009<DT><A HREF="#lbAS">MARKERS</A><DD>
2010<DT><A HREF="#lbAT">TRACEPOINTS</A><DD>
2011<DT><A HREF="#lbAU">HARDWARE BREAKPOINTS</A><DD>
2012<DT><A HREF="#lbAV">PERF</A><DD>
2013</DL>
2014<DT><A HREF="#lbAW">EXAMPLES</A><DD>
2015<DT><A HREF="#lbAX">SEE ALSO</A><DD>
2016</DL>
2017<HR>
2018This document was created by
2019<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
2020using the manual pages.<BR>
2021Time: 17:59:59 GMT, May 16, 2014
2022</BODY>
2023</HTML>
diff --git a/man/staprun.8.html b/man/staprun.8.html
new file mode 100644
index 00000000..95e11224
--- /dev/null
+++ b/man/staprun.8.html
@@ -0,0 +1,451 @@
1
2<HTML><HEAD><TITLE>Manpage of STAPRUN</TITLE>
3</HEAD><BODY>
4<H1>STAPRUN</H1>
5Section: Maintenance Commands (8)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11staprun - systemtap runtime
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>SYNOPSIS</H2>
15
16<P>
17<BR>
18
19<B>staprun</B>
20
21[
22<I>OPTIONS</I>
23
24]
25<I>MODULE</I>
26
27[
28<I>MODULE-OPTIONS</I>
29
30]
31<P>
32<A NAME="lbAD">&nbsp;</A>
33<H2>DESCRIPTION</H2>
34
35<P>
36The
37<I>staprun</I>
38
39program is the back-end of the Systemtap tool. It expects a kernel
40module produced by the front-end
41<I>stap</I>
42
43tool.
44<P>
45
46Splitting the systemtap tool into a front-end and a back-end allows a
47user to compile a systemtap script on a development machine that has
48the kernel development tools (needed to compile the script) and then
49transfer the resulting kernel module to a production machine that
50doesn't have any development tools installed.
51<P>
52
53Please refer to stappaths (7) for the version number, or run
54rpm -q systemtap (fedora/red hat)
55apt-get -v systemtap (ubuntu)
56<P>
57<A NAME="lbAE">&nbsp;</A>
58<H2>OPTIONS</H2>
59
60The
61<I>staprun</I>
62
63program supports the following options. Any other option
64prints a list of supported options.
65<DL COMPACT>
66<DT><B>-v</B>
67
68<DD>
69Verbose mode. The level of verbosity is also set in the
70<I>SYSTEMTAP_VERBOSE</I>
71
72environment variable.
73<DT><B>-V</B>
74
75<DD>
76Print version number and exit.
77<DT><B>-w</B>
78
79<DD>
80Suppress warnings from the script.
81<DT><B>-u</B>
82
83<DD>
84Load the uprobes.ko module.
85<DT><B>-c CMD</B>
86
87<DD>
88Command CMD will be run and the
89<I>staprun</I>
90
91program will exit when CMD
92does. The '_stp_target' variable will contain the pid for CMD.
93<DT><B>-x PID</B>
94
95<DD>
96The '_stp_target' variable will be set to PID.
97<DT><B>-o FILE</B>
98
99<DD>
100Send output to FILE. If the module uses bulk mode, the output will
101be in percpu files FILE_x(FILE_cpux in background and bulk mode)
102where 'x' is the cpu number. This supports <A HREF="strftime.3.html">strftime</A>(3) formats
103for FILE.
104<DT><B>-b BUFFER_SIZE</B>
105
106<DD>
107The systemtap module will specify a buffer size.
108Setting one here will override that value. The value should be
109an integer between 1 and 4095 which be assumed to be the
110buffer size in MB. That value will be per-cpu if bulk mode is used.
111<DT><B>-L</B>
112
113<DD>
114Load module and start probes, then detach from the module leaving the
115probes running. The module can be attached to later by using the
116<B>-A</B>
117
118option.
119<DT><B>-A</B>
120
121<DD>
122Attach to loaded systemtap module.
123<DT><B>-C WHEN</B>
124
125<DD>
126Control coloring of error messages. WHEN must be either
127
128&quot;never&quot;, &quot;always&quot;, or &quot;auto&quot;
129
130(i.e. enable only if at a terminal). If the option is missing, then &quot;auto&quot;
131is assumed. Colors can be modified using the SYSTEMTAP_COLORS environment
132variable. See the
133<I><A HREF="stap.1.html">stap</A></I>(1)
134
135manual page for more information on syntax and behaviour.
136<DT><B>-d</B>
137
138<DD>
139Delete a module. Only detached or unused modules
140the user has permission to access will be deleted. Use &quot;*&quot;
141(quoted) to delete all unused modules.
142<DT><B>-D</B>
143
144<DD>
145Run staprun in background as a daemon and show it's pid.
146<DT><B>-R</B>
147
148<DD>
149Rename the module to a unique name before inserting it.
150<DT><B>-r N:URI</B>
151
152<DD>
153Pass the given number and URI data to the tapset functions
154remote_id() and remote_uri().
155<DT><B>-S</B><I> size[,N]</I>
156
157<DD>
158Sets the maximum size of output file and the maximum number of output files.
159If the size of output file will exceed
160<B>size</B>
161
162, systemtap switches output file to the next file. And if the number of
163output files exceed
164<B>N</B>
165
166, systemtap removes the oldest output file. You can omit the second argument.
167<DT><B>-T timeout</B>
168
169<DD>
170Sets maximum time reader thread will wait before dumping trace buffer. Value is
171in ms, default is 200ms. Setting this to a high value decreases number of stapio
172wake-ups, allowing deeper sleep for embedded platforms. But it impacts interactivity
173on terminal as traces are dumped less often in case of low throughput.
174There is no interactivity or performance impact for high throughput as trace is
175dumped when buffer is full, before this timeout expires.
176<DT><B>var1=val</B>
177
178<DD>
179Sets the value of global variable var1 to val. Global variables contained
180within a module are treated as module options and can be set from the
181staprun command line.
182<P>
183</DL>
184<A NAME="lbAF">&nbsp;</A>
185<H2>ARGUMENTS</H2>
186
187<B>MODULE</B>
188
189is either a module path or a module name. If it is a module name,
190the module will be looked for in the following directory
191(where 'VERSION' is the output of &quot;uname -r&quot;):
192<DL COMPACT>
193<DT><DD>
194/lib/modules/VERSION/systemtap
195</DL>
196<P>
197
198
199Any additional arguments on the command line are passed to the
200module. One use of these additional module arguments is to set the value
201of global variables declared within the module.
202<P>
203
204<P>
205 $ stap -p4 -m mod1 -e&nbsp;'global var1=&quot;foo&quot;; probe begin{printf(&quot;%s\n&quot;, var1); exit()}'
206<BR>
207
208<P>
209
210Running this with an additional module argument:
211<P>
212
213<P>
214 $ staprun mod1.ko var1=&quot;HelloWorld&quot;
215<BR>
216
217 HelloWorld
218<P>
219
220Spaces and exclamation marks currently cannot be passed into global variables
221this way.
222<P>
223<A NAME="lbAG">&nbsp;</A>
224<H2>EXAMPLES</H2>
225
226See the
227<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap)
228
229manual page for a collection of sample scripts.
230<P>
231
232Here is a very basic example of how to use
233<I>staprun.</I>
234
235First, use
236<I>stap</I>
237
238to compile a script. The
239<I>stap</I>
240
241program will report the pathname to the resulting module.
242<P>
243
244 $ stap -p4 -e 'probe begin { printf(&quot;Hello World!\n&quot;); exit() }'
245<BR>
246
247 /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
248<P>
249
250Run
251<I>staprun</I>
252
253with the pathname to the module as an argument.
254<P>
255
256 $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
257<BR>
258
259 Hello World!
260<A NAME="lbAH">&nbsp;</A>
261<H2>MODULE DETACHING AND ATTACHING</H2>
262
263After the
264<I>staprun</I>
265
266program installs a Systemtap kernel module, users can detach from the
267kernel module and reattach to it later. The
268<B>-L</B>
269
270option loads the module and automatically detaches. Users can also
271detach from the kernel module interactively by sending the SIGQUIT
272signal from the keyboard (typically by typing Ctrl-\).
273<P>
274
275To reattach to a kernel module, the
276<I>staprun</I>
277
278<B>-A</B>
279
280option would be used.
281<P>
282<A NAME="lbAI">&nbsp;</A>
283<H2>FILE SWITCHING BY SIGNAL</H2>
284
285After
286<I>staprun</I>
287
288launched the
289<I>stapio</I>
290
291program, users can command it to switch output file to next file when it
292outputs to file(s) (running staprun with
293<B>-o</B>
294
295option) by sending a
296<B>SIGUSR2</B>
297
298signal to the
299<I>stapio</I>
300
301process. When it receives SIGUSR2, it will switch output file to
302new file with suffix
303<I>.N</I>
304
305where N is the sequential number.
306For example,
307<P>
308
309 $ staprun -o foo ...
310<P>
311
312outputs trace logs to
313<I>foo</I>
314
315and if it receives
316<B>SIGUSR2</B>
317
318signal, it switches output to
319<I>foo.1</I>
320
321file. And receiving
322<B>SIGUSR2</B>
323
324again, it switches to
325<I>foo.2</I>
326
327file.
328<P>
329<A NAME="lbAJ">&nbsp;</A>
330<H2>SAFETY AND SECURITY</H2>
331
332Systemtap, in the default kernel-module runtime mode, is an
333administrative tool. It exposes kernel internal data structures and
334potentially private user information. See the
335<I><A HREF="stap.1.html">stap</A></I>(1)
336
337manual page for additional information on safety and security.
338<P>
339
340To increase system security, users of systemtap must be root, or in the
341<I>staprun</I>
342
343group in order to execute this setuid
344<I>staprun</I>
345
346program.
347A user may select a particular privilege level with the stap
348<I>--privilege=</I>
349
350option, which
351<I>staprun</I>
352
353will later enforce.
354<DL COMPACT>
355<DT>stapdev<DD>
356Members of the
357<I>stapdev</I>
358
359group can write and load script modules with root-equivalent
360privileges, without particular security constraints. (Many safety
361constraints remain.)
362<DT>stapsys<DD>
363Members of the
364<I>stapsys</I>
365
366group have almost all the privileges of
367<I>stapdev</I>,
368
369except for guru mode constructs.
370<DT>staprun<DD>
371Members only of the
372<I>stapusr</I>
373
374group may any-privileged modules placed into the /lib/modules/VERSION/systemtap
375by the system administrator.
376<DT>staprun<DD>
377Members only of the
378<I>stapusr</I>
379
380group may also write and load low-privilege script modules, which are normally
381limited to manipulating their own processes (and not the kernel nor other users'
382processes).
383</DL>
384<P>
385
386Part of the privilege enforcement mechanism may require using a
387stap-server and administrative trust in its cryptographic signer; see the
388<I><A HREF="stap-server.8.html">stap-server</A></I>(8)
389
390manual page for a for more information.
391<A NAME="lbAK">&nbsp;</A>
392<H2>FILES</H2>
393
394<DL COMPACT>
395<DT>/lib/modules/VERSION/systemtap<DD>
396If MODULE is a module name, the module will be looked for in this directory.
397Users who are only in the
398<I>'stapusr'</I>
399
400group can install modules
401located in this directory. This directory must be owned by the root
402user and not be world writable.
403</DL>
404<A NAME="lbAL">&nbsp;</A>
405<H2>SEE ALSO</H2>
406
407<I><A HREF="stap.1.html">stap</A></I>(1),
408
409<I><A HREF="stapprobes.3stap.html">stapprobes</A></I>(3stap),
410
411<I><A HREF="stap-server.8.html">stap-server</A></I>(8),
412
413<I><A HREF="stapdyn.8.html">stapdyn</A></I>(8),
414
415<I><A HREF="stapex.3stap.html">stapex</A></I>(3stap)
416
417<P>
418<A NAME="lbAM">&nbsp;</A>
419<H2>BUGS</H2>
420
421Use the Bugzilla link of the project web page or our mailing list.
422
423<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>, <B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
424
425
426<P>
427<P>
428
429<HR>
430<A NAME="index">&nbsp;</A><H2>Index</H2>
431<DL>
432<DT><A HREF="#lbAB">NAME</A><DD>
433<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
434<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
435<DT><A HREF="#lbAE">OPTIONS</A><DD>
436<DT><A HREF="#lbAF">ARGUMENTS</A><DD>
437<DT><A HREF="#lbAG">EXAMPLES</A><DD>
438<DT><A HREF="#lbAH">MODULE DETACHING AND ATTACHING</A><DD>
439<DT><A HREF="#lbAI">FILE SWITCHING BY SIGNAL</A><DD>
440<DT><A HREF="#lbAJ">SAFETY AND SECURITY</A><DD>
441<DT><A HREF="#lbAK">FILES</A><DD>
442<DT><A HREF="#lbAL">SEE ALSO</A><DD>
443<DT><A HREF="#lbAM">BUGS</A><DD>
444</DL>
445<HR>
446This document was created by
447<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
448using the manual pages.<BR>
449Time: 18:00:00 GMT, May 16, 2014
450</BODY>
451</HTML>
diff --git a/man/stapsh.8.html b/man/stapsh.8.html
new file mode 100644
index 00000000..630d7383
--- /dev/null
+++ b/man/stapsh.8.html
@@ -0,0 +1,64 @@
1
2<HTML><HEAD><TITLE>Manpage of STAPSH</TITLE>
3</HEAD><BODY>
4<H1>STAPSH</H1>
5Section: Maintenance Commands (8)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stapsh
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>SYNOPSIS</H2>
15
16<P>
17<BR>
18
19<B>stapsh</B>
20
21<P>
22<A NAME="lbAD">&nbsp;</A>
23<H2>DESCRIPTION</H2>
24
25<P>
26The stapsh executable is used by the stap
27<I>--remote</I>
28
29functionality, as a wrapper shell on the remote machines.
30It is not intended to be run directly by users.
31<P>
32<A NAME="lbAE">&nbsp;</A>
33<H2>SEE ALSO</H2>
34
35
36<PRE>
37<I><A HREF="stap.1.html">stap</A></I>(1)
38
39</PRE><A NAME="lbAF">&nbsp;</A>
40<H2>BUGS</H2>
41
42Use the Bugzilla link of the project web page or our mailing list.
43
44<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>,<B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
45
46
47<P>
48
49<HR>
50<A NAME="index">&nbsp;</A><H2>Index</H2>
51<DL>
52<DT><A HREF="#lbAB">NAME</A><DD>
53<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
54<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
55<DT><A HREF="#lbAE">SEE ALSO</A><DD>
56<DT><A HREF="#lbAF">BUGS</A><DD>
57</DL>
58<HR>
59This document was created by
60<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
61using the manual pages.<BR>
62Time: 18:00:00 GMT, May 16, 2014
63</BODY>
64</HTML>
diff --git a/man/stapvars.3stap.html b/man/stapvars.3stap.html
new file mode 100644
index 00000000..a0f10e03
--- /dev/null
+++ b/man/stapvars.3stap.html
@@ -0,0 +1,95 @@
1
2<HTML><HEAD><TITLE>Manpage of STAPVARS</TITLE>
3</HEAD><BODY>
4<H1>STAPVARS</H1>
5Section: Misc. Reference Manual Pages (3stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11stapvars - systemtap variables
12<P>
13<A NAME="lbAC">&nbsp;</A>
14<H2>DESCRIPTION</H2>
15
16The following sections enumerate the public variables provided by
17standard tapsets installed, (the installation path is show in the
18stappaths (7) manual page). Each variable is described with a
19type, and its behavior/restrictions.
20The syntax is the same as printed with the
21<I>stap</I> option <I>-p2</I>.
22
23Examples:
24<P>
25<DL COMPACT>
26<DT>example1:long<DD>
27Variable &quot;example1&quot; contains an integer.
28<P>
29<DT>example2:string [long]<DD>
30Variable &quot;example2&quot; is an array of strings, indexed by integers.
31<P>
32</DL>
33<A NAME="lbAD">&nbsp;</A>
34<H3>ARGV</H3>
35
36<P>
37<DL COMPACT>
38<DT>argc:long<DD>
39Contains the value of the
40
41$#
42value: the number of command line arguments passed to the systemtap script.
43It is initialized with an implicit begin(-1) probe.
44<P>
45<DT>argv:string [long]<DD>
46Contains each command line argument as a string. argv[1] will equal @1 if
47there was at least one command line argument. Arguments beyond #32 are not
48transcribed, and produce a warning message within the begin(-1) probe that
49initializes this array.
50<P>
51</DL>
52<A NAME="lbAE">&nbsp;</A>
53<H3>NULL</H3>
54
55<P>
56<DL COMPACT>
57<DT>NULL:long<DD>
58Simply defined as the number 0.
59<P>
60</DL>
61<A NAME="lbAF">&nbsp;</A>
62<H2>FILES</H2>
63
64<DL COMPACT>
65<DT>More files and their corresponding paths can be found in the stappaths (7) manual page.<DD>
66<P>
67</DL>
68<A NAME="lbAG">&nbsp;</A>
69<H2>SEE ALSO</H2>
70
71
72<PRE>
73<I><A HREF="stap.1.html">stap</A></I>(1)
74<I><A HREF="stappaths.7.html">stappaths</A></I>(7)
75
76</PRE>
77<HR>
78<A NAME="index">&nbsp;</A><H2>Index</H2>
79<DL>
80<DT><A HREF="#lbAB">NAME</A><DD>
81<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
82<DL>
83<DT><A HREF="#lbAD">ARGV</A><DD>
84<DT><A HREF="#lbAE">NULL</A><DD>
85</DL>
86<DT><A HREF="#lbAF">FILES</A><DD>
87<DT><A HREF="#lbAG">SEE ALSO</A><DD>
88</DL>
89<HR>
90This document was created by
91<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
92using the manual pages.<BR>
93Time: 17:59:59 GMT, May 16, 2014
94</BODY>
95</HTML>
diff --git a/man/systemtap.8.html b/man/systemtap.8.html
new file mode 100644
index 00000000..5251cc44
--- /dev/null
+++ b/man/systemtap.8.html
@@ -0,0 +1,784 @@
1
2<HTML><HEAD><TITLE>Manpage of SYSTEMTAP</TITLE>
3</HEAD><BODY>
4<H1>SYSTEMTAP</H1>
5Section: Maintenance Commands (8)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11systemtap - SystemTap initscript service
12<P>
13
14
15
16<P>
17<A NAME="lbAC">&nbsp;</A>
18<H2>SYNOPSIS</H2>
19
20<B>service systemtap</B>
21
22<I>COMMAND</I> [<I>OPTIONS</I>] [<I>SCRIPT</I>...]
23
24<P>
25<A NAME="lbAD">&nbsp;</A>
26<H2>DESCRIPTION</H2>
27
28The SystemTap initscript aims to provide a way to run scripts as a service and
29easily control them individually. Scripts can be configured to start upon manual
30request, or during system startup. On dracut-based systems, it is also possible
31to integrate scripts in the initramfs and have them start during early-boot.
32<P>
33There are various parameters and options available to modify global behaviour,
34as well as script behaviour. Dependencies between scripts can be established so
35that starting one starts others (especially convenient when using the
36-DRELAY_HOST and -DRELAY_GUEST options of <I><A HREF="stap.1.html">stap</A></I>(1)).
37<P>
38The configuration file of the initscript is located at
39<B>${prefix}/etc/systemtap/config</B>. Acceptable parameters are detailed in the
40GLOBAL PARAMETERS section.
41<P>
42Scripts must be placed in the <B>${prefix}/etc/systemtap/script.d</B> directory
43and must have a <B>.stp</B> extension. When referring to them on the command-line
44however, there in no need to include the <B>.stp</B> extension. The scripts
45directory may be changed by setting the SCRIPT_PATH parameter in the
46configuration file.
47<P>
48<A NAME="lbAE">&nbsp;</A>
49<H2>COMMANDS</H2>
50
51One of the commands below must be specified:
52<P>
53<DL COMPACT>
54<DT><B>start</B>
55
56<DD>
57Start <I>SCRIPT</I>s. If no scripts are specified, start the scripts specified by
58the DEFAULT_START configuration. If DEFAULT_START is not set, start all scripts
59in the script directory. For scripts already started, the command is ignored.
60The command will fail if the scripts fail to start (see also the PASSALL
61configuration).
62<P>
63If the AUTOCOMPILE configuration is on, the command will try to compile or
64update the specified scripts when one of the below conditions is true:
65<DL COMPACT><DT><DD>
66<DL COMPACT>
67<DT>-<DD>
68The compiled cache file does not exist.
69<DT>-<DD>
70The mtime (modified timestamp) of the original script file is newer than the
71time of the compiled script cache.
72<DT>-<DD>
73The specified stap options used to compile the script has been changed (see
74also the SCRIPT PARAMETERS section).
75<DT>-<DD>
76The result of `uname -a` has been changed.
77</DL>
78</DL>
79
80<P>
81<DT><B>stop</B>
82
83<DD>
84Stop <I>SCRIPT</I>s. If no scripts are specified, stop all running scripts. For
85scripts already stopped, the command is ignored. The command will fail if the
86scripts fail to stop (see also the PASSALL configuration).
87<P>
88<DT><B>restart</B>
89
90<DD>
91Stop and start <I>SCRIPT</I>s.
92<P>
93<DT><B>status</B>
94
95<DD>
96Show the state of <I>SCRIPT</I>s and their dependencies.
97<P>
98<DT><B>compile</B>
99
100<DD>
101Compile <I>SCRIPT</I>s but do not start them. If the scripts have already been
102compiled, prompt for confirmation before overwriting cache. Compile for the
103current kernel, or the kernel release specified by the <B>-r</B> option.
104<P>
105<DT><B>onboot</B>
106
107<DD>
108Make <I>SCRIPT</I>s part of the initramfs so that they are started earlier during
109the boot process. This command is only available on dracut-based systems. If no
110scripts are specified, create a normal initramfs devoid of any SystemTap files.
111<P>
112The initramfs is created for the current kernel, or the kernel release specified
113by the <B>-r</B> option. The path of the created initramfs defaults to
114<B>/boot/initramfs-KVER.img</B>, where KVER is the output of `uname -r`. The
115bootloader is also updated (using <I><A HREF="new-kernel-pkg.8.html">new-kernel-pkg</A></I>(8)) to make the kernel
116entry use the new initramfs file. Use the <B>-o</B> option to specify a different
117path (the bootloader will not be updated).
118<P>
119If the output file already exists, it is overwritten, unless the <B>-b</B> switch
120is given, in which case the file is appended <B>.bak</B> rather than overwritten.
121However, if there is already a <B>.bak</B> version of the file, the backup will
122not be overwritten.
123<P>
124WARNING: do not use the <B>-o</B> option of <I><A HREF="stap.1.html">stap</A></I>(1) with onboot scripts
125because the script is started before the root filesystem is even mounted.
126Increase the buffer size if more space is needed.
127<P>
128<DT><B>cleanup</B>
129
130<DD>
131Delete the compiled <I>SCRIPT</I>s from cache. If no scripts are specified, then
132all compiled scripts are deleted. Only the cache for the current kernel is
133deleted, or the kernel release specified by the <B>-r</B> option. Prompt for
134confirmation before deleting.
135<P>
136</DL>
137<A NAME="lbAF">&nbsp;</A>
138<H2>OPTIONS</H2>
139
140Many of the commands can also take options. However, since users can't pass
141these options on boot, they are only meant for managing scripts after boot and
142for testing. Available options are:
143<P>
144<DL COMPACT>
145<DT><B>-c </B><I>CONFIG_FILE</I>
146
147<DD>
148Specify a different configuration file in place of the default one.
149<P>
150<DT><B>-R</B>
151
152<DD>
153When using the <B>start</B> and <B>stop</B> commands, also include the scripts'
154dependencies (recursively).
155<P>
156<DT><B>-r </B><I>KERNEL_RELEASE</I>
157
158<DD>
159When using the <B>compile</B>, <B>onboot</B>, and <B>cleanup</B> commands, specify
160the target kernel version rather than using the current one. Must be in the same
161format as `uname -r`.
162<P>
163<DT><B>-y</B>
164
165<DD>
166Answer yes for all prompts.
167<P>
168<DT><B>-o </B><I>PATH.IMG</I>
169
170<DD>
171When using the <B>onboot</B> command, specify the output path of the created
172initramfs. When specified, the bootloader configuration is not updated.
173<P>
174<DT><B>-b</B>
175
176<DD>
177When using the <B>onboot</B> command, backup an existing initramfs image by
178adding a <B>.bak</B> extension rather than overwriting it. Without this option,
179the initramfs is overwritten.
180<P>
181</DL>
182<A NAME="lbAG">&nbsp;</A>
183<H2>GLOBAL PARAMETERS</H2>
184
185These parameters affect the general behaviour of the SystemTap initscript
186service. They can be specified in the configuration file.
187<P>
188<DL COMPACT>
189<DT><B>SCRIPT_PATH</B>
190
191<DD>
192Specify the absolute path of the script directory. These are the scripts on
193which the initscript can operate. Scripts must have the <B>.stp</B> extension.
194The default path is <B>${prefix}/etc/systemtap/script.d</B>.
195<P>
196<DT><B>CONFIG_PATH</B>
197
198<DD>
199Specify the absolute path of the script configuration directory. These
200configuration files contain options for specific scripts. They must have the
201<B>.conf</B> extension. The default path is <B>${prefix}/etc/systemtap/conf.d</B>.
202<P>
203<DT><B>CACHE_PATH</B>
204
205<DD>
206Specify the absolute path of the cache directory. The default path is
207<B>${prefix}/var/cache/systemtap</B>.
208<P>
209<DT><B>TEMP_PATH</B>
210
211<DD>
212Specify the absolute path of the temporary directory in which SystemTap
213makes temporary directories to compile scripts. The default path is <B>/tmp</B>.
214<P>
215<DT><B>STAT_PATH</B>
216
217<DD>
218Specify the absolute path of the directory containing PID files used to track
219the status of SystemTap scripts. The default path is
220<B>${prefix}/var/run/systemtap</B>.
221<P>
222<DT><B>LOG_FILE</B>
223
224<DD>
225Specify the absolute path of the log file. All messages are sent to this file,
226including compilation and runtime errors. The default path is
227<B>${prefix}/var/log/systemtap.log</B>.
228<P>
229<DT><B>PASSALL</B>
230
231<DD>
232If this is set <B>yes</B>, initscript commands that operate on multiple scripts
233will report as failed when the action could not be performed on at least one
234script. If set to <B>no</B>, only a warning is emitted. The default is <B>yes</B>.
235<P>
236<DT><B>RECURSIVE</B>
237
238<DD>
239If this is set <B>yes</B>, the initscript will always follow script dependencies
240recursively. This means that there is no need to specify the <B>-R</B> option.
241This flag is effective only if you specify script(s) from the command-line. The
242default is <B>no</B>.
243<P>
244<DT><B>AUTOCOMPILE</B>
245
246<DD>
247If this is set <B>yes</B>, the initscript automatically tries to compile
248specified scripts when needed if there is no valid cache. Otherwise, the related
249command simply fails. The default is <B>yes</B>.
250<P>
251<DT><B>DEFAULT_START</B>
252
253<DD>
254Specify scripts which will be started by default. If omitted (or empty), all
255scripts in the script directory will be started. The default is <B>&quot;&quot;</B>.
256<P>
257<DT><B>ALLOW_CACHEONLY</B>
258
259<DD>
260If this is set <B>yes</B>, the initscript will also allow operating on scripts
261that are located in the cache directory, but not in the script directory. The
262default is <B>no</B>.
263<P>
264WARNING: the initscript may load unexpected obsolete caches with this option.
265The cache directory should be checked before enabling this option.
266<P>
267<DT><B>LOG_BOOT_ERR</B>
268
269<DD>
270Because boot-time scripts are run before the root filesystem is mounted,
271staprun's stderr cannot be logged to the LOG_FILE as usual. However, the log
272can instead be output to /var/run/systemtap/$script.log by setting LOG_BOOT_ERR
273to <B>yes</B>. If STAT_PATH is different from the default, the log files will be
274moved there upon executing any of the initscript commands. The default is
275<B>no</B>.
276<P>
277</DL>
278<P>
279
280Here is a global configuration file example:
281
282<P>
283
284<BR>
285
286<DL COMPACT><DT><DD>
287<PRE>
288SCRIPT_PATH=/var/systemtap/script.d/
289PASSALL=yes
290RECURSIVE=no
291
292</PRE>
293
294</DL>
295
296
297<P>
298
299<P>
300<A NAME="lbAH">&nbsp;</A>
301<H2>SCRIPT PARAMETERS</H2>
302
303These parameters affect the compilation or runtime behaviour of specific
304SystemTap scripts. They must be placed in config files located in the
305CONFIG_PATH directory.
306<P>
307<DL COMPACT>
308<DT><B>&lt;SCRIPT&gt;_OPT</B>
309
310<DD>
311Specify options passed to the <I><A HREF="stap.1.html">stap</A></I>(1) command for the SCRIPT. Here, SCRIPT
312is the name of the script file without the <B>.stp</B> extension. Note that the
313<B>-F</B> option is always added.
314<P>
315The following options are ignored when compiling scripts: -p, -m, -r, -c, -x,
316-e, -s, -o, -h, -V, -k.
317<P>
318The following options are ignored when running starting scripts: -h, -V, -v, -t,
319-p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u, -q, -w, -l, -d, -L, -F, and all
320long options.
321<P>
322<DT><B>&lt;SCRIPT&gt;_REQ</B>
323
324<DD>
325Specify script dependencies (i.e. which script this script requires). For
326example, if foo.stp requires (or needs to run after) bar.stp, set
327
328<P>
329
330<BR>
331
332<DL COMPACT><DT><DD>
333<PRE>
334foo_REQ=&quot;bar&quot;
335
336</PRE>
337
338</DL>
339
340
341<P>
342
343Specify multiple scripts by separating their names by spaces.
344<P>
345</DL>
346<P>
347
348Here is a script configuration file example:
349
350<P>
351
352<BR>
353
354<DL COMPACT><DT><DD>
355<PRE>
356script1_OPT=&quot;-o /var/log/script1.out -DRELAY_HOST=group1&quot;
357script2_OPT=&quot;-DRELAY_GUEST=group1&quot;
358script2_REQ=&quot;script1&quot;
359
360</PRE>
361
362</DL>
363
364
365<P>
366
367<P>
368<A NAME="lbAI">&nbsp;</A>
369<H2>EXAMPLES</H2>
370
371<P>
372<DL COMPACT>
373<DT><B>INSTALLING SCRIPTS</B>
374
375<DD>
376We first copy a SystemTap script (e.g. &quot;script1.stp&quot;) into the script directory:
377
378<P>
379
380<BR>
381
382<DL COMPACT><DT><DD>
383<PRE>
384<B>#</B> cp script1.stp /etc/systemtap/script.d/
385
386</PRE>
387
388</DL>
389
390
391<P>
392
393We can then set any script options, for example:
394
395<P>
396
397<BR>
398
399<DL COMPACT><DT><DD>
400<PRE>
401<B>#</B> vi /etc/systemtap/conf.d/group1
402script1_OPT=&quot;-o /var/log/group1.out -DRELAY_HOST=group1&quot;
403
404</PRE>
405
406</DL>
407
408
409<P>
410
411If we then install a script (e.g. &quot;script2.stp&quot;) which shares a buffer with
412script1, there is a dependency. In this case, we can do the following:
413
414<P>
415
416<BR>
417
418<DL COMPACT><DT><DD>
419<PRE>
420<B>#</B> cp script2.stp /etc/systemtap/script.d/
421<B>#</B> vi /etc/systemtap/conf.d/group1
422script2_OPT=&quot;-DRELAY_GUEST=group1&quot;
423script2_REQ=&quot;script1&quot;
424
425</PRE>
426
427</DL>
428
429
430<P>
431
432This way, if <I><A HREF="stap.1.html">stap</A></I>(1) fails to run script1, the initscript will not even
433try to run script2.
434<P>
435<DT><B>TESTING</B>
436
437<DD>
438After installing scripts, we can test that they work by simply doing:
439
440<P>
441
442<BR>
443
444<DL COMPACT><DT><DD>
445<PRE>
446<B>#</B> service systemtap start
447<B>#</B> service systemtap stop
448
449</PRE>
450
451</DL>
452
453
454<P>
455
456We could be more specific as well, for example:
457
458<P>
459
460<BR>
461
462<DL COMPACT><DT><DD>
463<PRE>
464<B>#</B> service systemtap start script1
465<B>#</B> service systemtap stop script1
466
467</PRE>
468
469</DL>
470
471
472<P>
473
474If there were no errors, we are ready to use it.
475<P>
476<DT><B>ENABLING SERVICE</B>
477
478<DD>
479After we're satisfied with the scripts and their tests, we can enable the
480SystemTap initscript service:
481
482<P>
483
484<BR>
485
486<DL COMPACT><DT><DD>
487<PRE>
488<B>#</B> chkconfig systemtap on
489
490</PRE>
491
492</DL>
493
494
495<P>
496
497<P>
498<DT><B>DELETING SCRIPTS</B>
499
500<DD>
501Scripts are deleted by simply removing them from the script directory and
502removing any configuration lines specific to them:
503
504<P>
505
506<BR>
507
508<DL COMPACT><DT><DD>
509<PRE>
510<B>#</B> rm /etc/systemtap/script.d/script2.stp
511<B>#</B> vi /etc/systemtap/conf.d/group1
512
513</PRE>
514
515</DL>
516
517
518<P>
519
520If the script is still running, we also need to stop it:
521
522<P>
523
524<BR>
525
526<DL COMPACT><DT><DD>
527<PRE>
528<B>#</B> service systemtap stop script2
529
530</PRE>
531
532</DL>
533
534
535<P>
536
537We can then also remove the cache associated with the script:
538
539<P>
540
541<BR>
542
543<DL COMPACT><DT><DD>
544<PRE>
545<B>#</B> service systemtap cleanup script2
546
547</PRE>
548
549</DL>
550
551
552<P>
553
554<P>
555<DT><B>PREPARING FOR KERNEL UPDATES</B>
556
557<DD>
558Usually, there is nothing to do when booting into a new kernel. The initscript
559will see that the kernel version is different and will compile the scripts. The
560compilation can be done beforehand as well to avoid having to compile during
561boot by using the <B>-r</B> option:
562
563<P>
564
565<BR>
566
567<DL COMPACT><DT><DD>
568<PRE>
569<B>#</B> service systemtap compile myscript -r &lt;NEW_KERNEL_VERSION&gt;
570
571</PRE>
572
573</DL>
574
575
576<P>
577
578<P>
579<DT><B>IMPORTING COMPILED SCRIPTS</B>
580
581<DD>
582For environments which lack compilation infrastructure (e.g. no compilers or
583debuginfo), such as a production system, the scripts can be compiled on another
584(development) machine and then transferred over to the production system:
585
586<P>
587
588<BR>
589
590<DL COMPACT><DT><DD>
591<PRE>
592<B>#</B> service systemtap compile myscript -r \
593<BR>
594&gt; &lt;KERNEL_VERSION_OF_TARGET_MACHINE&gt;
595<B>#</B> tar czf stap-scripts-&lt;kernel-version&gt;.tar.gz \
596<BR>
597&gt; /var/cache/systemtap/&lt;kernel-version&gt; \
598<BR>
599&gt; /etc/systemtap/conf.d/&lt;configfile&gt;
600
601</PRE>
602
603</DL>
604
605
606<P>
607
608And then copy this package to the target machine and extract it.
609<P>
610<DT><B>STARTING SCRIPTS DURING EARLY-BOOT</B>
611
612<DD>
613The initscript also allows us to start scripts earlier during the boot process
614by creating an initramfs containing the script's module. The system must be
615dracut-based for this to work. Starting a script at this stage gives access to
616information otherwise very hard to obtain.
617<P>
618We first install the script by copying it into the script directory as usual and
619setting whatever options we'd like:
620
621<P>
622
623<BR>
624
625<DL COMPACT><DT><DD>
626<PRE>
627<B>#</B> cp myscript.stp /etc/systemtap/script.d
628<B>#</B> vi /etc/systemtap/conf.d/myscript.conf
629
630</PRE>
631
632</DL>
633
634
635<P>
636
637To add the script to the initramfs, we use the <B>onboot</B> command:
638
639<P>
640
641<BR>
642
643<DL COMPACT><DT><DD>
644<PRE>
645<B>#</B> service systemtap onboot myscript
646
647</PRE>
648
649</DL>
650
651
652<P>
653
654If the script is not already compiled and cached, it will be done at this point.
655A new initramfs will then be created at the default location. We can use the
656<B>-b</B> option to ensure that the existing initramfs is backed up. We can then
657restart the system.
658<P>
659<DT><B>USING A DIFFERENT INITRAMFS</B>
660
661<DD>
662If we would prefer to only start the script for one boot and not others, it
663might be easier to instead use the <B>-o</B> option to specify a different
664initramfs output file:
665
666<P>
667
668<BR>
669
670<DL COMPACT><DT><DD>
671<PRE>
672<B>#</B> service systemtap onboot myscript \
673&gt; -o /boot/special_initramfs.img
674
675</PRE>
676
677</DL>
678
679
680<P>
681
682Once the initramfs is created, it's simply a matter of changing the command-line
683options at boot-time so that the new image is used rather than the usual one.
684<P>
685<DT><B>CREATING AN INITRAMFS FOR A DIFFERENT KERNEL</B>
686
687<DD>
688Just like the compile command, we can use the <B>-r</B> option to specify the
689kernel for which we want to create the initramfs. This is useful when we are
690about to upgrade and would like to prepare in advance. For example:
691
692<P>
693
694<BR>
695
696<DL COMPACT><DT><DD>
697<PRE>
698<B>#</B> service systemtap onboot myscript \
699&gt; -r 3.12.6-200.fc19.x86_64
700
701</PRE>
702
703</DL>
704
705
706<P>
707
708<P>
709<DT><B>REMOVING SCRIPTS FROM THE INITRAMFS</B>
710
711<DD>
712Finally, to remove all script from the initramfs, we simple run the <B>onboot</B>
713command without specifying any scripts:
714
715<P>
716
717<BR>
718
719<DL COMPACT><DT><DD>
720<PRE>
721<B>#</B> service systemtap onboot
722
723</PRE>
724
725</DL>
726
727
728<P>
729
730This will simply create a standard initramfs without any SystemTap modules
731inserted.
732<P>
733<DT><B>TROUBLESHOOTING EARLY-BOOT ISSUES</B>
734
735<DD>
736There can be many reasons for which the module didn't insert or did not work as
737expected. It may be useful to turn on dracut debugging by adding 'rdinitdebug'
738to the kernel command-line and checking dmesg/journalctl -ae. Also, the stderr
739output of staprun can be captured by setting the LOG_BOOT_ERR option to
740<B>yes</B>.
741<P>
742</DL>
743<A NAME="lbAJ">&nbsp;</A>
744<H2>SEE ALSO</H2>
745
746<I><A HREF="stap.1.html">stap</A></I>(1)
747
748<I><A HREF="dracut.8.html">dracut</A></I>(8)
749
750<I><A HREF="new-kernel-pkg.8.html">new-kernel-pkg</A></I>(8)
751
752<P>
753<A NAME="lbAK">&nbsp;</A>
754<H2>BUGS</H2>
755
756Use the Bugzilla link of the project web page or our mailing list.
757
758<B><A HREF="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</A></B>, <B>&lt;<A HREF="mailto:systemtap@sourceware.org">systemtap@sourceware.org</A>&gt;</B>.
759
760
761<P>
762<P>
763
764<HR>
765<A NAME="index">&nbsp;</A><H2>Index</H2>
766<DL>
767<DT><A HREF="#lbAB">NAME</A><DD>
768<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
769<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
770<DT><A HREF="#lbAE">COMMANDS</A><DD>
771<DT><A HREF="#lbAF">OPTIONS</A><DD>
772<DT><A HREF="#lbAG">GLOBAL PARAMETERS</A><DD>
773<DT><A HREF="#lbAH">SCRIPT PARAMETERS</A><DD>
774<DT><A HREF="#lbAI">EXAMPLES</A><DD>
775<DT><A HREF="#lbAJ">SEE ALSO</A><DD>
776<DT><A HREF="#lbAK">BUGS</A><DD>
777</DL>
778<HR>
779This document was created by
780<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
781using the manual pages.<BR>
782Time: 18:00:00 GMT, May 16, 2014
783</BODY>
784</HTML>
diff --git a/man/warning::debuginfo.7stap.html b/man/warning::debuginfo.7stap.html
new file mode 100644
index 00000000..def32ccd
--- /dev/null
+++ b/man/warning::debuginfo.7stap.html
@@ -0,0 +1,178 @@
1
2<HTML><HEAD><TITLE>Manpage of WARNING::DEBUGINFO</TITLE>
3</HEAD><BODY>
4<H1>WARNING::DEBUGINFO</H1>
5Section: Misc. Reference Manual Pages (7stap)<BR><A HREF="#index">Index</A>
6<A HREF="index.html">Return to Main Contents</A><HR>
7
8<A NAME="lbAB">&nbsp;</A>
9<H2>NAME</H2>
10
11warning::debuginfo - systemtap missing-debuginfo warnings
12<P>
13
14
15
16<P>
17<A NAME="lbAC">&nbsp;</A>
18<H2>DESCRIPTION</H2>
19
20For many symbolic probing operations, systemtap needs DWARF debuginfo for
21the relevant binaries. This often includes resolving function/statement
22probes, or $context variables in related handlers. DWARF debuginfo may
23be found in the original binaries built during compilation, or may have
24been split into separate files. The
25<I>SYSTEMTAP_DEBUGINFO_PATH</I>
26
27environment variable affects where systemtap looks for these files.
28<P>
29
30If your operating system came from a distributor, check with them if
31debuginfo packages or variants are available. If your distributor does
32not have debuginfo-equipped binaries at all, you may need to rebuild it.
33<P>
34
35Systemtap uses the
36<I>elfutils</I>
37
38library to process ELF/DWARF files. The version of elfutils used by systemtap
39is the number after the slash in the
40<I>-V</I>
41
42output:
43
44<P>
45
46<BR>
47
48<DL COMPACT><DT><DD>
49<PRE>
50% stap -V
51Systemtap translator/driver (version 2.3/0.156, rpm 2.3-1.fc19)
52Copyright (C) 2005-2014 Red Hat, Inc. and others
53[...]
54
55</PRE>
56
57</DL>
58
59
60<P>
61
62This indicates systemtap version 2.3 with elfutils version 0.156.
63<P>
64<DL COMPACT>
65<DT>kernel debuginfo<DD>
66For scripts that target the kernel, systemtap may search for the
67<I>vmlinux</I>
68
69file created during its original build. This is distinct from the
70boot-loader's compressed/stripped
71<I>vmlinuz</I>
72
73file, and much larger. If you have a hand-built kernel, make sure
74it was built with the
75<I>CONFIG_DEBUG_INFO=y</I>
76
77option.
78<P>
79<DT>process debuginfo<DD>
80For scripts that target user-space, systemtap may search for debuginfo.
81If you have hand-built binaries, use
82<I>CFLAGS=-g -O2</I>
83
84to compile them.
85<P>
86<DT>minidebuginfo<DD>
87On some systems, binaries may be compiled with a subset of debuginfo
88useful for function tracing and backtraces. This 'Minidebuginfo' is
89a xz compressed section labeled .gnu_debugdata. Support for
90minidebuginfo relies on elfutils version 0.156 or later.
91<P>
92<DT>compressed debuginfo<DD>
93On some systems, debuginfo may be available, but compressed into
94<I>.zdebug_*</I>
95
96sections. Support for compressed debuginfo relies on elfutils
97version 0.153 or later.
98<P>
99<DT>unnecessary debuginfo<DD>
100In some cases, a script may be altered to avoid requiring debuginfo.
101For example, as script that uses
102<I>probe syscall.*</I>
103
104probes could try instead
105<I>probe nd_syscall.*</I>
106
107(for non-DWARF syscall): these work similarly, and use more intricate
108(fragile) tapset functions to extract system call arguments. Another
109option is use of compiled-in instrumentation such as kernel tracepoints
110or user-space
111<I>&lt;<A HREF="file:///usr/include/sys/sdt.h">sys/sdt.h</A>&gt;</I>
112
113markers in libraries or executables, which do not require debuginfo.
114If debuginfo was required for resolving a complicated
115<I>$var-&gt;foo-&gt;bar</I>
116
117expression, it may be possible to use
118<I>@cast(var,foo,foo.h)-&gt;foo-&gt;bar</I>
119
120to synthesize debuginfo for that type from a header file.
121<P>
122</DL>
123<A NAME="lbAD">&nbsp;</A>
124<H2>AUTOMATION</H2>
125
126<P>
127On some platforms, systemtap may advise what commands to run, in order
128to download needed debuginfo. Another possibility is to invoke systemtap
129with the
130<I>--download-debuginfo</I>
131
132flag.
133The
134<I>stap-prep</I>
135
136script included with systemtap may be able to download the
137appropriate kernel debuginfo. Another possibility is to install and
138use a
139<I>stap-server</I>
140
141remote-compilation instance on a machine on your network, where
142debuginfo and compilation resources can be centralized. Try the
143<I>stap --use-server</I>
144
145option, in case such a server is already running.
146<P>
147<A NAME="lbAE">&nbsp;</A>
148<H2>SEE ALSO</H2>
149
150
151<PRE>
152<I><A HREF="stap.1.html">stap</A></I>(1),
153<I><A HREF="stappaths.7.html">stappaths</A></I>(7),
154<I><A HREF="stap-server.8.html">stap-server</A></I>(8),
155<I><A HREF="stap-prep.1.html">stap-prep</A></I>(1),
156<I><A HREF="strip.1.html">strip</A></I>(1),
157<I><A HREF="./error::dwarf.7stap.html">error::dwarf</A></I>(7stap),
158<I><A HREF="./error::reporting.7stap.html">error::reporting</A></I>(7stap),
159<I><A HREF="./error::contextvars.7stap.html">error::contextvars</A></I>(7stap),
160<I><A HREF="http://fedorahosted.org/elfutils">http://fedorahosted.org/elfutils</A></I>,
161<I><A HREF="http://fedoraproject.org/wiki/Features/MiniDebugInfo">http://fedoraproject.org/wiki/Features/MiniDebugInfo</A></I>
162
163</PRE>
164<HR>
165<A NAME="index">&nbsp;</A><H2>Index</H2>
166<DL>
167<DT><A HREF="#lbAB">NAME</A><DD>
168<DT><A HREF="#lbAC">DESCRIPTION</A><DD>
169<DT><A HREF="#lbAD">AUTOMATION</A><DD>
170<DT><A HREF="#lbAE">SEE ALSO</A><DD>
171</DL>
172<HR>
173This document was created by
174<A HREFhttp://www.kapiti.co.nz/michael/vhman2html.html">man2html</A>,
175using the manual pages.<BR>
176Time: 18:00:00 GMT, May 16, 2014
177</BODY>
178</HTML>
generated by cgit (git 2.34.1) at 2025-10-31 14:39:57 +0000