Debian Codegraph @

doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml

raw
1 <?xml version='1.0'?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3 ]>
4
5 <section id="scriptconstructions">
6 <title>Basic SystemTap Handler Constructs</title>
7 <indexterm>
8 <primary>handlers</primary>
9 <secondary>SystemTap handler constructs</secondary>
10 </indexterm>
11
12 <indexterm>
13 <primary>SystemTap handlers</primary>
14 <secondary>SystemTap handler constructs</secondary>
15 </indexterm>
16
17 <!-- next 2 indexterms for syntax and format -->
18
19 <indexterm>
20 <primary>handlers</primary>
21 <secondary>SystemTap handler constructs</secondary>
22 <tertiary>syntax and format</tertiary>
23 </indexterm>
24
25 <indexterm>
26 <primary>SystemTap handlers</primary>
27 <secondary>SystemTap handler constructs</secondary>
28 <tertiary>syntax and format</tertiary>
29 </indexterm>
30
31 <indexterm>
32 <primary>syntax and format</primary>
33 <secondary>SystemTap handler constructs</secondary>
34 <tertiary>handlers</tertiary>
35 </indexterm>
36 <para>SystemTap supports the use of several basic constructs in handlers. The syntax for most of these handler constructs are mostly based on C and <command>awk</command> syntax. This section describes several of the most useful SystemTap handler constructs, which should provide you with enough information to write simple yet useful SystemTap scripts.</para>
37
38 <section id="variablesconstructs">
39 <title>Variables</title>
40 <!-- next 3 indexterms for variables -->
41 <indexterm>
42 <primary>handlers</primary>
43 <secondary>SystemTap handler constructs</secondary>
44 <tertiary>variables</tertiary>
45 </indexterm>
46
47 <indexterm>
48 <primary>SystemTap statements</primary>
49 <secondary>SystemTap handler constructs</secondary>
50 <tertiary>variables</tertiary>
51 </indexterm>
52
53 <indexterm>
54 <primary>variables</primary>
55 <secondary>SystemTap handler constructs</secondary>
56 <tertiary>handlers</tertiary>
57 </indexterm>
58
59 <indexterm>
60 <primary>format and syntax</primary>
61 <secondary>SystemTap handler constructs</secondary>
62 <tertiary>handlers</tertiary>
63 </indexterm>
64 <para>Variables can be used freely throughout a handler; simply choose a
65 name, assign a value from a function or expression to it, and use it in an expression. SystemTap automatically identifies whether a variable should be typed as a string or integer, based on the type of the values assigned to it. For instance, if you use set the variable <command>foo</command> to <command>gettimeofday_s()</command> (as in <command>foo = gettimeofday_s()</command>), then <command>foo</command> is typed as a number and can be printed in a <command>printf()</command> with the integer format specifier (<command>%d</command>).</para>
66
67 <!-- next 2 indexterms for <command>global</command> -->
68
69 <indexterm>
70 <primary>handlers</primary>
71 <secondary>SystemTap handler constructs</secondary>
72 <tertiary><command>global</command></tertiary>
73 </indexterm>
74
75 <indexterm>
76 <primary>SystemTap statements</primary>
77 <secondary>SystemTap handler constructs</secondary>
78 <tertiary><command>global</command></tertiary>
79 </indexterm>
80
81 <indexterm>
82 <primary><command>global</command></primary>
83 <secondary>SystemTap handler constructs</secondary>
84 <tertiary>handlers</tertiary>
85 </indexterm>
86 <para>Note, however, that by default variables are only local to the probe they are used in. This means that variables are initialized, used and disposed at each probe handler invocation. To share a variable between probes, declare the variable name using <command>global</command> outside of the probes. Consider the following example:</para>
87
88 <example id="timerjiffies">
89 <title>timer-jiffies.stp</title>
90 <programlisting>global count_jiffies, count_ms
91 probe timer.jiffies(100) { count_jiffies ++ }
92 probe timer.ms(100) { count_ms ++ }
93 probe timer.ms(12345)
94 {
95 hz=(1000*count_jiffies) / count_ms
96 printf ("jiffies:ms ratio %d:%d => CONFIG_HZ=%d\n",
97 count_jiffies, count_ms, hz)
98 exit ()
99 }</programlisting>
100 </example>
101
102 <indexterm>
103 <primary><command>CONFIG_HZ, computing for</command></primary>
104 </indexterm>
105
106 <para><xref linkend="timerjiffies"/> computes the <command>CONFIG_HZ</command> setting of the kernel using timers that count jiffies and milliseconds, then computing accordingly. The <command>global</command> statement allows the script to use the variables <command>count_jiffies</command> and <command>count_ms</command> (set in their own respective probes) to be shared with <command>probe timer.ms(12345)</command>.</para>
107
108 <note>
109 <title>Note</title>
110 <para>The <command>++</command> notation in <xref linkend="timerjiffies"/> (that is, <command>count_jiffies ++</command> and <command>count_ms ++</command>) is used to increment the value of a variable by 1. In the following probe, <command>count_jiffies</command> is incremented by 1 every 100 jiffies:</para>
111 <screen>probe timer.jiffies(100) { count_jiffies ++ }</screen>
112 <para>In this instance, SystemTap understands that <command>count_jiffies</command> is an integer. Because no initial value was assigned to <command>count_jiffies</command>, its initial value is zero by default.</para>
113 </note>
114 <!--
115 <note>
116 <title>Note</title>
117 <para>In some cases, such as in <xref linkend="timerjiffies"/>, a variable may be declared without any specific value as yet. You need to declare such values as integers using the notation <command>++</command>.</para>
118 </note>
119 -->
120 </section>
121
122 <section id="targetvariables">
123 <title>Target Variables</title>
124
125 <indexterm>
126 <primary>handlers</primary>
127 <secondary>target variables</secondary>
128 </indexterm>
129
130 <indexterm>
131 <primary>target variables</primary>
132 </indexterm>
133
134 <para>
135 The probe events that map to actual locations in the code (for example
136 <command>kernel.function("<replaceable>function</replaceable>")</command> and
137 <command>kernel.statement("<replaceable>statement</replaceable>")</command>)
138 allow the use of <emphasis>target variables</emphasis> to obtain the value of
139 variables visible at that location in the code.
140 You can use the <command>-L</command> option to list the target variable available at a
141 probe point.
142 If the debug information is installed for the running kernel,
143 you can run the following command to find out what target variables
144 are available for the <command>vfs_read</command> function:
145 </para>
146
147 <screen>stap -L 'kernel.function("vfs_read")'</screen>
148
149 <para>
150 This will yield something similar to the following:
151 </para>
152
153 <screen>kernel.function("vfs_read@fs/read_write.c:277") $file:struct file* $buf:char* $count:size_t $pos:loff_t*</screen>
154
155 <para>
156 Each target variable is proceeded by a <quote><command>$</command></quote> and
157 the type of the target variable follows the <quote><command>:</command></quote>.
158 The kernel's <command>vfs_read</command> function has
159 <command>$file</command> (pointer to structure describing the file),
160 <command>$buf</command> (pointer to the user-space memory to store the read data),
161 <command>$count</command> (number of bytes to read),
162 and <command>$pos</command> (position to start reading from in the file)
163 target variables at the entry to the function.
164 </para>
165
166 <para>
167 When a target variable is not local to the probe point, like a global
168 external variable or a file local static variable defined in another file
169 then it can be referenced through
170 <quote><command>@var("<replaceable>varname</replaceable>@<replaceable>src/file.c</replaceable>")</command></quote>.
171 </para>
172
173 <para>
174 It is also supported to specify an executable or library file path as the
175 second argument, as in
176 <quote><command>@var("<replaceable>varname</replaceable>", "<replaceable>/path/to/exe/or/lib</replaceable>")</command></quote>
177 </para>
178
179 <para>
180 SystemTap tracks the typing information of the target variable and can
181 examine the fields of a structure with the <command>-></command> operator.
182 The <command>-></command> operator can be chained to look at data structures
183 contained within data structures and follow pointers to other data structures.
184 The <command>-></command> operator will obtain the value in the field of the
185 structure.
186 The <command>-></command> operator is used regardless whether accessing a field
187 in a substructure or accessing another structure through a pointer.
188 </para>
189
190 <para>
191 For example to access a field of the static files_stat target variable
192 defined in fs/file_table.c (which holds some of the current file system
193 sysctl tunables), one could write:
194 </para>
195
196 <screen>
197 stap -e 'probe kernel.function("vfs_read") {
198 printf ("current files_stat max_files: %d\n",
199 @var("files_stat@fs/file_table.c")->max_files);
200 exit(); }'
201 </screen>
202
203 <para>
204 Which will yield something similar to the following:
205 </para>
206
207 <screen>
208 current files_stat max_files: 386070
209 </screen>
210
211 <para>
212 For pointers to base types such as integers and strings
213 there are a number of functions listed below to access kernel-space data.
214 The first argument for each functions is the pointer to the data item.
215 Similar functions are described in <xref linkend="utargetvariable"/> for
216 accessing target variables in user-space code.
217 </para>
218
219 <variablelist>
220
221 <varlistentry>
222 <term>kernel_char(<replaceable>address</replaceable>)</term>
223 <listitem>
224 <para>
225 Obtain the character at <replaceable>address</replaceable> from kernel memory.
226 </para>
227 </listitem>
228 </varlistentry>
229
230 <varlistentry>
231 <term>kernel_short(<replaceable>address</replaceable>)</term>
232 <listitem>
233 <para>
234 Obtain the short at <replaceable>address</replaceable> from kernel memory.
235 </para>
236 </listitem>
237 </varlistentry>
238
239 <varlistentry>
240 <term>kernel_int(<replaceable>address</replaceable>)</term>
241 <listitem>
242 <para>
243 Obtain the int at <replaceable>address</replaceable> from kernel memory.
244 </para>
245 </listitem>
246 </varlistentry>
247
248 <varlistentry>
249 <term>kernel_long(<replaceable>address</replaceable>)</term>
250 <listitem>
251 <para>
252 Obtain the long at <replaceable>address</replaceable> from kernel memory
253 </para>
254 </listitem>
255 </varlistentry>
256
257 <varlistentry>
258 <term>kernel_string(<replaceable>address</replaceable>)</term>
259 <listitem>
260 <para>
261 Obtain the string at <replaceable>address</replaceable> from kernel memory.
262 </para>
263 </listitem>
264 </varlistentry>
265
266 <varlistentry>
267 <term>kernel_string_n(<replaceable>address</replaceable>, <replaceable>n</replaceable>)</term>
268 <listitem>
269 <para>
270 Obtain the string at <replaceable>address</replaceable> from the kernel memory
271 and limits the string to <replaceable>n</replaceable> bytes.
272 </para>
273 </listitem>
274 </varlistentry>
275
276 </variablelist>
277
278 <section id="targetprettyprinting">
279 <title>Pretty Printing Target Variables</title>
280 <indexterm>
281 <primary>target variables</primary>
282 <secondary>pretty printing</secondary>
283 </indexterm>
284
285 <para>
286 SystemTap scripts are often used to observe what is happening within
287 the code.
288 In many cases just printing the values of the various context variables
289 is sufficient.
290 SystemTap makes a number operations available that can generate
291 printable strings for target variables:
292 </para>
293
294 <variablelist>
295 <varlistentry>
296 <term>$$vars</term>
297 <listitem>
298 <para>
299 Expands to a character string that is equivalent to
300 <command>sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x",
301 parm1, ..., parmN, var1, ..., varN)</command>
302 for each variable in scope at the probe point.
303 Some values may be printed as <quote><command>=?</command></quote>
304 if their run-time location cannot be found.
305 </para>
306 </listitem>
307 </varlistentry>
308
309
310 <varlistentry>
311 <term>$$locals</term>
312 <listitem>
313 <para>
314 Expands to a subset of <command>$$vars</command>
315 containing only the local variables.
316 </para>
317 </listitem>
318 </varlistentry>
319
320 <varlistentry>
321 <term>$$parms</term>
322 <listitem>
323 <para>
324 Expands to a subset of <command>$$vars</command>
325 containing only the function parameters.
326 </para>
327 </listitem>
328 </varlistentry>
329
330 <varlistentry>
331 <term>$$return</term>
332 <listitem>
333 <para>
334 Is available in return probes only. It expands to a string that
335 is equivalent to
336 <command>sprintf("return=%x", $return)</command> if the probed
337 function has a return value, or else an empty string.
338 </para>
339 </listitem>
340 </varlistentry>
341 </variablelist>
342
343 <para>
344 Below is a command-line script that prints the values of the
345 parameters passed into the function <command>vfs_read</command>:
346 </para>
347
348 <programlisting>stap -e 'probe kernel.function("vfs_read") {printf("%s\n", $$parms); exit(); }'</programlisting>
349
350 <para>
351 There are four parameters passed into <command>vfs_read</command>:
352 <command>file</command>, <command>buf</command>,
353 <command>count</command>, and <command>pos</command>.
354 The <command>$$parms</command> generates a string for the parameters
355 passed into the function. In this case all but the
356 <command>count</command> parameter are pointers. The following
357 is an example of the output from the previous command-line script:
358 </para>
359
360 <programlisting>file=0xffff8800b40d4c80 buf=0x7fff634403e0 count=0x2004 pos=0xffff8800af96df48</programlisting>
361
362 <para>
363 Having the address a pointer points to may not be useful.
364 Instead the fields of the data structure the pointer points to may be of more use.
365 Use the <quote><command>$</command></quote> suffix to pretty print
366 the data structure.
367 The following command-line example uses the pretty printing suffix to
368 print more details about the data structures passed into the function
369 <command>vfs_read</command>:
370 </para>
371
372 <programlisting>stap -e 'probe kernel.function("vfs_read") {printf("%s\n", $$parms$); exit(); }'</programlisting>
373
374 <para>
375 The previous command line will generate something similar to the
376 following with the fields of the data structure included in the output:
377 </para>
378
379 <programlisting>file={.f_u={...}, .f_path={...}, .f_op=0xffffffffa06e1d80, .f_lock={...}, .f_count={...}, .f_flags=34818, .f_mode=31, .f_pos=0, .f_owner={...}, .f_cred=0xffff88013148fc80, .f_ra={...}, .f_version=0, .f_security=0xffff8800b8dce560, .private_data=0x0, .f_ep_links={...}, .f_mapping=0xffff880037f8fdf8} buf="" count=8196 pos=-131938753921208</programlisting>
380
381 <para>
382 With the <quote><command>$</command></quote> suffix fields that are composed of
383 data structures are not expanded.
384 The <quote><command>$$</command></quote> suffix will print the values contained within
385 the nested data structures.
386 Below is an example using the <quote><command>$$</command></quote> suffix:
387 </para>
388
389 <programlisting>stap -e 'probe kernel.function("vfs_read") {printf("%s\n", $$parms$$); exit(); }'</programlisting>
390
391 <para>
392 The <quote><command>$$</command></quote> suffix, like all strings,
393 is limited to the maximum string size.
394 Below is a representative output from the previous command-line script,
395 which is truncated because of the string size limit:
396 </para>
397
398 <programlisting>file={.f_u={.fu_list={.next=0xffff8801336ca0e8, .prev=0xffff88012ded0840}, .fu_rcuhead={.next=0xffff8801336ca0e8, .func=0xffff88012ded0840}}, .f_path={.mnt=0xffff880132fc97c0, .dentry=0xffff88001a889cc0}, .f_op=0xffffffffa06f64c0, .f_lock={.raw_lock={.slock=196611}}, .f_count={.counter=2}, .f_flags=34818, .f_mode=31, .f_pos=0, .f_owner={.lock={.raw_lock={.lock=16777216}}, .pid=0x0, .pid_type=0, .uid=0, .euid=0, .signum=0}, .f_cred=0xffff880130129a80, .f_ra={.start=0, .size=0, .async_size=0, .ra_pages=32, .</programlisting>
399
400 </section>
401
402 <section id="typecasting">
403 <title>Typecasting</title>
404 <indexterm>
405 <primary>target variables</primary>
406 <secondary>typecasting</secondary>
407 </indexterm>
408
409 <para>
410 In most cases SystemTap can determine a variable's type
411 from the debug information.
412 However, code may use void pointers for variables
413 (for example memory allocation routines) and typing information is
414 not available.
415 Also the typing information available within a probe handler is not
416 available within a function;
417 SystemTap functions arguments use a long in place of a typed pointer.
418 SystemTap's <command>@cast</command> operator (first available in
419 SystemTap 0.9) can be used to indicate
420 the correct type of the object.
421 </para>
422
423 <para>
424 The <xref linkend="casting"/> is from the
425 <command>task.stp</command> tapset.
426 The function returns the value of the <command>state</command>
427 field from a <command>task_struct</command> pointed to by
428 the long <command>task</command>.
429 The first argument of the <command>@cast</command> operator,
430 <command>task</command>, is the pointer to the object.
431 The second argument is the type to cast the object to,
432 <command>task_struct</command>.
433 The third argument lists what file that the type definition
434 information comes from and is optional.
435 With the <command>@cast</command> operator the various fields of
436 this particular <command>task_struct</command> <command>task</command>
437 can be accessed; in this example the <command>state</command> field
438 is obtained.
439 </para>
440
441 <example id="casting">
442 <title>Casting Example</title>
443 <programlisting><xi:include parse="text" href="extras/cast_example.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
444 </example>
445
446 </section>
447
448 <section id="targetavailable">
449 <title>Checking Target Variable Availability</title>
450 <indexterm>
451 <primary>target variables</primary>
452 <secondary>variable availability</secondary>
453 </indexterm>
454
455 <para>
456 As code evolves the target variables available may change.
457 The <command>@defined</command> makes it easier to handle
458 those variations in the available target variables.
459 The <command>@defined</command> provides a test to see if a particular
460 target variable is available. The result of this test
461 can be used to select the appropriate expression.
462 </para>
463
464 <para>
465 The <xref linkend="available"/> from the
466 <command>memory.stp</command> tapset provides an probe event alias.
467 Some version of the kernel functions being probed have an argument
468 <command>$flags</command>. When available, the
469 <command>$flags</command> argument is used to generate
470 the local variable <command>write_access</command>.
471 The versions of the probed functions that do not have the
472 <command>$flags</command> argument have a <command>$write</command>
473 argument and that is used instead for the local variable
474 <command>write_access</command>.
475 </para>
476
477 <example id="available">
478 <title>Testing target variable available Example</title>
479 <programlisting><xi:include parse="text" href="extras/defined_example.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
480 </example>
481
482 </section>
483
484 </section>
485
486 <section id="handlerconditionalstatements">
487 <title>Conditional Statements</title>
488 <indexterm>
489 <primary>handlers</primary>
490 <secondary>conditional statements</secondary>
491 </indexterm>
492
493 <indexterm>
494 <primary>SystemTap statements</primary>
495 <secondary>conditional statements</secondary>
496 </indexterm>
497 <para>
498 In some cases, the output of a SystemTap script may be too large. To address this, you need to further refine the script's logic in order to delimit the output into something more relevant or useful to your probe.
499 </para>
500 <!-- </formalpara> -->
501 <para>
502 Do this by using <emphasis>conditionals</emphasis> in handlers. SystemTap accepts the following types of conditional statements:
503 </para>
504
505 <variablelist>
506 <varlistentry>
507 <term>If/Else Statements</term>
508 <listitem>
509 <!-- next 3 indexterms for if/else -->
510 <indexterm>
511 <primary>handlers</primary>
512 <secondary>conditional statements</secondary>
513 <tertiary>if/else</tertiary>
514 </indexterm>
515
516 <indexterm>
517 <primary>SystemTap statements</primary>
518 <secondary>conditional statements</secondary>
519 <tertiary>if/else</tertiary>
520 </indexterm>
521
522 <indexterm>
523 <primary>if/else</primary>
524 <secondary>conditional statements</secondary>
525 <tertiary>handlers</tertiary>
526 </indexterm>
527
528 <para>Format:</para>
529 <programlisting>if (<replaceable>condition</replaceable>)
530 <replaceable>statement1</replaceable>
531 else
532 <replaceable>statement2</replaceable></programlisting>
533
534 <para>
535 The <command><replaceable>statement1</replaceable></command> is executed if the
536 <command><replaceable>condition</replaceable></command> expression is
537 non-zero. The <command><replaceable>statement2</replaceable></command> is
538 executed if the <command><replaceable>condition</replaceable></command>
539 expression is zero. The <command>else</command> clause
540 (<command>else</command> <replaceable>statement2</replaceable>) is optional. Both
541 <command><replaceable>statement1</replaceable></command> and
542 <command><replaceable>statement2</replaceable></command> can be statement
543 blocks.
544 </para>
545
546 <example id="simpleifelseexample">
547 <title>ifelse.stp</title>
548 <programlisting>global countread, countnonread
549 probe kernel.function("vfs_read"),kernel.function("vfs_write")
550 {
551 if (probefunc()=="vfs_read")
552 countread ++
553 else
554 countnonread ++
555 }
556 probe timer.s(5) { exit() }
557 probe end
558 {
559 printf("VFS reads total %d\n VFS writes total %d\n", countread, countnonread)
560 }</programlisting>
561 </example>
562
563 <para><xref linkend="simpleifelseexample"/> is a script that counts how many virtual file system reads (<command>vfs_read</command>) and writes (<command>vfs_write</command>) the system performs within a 5-second span. When run, the script increments the value of the variable <command>countread</command> by 1 if the name of the function it probed matches <command>vfs_read</command> (as noted by the condition <command>if (probefunc()=="vfs_read")</command>); otherwise, it increments <command>countnonread</command> (<command>else {countnonread ++}</command>).</para>
564
565 </listitem>
566 </varlistentry>
567
568 <varlistentry>
569 <term>While Loops</term>
570 <listitem>
571 <!-- next 2 indexterms for while loops -->
572
573 <indexterm>
574 <primary>handlers</primary>
575 <secondary>conditional statements</secondary>
576 <tertiary>while loops</tertiary>
577 </indexterm>
578
579 <indexterm>
580 <primary>SystemTap statements</primary>
581 <secondary>conditional statements</secondary>
582 <tertiary>while loops</tertiary>
583 </indexterm>
584
585 <indexterm>
586 <primary>while loops</primary>
587 <secondary>conditional statements</secondary>
588 <tertiary>handlers</tertiary>
589 </indexterm>
590 <para>Format:</para>
591 <programlisting>while (<replaceable>condition</replaceable>)
592 <replaceable>statement</replaceable></programlisting>
593 <para>
594 So long as <command><replaceable>condition</replaceable></command> is non-zero
595 the block of statements in
596 <command><replaceable>statement</replaceable></command> are executed. The
597 <command><replaceable>statement</replaceable></command> is often a statement
598 block and it must change a value so
599 <command><replaceable>condition</replaceable></command> will eventually be zero.
600 </para>
601 <!--
602 <example id="simplewhileexample">
603 <title>while.stp</title>
604 <programlisting>global foo
605 probe timer.s(1) {
606 foo ++
607 while (foo&lt;6) {printf("hello world\n")}
608 printf("goodbye world\n")</programlisting>
609 </example>
610
611 <para><xref linkend="simplewhileexample"/> is a script that prints <computeroutput>hello world</computeroutput> while less than 6 seconds has passed (<command>while (foo&lt;6)</command>). Once the <command>while</command> condition no longer applies, the script prints out <computeroutput>goodbye world</computeroutput>.</para>
612
613 --></listitem>
614 </varlistentry>
615
616 <varlistentry>
617 <term>For Loops</term>
618 <listitem>
619 <!-- next 2 indexterms for for loops -->
620
621 <indexterm>
622 <primary>handlers</primary>
623 <secondary>conditional statements</secondary>
624 <tertiary>for loops</tertiary>
625 </indexterm>
626
627 <indexterm>
628 <primary>SystemTap statements</primary>
629 <secondary>conditional statements</secondary>
630 <tertiary>for loops</tertiary>
631 </indexterm>
632
633 <indexterm>
634 <primary>for loops</primary>
635 <secondary>conditional statements</secondary>
636 <tertiary>handlers</tertiary>
637 </indexterm>
638 <para>Format:</para>
639 <programlisting>for (<replaceable>initialization</replaceable>; <replaceable>conditional</replaceable>; <replaceable>increment</replaceable>) <replaceable>statement</replaceable></programlisting>
640 <para>
641 The <command>for</command> loop is shorthand for a while loop. The
642 following is the equivalent <command>while</command> loop:
643 </para>
644 <programlisting><replaceable>initialization</replaceable>
645 while (<replaceable>conditional</replaceable>) {
646 <replaceable>statement</replaceable>
647 <replaceable>increment</replaceable>
648 }</programlisting>
649 </listitem>
650 </varlistentry>
651
652 <!--<para>Each conditional statement must be enclosed in <command>{ }</command>.</para>-->
653 <!--
654 <varlistentry>
655 <term></term>
656 <listitem>
657 <para></para>
658 </listitem>
659 </varlistentry>
660 -->
661
662 </variablelist>
663 <!--
664 <para>These constructs are better illustrated in the different examples available in <xref linkend="useful-systemtap-scripts"/>.</para>-->
665
666 <remark>need simple, simple examples for FOR and WHILE</remark>
667
668 <formalpara>
669 <title>Conditional Operators</title>
670 <!-- next 2 indexterms for conditional operators -->
671
672 <indexterm>
673 <primary>handlers</primary>
674 <secondary>conditional statements</secondary>
675 <tertiary>conditional operators</tertiary>
676 </indexterm>
677
678 <indexterm>
679 <primary>SystemTap statements</primary>
680 <secondary>conditional statements</secondary>
681 <tertiary>conditional operators</tertiary>
682 </indexterm>
683
684 <indexterm>
685 <primary>conditional operators</primary>
686 <secondary>conditional statements</secondary>
687 <tertiary>handlers</tertiary>
688 </indexterm>
689
690 <para>Aside from <command>==</command> ("is equal to"), following operators can also be used in conditional statements:</para>
691 </formalpara>
692
693 <variablelist>
694
695 <varlistentry>
696 <term>>=</term>
697 <listitem>
698 <para>Greater than or equal to</para>
699 </listitem>
700 </varlistentry>
701
702 <varlistentry>
703 <term>&lt;=</term>
704 <listitem>
705 <para>Less than or equal to</para>
706 </listitem>
707 </varlistentry>
708
709 <varlistentry>
710 <term>!=</term>
711 <listitem>
712 <para>Is not equal to</para>
713 </listitem>
714 </varlistentry>
715
716 </variablelist>
717 </section>
718 <section id="commandlineargssect">
719 <title>Command-Line Arguments</title>
720 <indexterm>
721 <primary>handlers</primary>
722 <secondary>SystemTap handler constructs</secondary>
723 <tertiary>command-line arguments</tertiary>
724 </indexterm>
725
726 <indexterm>
727 <primary>SystemTap statements</primary>
728 <secondary>SystemTap handler constructs</secondary>
729 <tertiary>command-line arguments</tertiary>
730 </indexterm>
731
732 <indexterm>
733 <primary>command-line arguments</primary>
734 <secondary>SystemTap handler constructs</secondary>
735 <tertiary>handlers</tertiary>
736 </indexterm>
737 <para>A SystemTap script can also accept simple command-line arguments using a <command>$</command> or <command>@</command> immediately
738 followed by the number of the argument on the command line. Use <command>$</command> if you are expecting the user to enter an integer as a command-line argument, and <command>@</command> if you are expecting a string.
739 </para>
740 <!-- </formalpara> -->
741
742
743 <example id="commandlineargs"><title>commandlineargs.stp</title>
744 <programlisting>probe kernel.function(@1) { }
745 probe kernel.function(@1).return { }</programlisting>
746 </example>
747
748 <para><xref linkend="commandlineargs"/> is similar to <xref linkend="wildcards"/>, except that it allows you to pass the kernel function to be probed as a command-line argument (as in <command>stap commandlineargs.stp <replaceable>kernel function</replaceable></command>). You can also specify the script to accept multiple command-line arguments, noting them as <command>@1</command>, <command>@2</command>, and so on, in the order they are entered by the user.</para>
749 <!-- next 2 indexterms for variable notations -->
750
751 <indexterm>
752 <primary>handlers</primary>
753 <secondary>SystemTap handler constructs</secondary>
754 <tertiary>variable notations</tertiary>
755 </indexterm>
756
757 <indexterm>
758 <primary>SystemTap statements</primary>
759 <secondary>SystemTap handler constructs</secondary>
760 <tertiary>variable notations</tertiary>
761 </indexterm>
762
763 <indexterm>
764 <primary>variable notations</primary>
765 <secondary>SystemTap handler constructs</secondary>
766 <tertiary>handlers</tertiary>
767 </indexterm>
768 </section>
769
770 <!-- endsection -->
771 </section>
772