A discussion about @defined to SystemTap Beginners Guide.

diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
index 8f7a8c15406e3b13921d7739a491b631fec613fc..94c4d93aa9f000df1d0e89f85b04a7e9a9e5d79a 100644 (file)
--- a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml
@@ -289,6 +289,42 @@ and limits the string to <replaceable>n</replaceable> bytes.
 
 </section>
 
+<section id="targetavailable">
+       <title>Checking Target Variable Availablility</title>
+<indexterm>
+<primary>target variables</primary>
+<secondary>variable availability</secondary>
+</indexterm>
+
+<para>
+       As code evolves the target variables available may change.
+       The <command>@defined</command> makes it easier to handle
+       those variations in the available target variables.
+       The <command>@defined</command> provides a test to see if a particular
+       target variable is available. The result of this test
+       can be used to select the appropriate expression.
+</para>
+
+<para>
+       The <xref linkend="available"/> from the
+       <command>memory.stp</command> tapset provides an probe event alias.
+       Some version of the kernel functions being probed have an argument
+       <command>$flags</command>. In those cases, the
+       <command>$flags</command> argument is used to generate
+       the local variable <command>write</command>.
+       The versions of the probed functions that do not have the
+       <command>$flags</command> argument have a <command>$write</command>
+       argument and that is used instead for the local variable
+       <command>write</command>.
+</para>
+
+<example id="available">
+       <title>Testing target variable available Example</title>
+<programlisting><xi:include parse="text" href="extras/defined_example.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+</example>
+
+</section>
+
 </section>
 
 <section id="handlerconditionalstatements">

diff --git a/doc/SystemTap_Beginners_Guide/en-US/extras/defined_example.stp b/doc/SystemTap_Beginners_Guide/en-US/extras/defined_example.stp
new file mode 100644 (file)
index 0000000..19dd10c
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/extras/defined_example.stp
@@ -0,0 +1,8 @@
+probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?,
+                     kernel.function("handle_mm_fault@mm/memory.c") ?
+{
+        name = "pagefault"
+        write_access = (@defined($flags)
+                       ? $flags & FAULT_FLAG_WRITE : $write_access)
+       address =  $address
+}