diff options
Diffstat (limited to 'doc')
5 files changed, 36 insertions, 69 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml index c053c329..9c5e5a9f 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml @@ -178,7 +178,18 @@ delta = gettimeofday_s() - foo[tid()] </screen> </example> -<para>In <xref linkend="arrayreadingvaluesfrom"/>, the first statement sets a timestamp associated with the returned value of the handler function <command>tid()</command> as a <emphasis>reference point</emphasis>. The second statement computes a value for the variable <command>delta</command> by subtracting the associated value the reference point from the current <command>gettimeofday_s()</command>. Note that the first statement writes the value of <command>gettimeofday_s()</command> into the appropriate key of array <literal>foo</literal>, while in the second statement the value of <command>foo[tid()]</command> is <emphasis>read</emphasis> from the array in order to compute for <literal>delta</literal>.</para> +<para> + In <xref linkend="arrayreadingvaluesfrom"/>, the first statement sets a timestamp associated + with the returned value of the handler function <command>tid()</command> as a + <emphasis>reference point</emphasis>. + The second statement computes a value for the variable + <command>delta</command> by subtracting the associated value the reference point from the + current <command>gettimeofday_s()</command>. Note that the first statement writes the value + of <command>gettimeofday_s()</command> into the appropriate key of array + <literal>foo</literal>, while in the second statement the value of + <command>foo[tid()]</command> is <emphasis>read</emphasis> from the array in order to compute + for <literal>delta</literal>. +</para> <indexterm> <primary>reading values from arrays</primary> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml index fa81d7fc..36423fb4 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml @@ -13,7 +13,10 @@ <primary>associative arrays</primary> <secondary>introduction</secondary> </indexterm> -<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a list of values. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it. Illustrating this visually would be similar to creating a two-column table: the first column would have the unique key, while the second column would have each key's associated value. Each unique key and its associated value is referred to as a <emphasis>key pair</emphasis>.</para> + +<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a list of values. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it.</para> + +<!--<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a list of values. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it. Illustrating this visually would be similar to creating a two-column table: the first column would have the unique key, while the second column would have each key's associated value. Each unique key and its associated value is referred to as a <emphasis>key pair</emphasis>.</para>--> <!-- next 2 indexterms for key pairs --> @@ -156,62 +159,19 @@ foo["harry"] = 25 </screen> </example> -<important> - <title>Important</title> - <para>All associate arrays must be declared as <command>global</command>, regardless of whether the associate array is used in one or multiple probes. </para> -</important> - - -<section id="tuples"> - <title>Array Slots</title> -<!-- next 2 indexterms for slots --> - -<indexterm> -<primary>arrays</primary> -<secondary>introduction</secondary> -<tertiary>slots</tertiary> -</indexterm> - -<indexterm> -<primary>associative arrays</primary> -<secondary>introduction</secondary> -<tertiary>slots</tertiary> -</indexterm> - -<indexterm> -<primary>slots</primary> -<secondary>introduction</secondary> -<tertiary>arrays</tertiary> -</indexterm> -<para>Another important point to remember in arrays is that each element therein (i.e. the indexed expression) exists in a <emphasis>slot</emphasis>. A key pair's slot is defined by the order in which each pair's unique key is defined. In our sample array <command>foo</command> in <xref linkend="arraysimplestexample"/>, the key pair that uses the unique key <command>tom</command> is in the first slot, since <command>tom</command> was the first unique key to be defined. <command>dick</command> is in the second slot, and so on.</para> - -<!-- -<para>The sequence in which each key pair appears in an array (as defined by each pair's slot) is referred to as a <emphasis>tuple</emphasis>. Tuples allow us to refer to key pairs in an array by the order in which they appear in the sequence.</para>--> - -<para>For example, the array statements in <xref linkend="arraysimplestexample"/> set 23 as the associated value of the unique key <command>tom</command>. Given the same array <command>foo</command>, we can increment the associated value of <command>tom</command> by 1 using the operator <command>++</command>, like so:</para> +<para>You can specify up to 5 index expressons in an array statement, each one delimited by a comma (<command>,</command>). This is useful if you wish to perform the same operation to a set of key pairs. For example, to increase the associated value of all the key pairs defined by <xref linkend="arraysimplestexample"/>, you can use the following statement:</para> <screen> -foo["tom"] ++ +foo["tom","dick","harry"] ++ </screen> -<para>The above statement will increase the associated value of unique key <command>tom</command> to 24. Now, looking back at <xref linkend="arraysimplestexample"/>, we know that <command>dick</command> was the first unique key to be defined. As such, we can perform the same operation (i.e. incrementing associated value by 1) to <command>dick</command> using the following statement:</para> - -<screen> -foo[2] ++ -</screen> +<important> + <title>Important</title> + <para>All associate arrays must be declared as <command>global</command>, regardless of whether the associate array is used in one or multiple probes. </para> +</important> -<note> - <title>Note</title> - <para>You can specify up to 5 index expressons in an array statement, each one delimited by a comma (<command>,</command>). This is useful if you wish to perform the same operation to a set of key pairs. For example, to increase the associated value of all the key pairs defined by <xref linkend="arraysimplestexample"/>, you can use the following statement:</para> - -<screen> -foo["tom",2,"harry"] ++ -</screen> -</note> -</section> -<xi:include href="Array-Operations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- <varlistentry> <term></term> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml index 4e63ac4e..4e61e247 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml @@ -156,6 +156,8 @@ <xi:include href="Scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="ScriptConstructs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Arrays.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<xi:include href="Array-Operations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- <section id="understanding-scripts"> <title>SystemTap Scripts</title> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml index 8e089af6..8b7fc741 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml @@ -36,8 +36,12 @@ <remark>case studies and more info on some scripts here - http://sourceware.org/systemtap/wiki/WarStories</remark> <!-- <xi:include href="Useful_Scripts-Disk.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> -<xi:include href="Useful_Scripts-futexes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - +<section id="mainsect-network"> + <title>Network</title> + <para>The following sections showcase scripts that trace network-related functions and build a profile of network activity.</para> + <xi:include href="Useful_Scripts-nettop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Useful_Scripts-sockettrace.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</section> <section id="mainsect-disk"> <title>Disk</title> <para>The following sections showcase scripts that monitor disk and I/O activity.</para> @@ -61,12 +65,8 @@ </section> <!-- removed; handler function no longer working as expected <xi:include href="Useful_Scripts-kernelprofiling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> -<section id="mainsect-network"> - <title>Network</title> - <para>The following sections showcase scripts that trace network-related functions and build a profile of network activity.</para> - <xi:include href="Useful_Scripts-nettop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Useful_Scripts-sockettrace.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</section> + +<xi:include href="Useful_Scripts-futexes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- <xi:include href="Useful_Scripts-Network.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Useful_Scripts-Signals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> diff --git a/doc/langref.tex b/doc/langref.tex index 5db82550..3af2bd15 100644 --- a/doc/langref.tex +++ b/doc/langref.tex @@ -1858,16 +1858,10 @@ p& Pointer address& 0x0000000000bc614e\tabularnewline \hline -n& -Writes a binary value that is the total length of the string written by printf. -The field width specifies the number of bytes to write. Valid specifications -are \%n, \%1n, \%2n and \%4n. The default is 2.& -See below\tabularnewline -\hline b& Writes a binary value as text. The field width specifies the number of bytes to write. Valid specifications are \%b, \%1b, \%2b, \%4b and \%8b. The default -width is 4 (32-bits).& +width is 8 (64-bits).& See below\tabularnewline \hline \%& @@ -1987,7 +1981,7 @@ Another example: \begin{vindent} \begin{verbatim} -stap -e 'probe begin{printf("%1n%b%b", 0xc0dedbad, \ +stap -e 'probe begin{printf("%b%b", 0xc0dedbad, \ 0x12345678);exit()}' | hexdump -C \end{verbatim} @@ -1996,8 +1990,8 @@ This prints: \begin{vindent} \begin{verbatim} -00000000 08 ad db de c0 78 56 34 12 |.....xV4.| -00000009 +00000000 ad db de c0 00 00 00 00 78 56 34 12 00 00 00 00 |........xV4.....| +00000010 \end{verbatim} \end{vindent} Another example: |