| 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<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<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><=</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 |
|