path: root/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml

<?xml version='1.0'?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<section id="scriptconstructions">
<title>Basic SystemTap Handler Constructs</title>
<indexterm>
<primary>handlers</primary>
<secondary>SystemTap handler constructs</secondary>
</indexterm>

<indexterm>
<primary>SystemTap handlers</primary>
<secondary>SystemTap handler constructs</secondary>
</indexterm>	

<!-- next 2 indexterms for syntax and format -->

<indexterm>
<primary>handlers</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>syntax and format</tertiary>
</indexterm>

<indexterm>
<primary>SystemTap handlers</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>syntax and format</tertiary>
</indexterm>

<indexterm>
<primary>syntax and format</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>handlers</tertiary>
</indexterm>
	<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> 
	
<section id="variablesconstructs">
	<title>Variables</title>
<!-- next 3 indexterms for variables -->
<indexterm>
<primary>handlers</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>variables</tertiary>
</indexterm>

<indexterm>
	<primary>SystemTap statements</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>variables</tertiary>
</indexterm>

<indexterm>
<primary>variables</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>handlers</tertiary>
</indexterm>	

<indexterm>
	<primary>format and syntax</primary>
	<secondary>SystemTap handler constructs</secondary>
	<tertiary>handlers</tertiary>
</indexterm>
	<para>Variables can be used freely throughout a handler; simply choose a
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 an number and can be printed in a <command>printf()</command> with the integer format specifier (<command>%d</command>).</para>

<!-- next 2 indexterms for <command>global</command> -->

<indexterm>
<primary>handlers</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary><command>global</command></tertiary>
</indexterm>

<indexterm>
	<primary>SystemTap statements</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary><command>global</command></tertiary>
</indexterm>

<indexterm>
<primary><command>global</command></primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>handlers</tertiary>
</indexterm>
<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>

<example id="timerjiffies">
	<title>timer-jiffies.stp</title>
<programlisting>
global count_jiffies, count_ms
probe timer.jiffies(100) { count_jiffies ++ }
probe timer.ms(100) { count_ms ++ }
probe timer.ms(12345)
{
  hz=(1000*count_jiffies) / count_ms
  printf ("jiffies:ms ratio %d:%d => CONFIG_HZ=%d\n",
    count_jiffies, count_ms, hz)
  exit ()
}
</programlisting>
</example>

<indexterm>
<primary><command>CONFIG_HZ, computing for</command></primary>
</indexterm>
	
<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>

