diff options
Diffstat (limited to 'doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml')
| -rw-r--r-- | doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml | 200 |
1 files changed, 197 insertions, 3 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml index 1cda95a4..e0917280 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml @@ -4,15 +4,84 @@ <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 handlers</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 it to a function, and use it in an expression. SystemTap automatically identifies whether a variable should be identified as a string or integer, based on the function it is assigned to. 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> can be used as an integer argument (<command>%d</command>) in <command>printf()</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 handlers</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 first using <command>global</command> outside of any probe. Consider the following example:</para> <example id="timerjiffies"> @@ -30,6 +99,10 @@ probe timer.ms(12345) } </programlisting> </example> + +<indexterm> +<primary><command>CONFIG_HZ, computing for</command></primary> +</indexterm> <para><xref linkend="timerjiffies"/> attempts to compute 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> @@ -50,6 +123,15 @@ probe timer.jiffies(100) { count_jiffies ++ } </section> <section id="handlerconditionalstatements"> <title>Conditional Statements</title> +<indexterm> +<primary>handlers</primary> +<secondary>conditional statements</secondary> +</indexterm> + +<indexterm> +<primary>SystemTap handlers</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> @@ -62,6 +144,25 @@ You can do this by using <emphasis>conditionals</emphasis> in handlers. SystemTa <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 handlers</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>) @@ -95,6 +196,25 @@ probe end <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 handlers</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>} @@ -119,6 +239,25 @@ printf("goodbye world\n") <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 handlers</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>argument1</replaceable>; <replaceable>argument2</replaceable>; <replaceable>argument3</replaceable>) {<replaceable>statement</replaceable>} @@ -144,6 +283,26 @@ for (<replaceable>argument1</replaceable>; <replaceable>argument2</replaceable>; <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 handlers</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> @@ -174,6 +333,23 @@ for (<replaceable>argument1</replaceable>; <replaceable>argument2</replaceable>; </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 handlers</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 and declare them in the script without using <command>target()</command>. One way to do this is to use the variable notation <command>$</command> or <command>@</command>.</para> <!-- </formalpara> --> @@ -186,7 +362,25 @@ probe kernel.function(@1).return { } </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 handlers</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> <para>Both variable notations <command>$</command> and <command>@</command> also represent a specific variable type. 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> </section> |