diff options
Diffstat (limited to 'doc/SystemTap_Beginners_Guide/en-US/Arrays.xml')
| -rw-r--r-- | doc/SystemTap_Beginners_Guide/en-US/Arrays.xml | 22 |
1 files changed, 11 insertions, 11 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml index 04e34de3..63c3df04 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml @@ -14,7 +14,7 @@ <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.</para> +<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a collection 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>--> @@ -98,7 +98,7 @@ <tertiary>arrays</tertiary> </indexterm> -<para>Since associative arrays are normally processed in multiple probes (as we will demonstrate later), they are declared as <command>global</command> variables in the SystemTap script. The syntax for manipulating arrays (i.e. accessing elements in an associative array) is similar to that of <command>awk</command>, and is as follows:</para> +<para>Since associative arrays are normally processed in multiple probes (as we will demonstrate later), they are declared as <command>global</command> variables in the SystemTap script. The syntax for accessing an element in an associative array is similar to that of <command>awk</command>, and is as follows:</para> <!-- next 3 indexterms for syntax --> <indexterm> <primary>arrays</primary> @@ -126,10 +126,10 @@ <screen> -<replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>] <replaceable>operation</replaceable> +<replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>] </screen> -<para>Here, the <command><replaceable>array_name</replaceable></command> is any arbitrary name the array uses. The <command><replaceable>index_expression</replaceable></command> is used to refer to a specific unique key (or set of unique keys) in the array, and the <command><replaceable>operation</replaceable></command> defines what to do with the <command><replaceable>index_expression</replaceable></command>. To illustrate, let us try to build an array named <command>foo</command> that specifies the ages of three people (i.e. the unique keys): <command>tom</command>, <command>dick</command>, and <command>harry</command>. To assign them the ages (i.e. associated values) of 23, 24, and 25 respectively, we'd use the following array statements:</para> +<para>Here, the <command><replaceable>array_name</replaceable></command> is any arbitrary name the array uses. The <command><replaceable>index_expression</replaceable></command> is used to refer to a specific unique key in the array. To illustrate, let us try to build an array named <command>foo</command> that specifies the ages of three people (i.e. the unique keys): <command>tom</command>, <command>dick</command>, and <command>harry</command>. To assign them the ages (i.e. associated values) of 23, 24, and 25 respectively, we'd use the following array statements:</para> <!-- next 2 indexterms for example --> @@ -158,13 +158,13 @@ foo["dick"] = 24 foo["harry"] = 25 </screen> </example> -<!-- -<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> + +<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 have a key that contains multiple pieces of information. The following line from <xref linkend="scriptdisktop"/> uses 5 elements for the key: process ID, executable name, user ID, parent ID, and string "W". It associates the value of <command>devname</command> with that key.</para> <screen> -foo["tom","dick","harry"] ++ +device[pid(),execname(),uid(),ppid(),"W"] = devname </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> @@ -220,13 +220,13 @@ probe begin { foo[4,"hello"] ++ } <para>You can also use a handler function in as the <command><replaceable>unique_key</replaceable></command>. Doing so creates an associate array that uses the values returned by the handler function as the unique keys. The first time that a probe using this array returns a string value, that value is set as a unique key with an initial value of 0. The next time that the probe returns the same string value, it increments the associated value of the unique key by 1.</para> -<para>For example, let's say you need to tally how many times each process performs a read to the virtual file system (VFS). To do this, probe the kernel function <command>vfs_read</command>, use the handler <command>execname()</command> to identify which processes performed the VFS read, and tally the reads of each process using the associative array named <command>reads</command>, as in</para> +<para>For example, let's say you need to tally how many times each process performs a read to the virtual file system (VFS). To do this, probe the VFS read opeartion, use the handler <command>execname()</command> to identify which processes performed the VFS read, and tally the reads of each process using the associative array named <command>reads</command>, as in</para> <formalpara id="aaexamplesimplevfsreads"> <title>tallying-in-arrays.stp</title> <para> <programlisting> -probe kernel.function("vfs_read") +probe vfs.read { reads[execname()] += $count } </programlisting> </para> @@ -234,4 +234,4 @@ probe kernel.function("vfs_read") <para>In <xref linkend="aaexamplesimplevfsreads"/>, the first time that the probe returns the process name <command>gnome-terminal</command> (i.e. the first time <command>gnome-terminal</command> performs a VFS read), that process name is set as a unique key. The next time that the probe returns the process name <command>gnome-terminal</command>, SystemTap increments the associated value of <command>gnome-terminal</command> by 1. SystemTap performs this operation for <emphasis>all</emphasis> process names as the probe returns them.</para> --> -</section>
\ No newline at end of file +</section> |