<note>
	<title>Note</title>
	<para>The <command>++</command> notation in <xref linkend="timerjiffies"/> (i.e. <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>
<screen>
probe timer.jiffies(100) { count_jiffies ++ }
</screen>
	<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>   
</note>	
<!--
<note>
	<title>Note</title>
	<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>
</note>	
	-->
</section>	
<section id="handlerconditionalstatements">
	<title>Conditional Statements</title>
<indexterm>
<primary>handlers</primary>
<secondary>conditional statements</secondary>
</indexterm>

<indexterm>
	<primary>SystemTap statements</primary>
<secondary>conditional statements</secondary>
</indexterm>
<para>
In some cases, the output of a SystemTap script may be too big. 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.
</para>
<!-- </formalpara> -->
<para>
You can do this by using <emphasis>conditionals</emphasis> in handlers. SystemTap accepts the following types of conditional statements:
</para>

<variablelist>
<varlistentry>
	<term>If/Else Statements</term>
	<listitem>
<!-- next 3 indexterms for if/else -->
<indexterm>
<primary>handlers</primary>
<secondary>conditional statements</secondary>
<tertiary>if/else</tertiary>
</indexterm>

<indexterm>
	<primary>SystemTap statements</primary>
<secondary>conditional statements</secondary>
<tertiary>if/else</tertiary>
</indexterm>

<indexterm>
<primary>if/else</primary>
<secondary>conditional statements</secondary>
<tertiary>handlers</tertiary>
</indexterm>

		<para>Format:</para>
<programlisting>
if (<replaceable>condition</replaceable>)
  <replaceable>statement1</replaceable>
else
  <replaceable>statement2</replaceable>
</programlisting>

<para>
The <command><replaceable>statement1</replaceable></command> is executed if the
<command><replaceable>condition</replaceable></command> expression is
non-zero. The <command><replaceable>statement2</replaceable></command> is
executed if the <command><replaceable>condition</replaceable></command>
expression is zero. The <command>else</command> clause 
(<command>else</command> <replaceable>statement2</replaceable>)is optional. Both
<command><replaceable>statement1</replaceable></command> and
<command><replaceable>statement2</replaceable></command> can be statement
blocks.
</para>

<example id="simpleifelseexample">
	<title>ifelse.stp</title>
<programlisting>
global countread, countnonread
probe kernel.function("vfs_read"),kernel.function("vfs_write")
{
  if (probefunc()=="vfs_read") 
    countread ++ 
  else 
    countnonread ++
}
probe timer.s(5) { exit() }
probe end 
{
  printf("VFS reads total %d\n VFS writes total %d\n", countread, countnonread)
}
</programlisting>
</example>

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

	</listitem>	
</varlistentry>	
	
<varlistentry>
	<term>While Loops</term>
	<listitem>
<!-- next 2 indexterms for while loops -->

<indexterm>
<primary>handlers</primary>
<secondary>conditional statements</secondary>
<tertiary>while loops</tertiary>
</indexterm>

<indexterm>
	<primary>SystemTap statements</primary>
<secondary>conditional statements</secondary>
<tertiary>while loops</tertiary>
</indexterm>

<indexterm>
<primary>while loops</primary>
<secondary>conditional statements</secondary>
<tertiary>handlers</tertiary>
</indexterm>
		<para>Format:</para>
<programlisting>
while (<replaceable>condition</replaceable>)
  <replaceable>statement</replaceable>
</programlisting>
<para>
So long as <command><replaceable>condition</replaceable></command> is non-zero
the block of statements in
<command><replaceable>statement</replaceable></command> are executed. The
<command><replaceable>statement</replaceable></command> is often a statement
block and it must change a value so
<command><replaceable>condition</replaceable></command> will eventually be zero.
</para>
<!--
<example id="simplewhileexample">
	<title>while.stp</title>
<programlisting>
global foo
probe timer.s(1) {
foo ++
while (foo&lt;6) {printf("hello world\n")}
printf("goodbye world\n")
</programlisting>
</example>

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

	--></listitem>	
</varlistentry>	

<varlistentry>
	<term>For Loops</term>
	<listitem>
<!-- next 2 indexterms for for loops -->

<indexterm>
<primary>handlers</primary>
<secondary>conditional statements</secondary>
<tertiary>for loops</tertiary>
</indexterm>

<indexterm>
	<primary>SystemTap statements</primary>
<secondary>conditional statements</secondary>
<tertiary>for loops</tertiary>
</indexterm>

<indexterm>
<primary>for loops</primary>
<secondary>conditional statements</secondary>
<tertiary>handlers</tertiary>
</indexterm>		
		<para>Format:</para>
<programlisting>
for (<replaceable>initialization</replaceable>; <replaceable>conditional</replaceable>; <replaceable>increment</replaceable>) <replaceable>statement</replaceable>
</programlisting>
<para>
The <command>for</command> loop is simply shorthand for a while loop. The
following is the equivalent <command>while</command> loop:
</para>
<programlisting>
<replaceable>initialization</replaceable>
while (<replaceable>conditional</replaceable>) {
   <replaceable>statement</replaceable>
   <replaceable>increment</replaceable>
}
</programlisting>
	</listitem>
</varlistentry>

<!--<para>Each conditional statement must be enclosed in <command>{ }</command>.</para>-->
<!--	
<varlistentry>
	<term></term>
	<listitem>
		<para></para>
	</listitem>	
</varlistentry>
-->	
	
</variablelist>	
<!--	
<para>These constructs are better illustrated in the different examples available in <xref linkend="useful-systemtap-scripts"/>.</para>-->

<remark>need simple, simple examples for FOR and WHILE</remark>

<formalpara>
	<title>Conditional Operators</title>
<!-- next 2 indexterms for conditional operators -->

<indexterm>
<primary>handlers</primary>
<secondary>conditional statements</secondary>
<tertiary>conditional operators</tertiary>
</indexterm>

<indexterm>
	<primary>SystemTap statements</primary>
<secondary>conditional statements</secondary>
<tertiary>conditional operators</tertiary>
</indexterm>

<indexterm>
<primary>conditional operators</primary>
<secondary>conditional statements</secondary>
<tertiary>handlers</tertiary>
</indexterm>

<para>Aside from <command>==</command> ("is equal to"), you can also use the following operators in your conditional statements:</para>
</formalpara>

<variablelist>

<varlistentry>
	<term>>=</term>
	<listitem>
		<para>Greater than or equal to</para>
	</listitem>	
</varlistentry>	

<varlistentry>
	<term>&lt;=</term>
	<listitem>
		<para>Less than or equal to</para>
	</listitem>	
</varlistentry>

<varlistentry>
	<term>!=</term>
	<listitem>
		<para>Is not equal to</para>
	</listitem>	
</varlistentry>

</variablelist>
</section>
<section id="commandlineargssect">
	<title>Command-Line Arguments</title>
<indexterm>
<primary>handlers</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>command-line arguments</tertiary>
</indexterm>

<indexterm>
	<primary>SystemTap statements</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>command-line arguments</tertiary>
</indexterm>

<indexterm>
<primary>command-line arguments</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>handlers</tertiary>
</indexterm>	
	<para>You can also allow a SystemTap script to accept simple command-line arguments using a  <command>$</command> or <command>@</command> immediately
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.
</para>
<!-- </formalpara> -->


<example id="commandlineargs"><title>commandlineargs.stp</title>
<programlisting>
probe kernel.function(@1) { }
probe kernel.function(@1).return { }
</programlisting>	
</example>	

<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>
 <!-- next 2 indexterms for variable notations -->

<indexterm>
<primary>handlers</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>variable notations</tertiary>
</indexterm>

<indexterm>
	<primary>SystemTap statements</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>variable notations</tertiary>
</indexterm>

<indexterm>
<primary>variable notations</primary>
<secondary>SystemTap handler constructs</secondary>
<tertiary>handlers</tertiary>
</indexterm>
	</section>
	
<!-- endsection	 -->
</section>