From e557e9564abe26495b516332fec90016bc4760ac Mon Sep 17 00:00:00 2001 From: William Cohen Date: Wed, 10 Dec 2008 10:38:53 -0500 Subject: Edit text sections on associative arrays. Also tweak example two space indent. --- .../en-US/Array-Operations.xml | 148 ++++++++++----------- doc/SystemTap_Beginners_Guide/en-US/Arrays.xml | 22 +-- 2 files changed, 84 insertions(+), 86 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide') diff --git a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml index 8fe46721..789bf607 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml @@ -263,7 +263,7 @@ delta = gettimeofday_s() - foo[tid()] array_name[index_expression] ++ -Again, you can also use a handler function for your index_expression. For example, if you wanted to tally how many times a specific process performed a read to the virtual file system (using the event kernel.function("vfs_read")), you can use the following probe: +Again, you can also use a handler function for your index_expression. For example, if you wanted to tally how many times a specific process performed a read to the virtual file system (using the event vfs.read), you can use the following probe: @@ -299,9 +299,9 @@ delta = gettimeofday_s() - foo[tid()] vfsreads.stp -probe kernel.function("vfs_read") +probe vfs.read { - reads[execname()] ++ + reads[execname()] ++ } @@ -430,12 +430,12 @@ probe kernel.function("vfs_read") global reads probe vfs.read { - reads[execname()] ++ + reads[execname()] ++ } probe timer.s(3) { - foreach (count in reads) - printf("%s : %d \n", count, reads[count]) + foreach (count in reads) + printf("%s : %d \n", count, reads[count]) } @@ -500,8 +500,8 @@ probe timer.s(3) probe timer.s(3) { - foreach (count in reads- limit 10) - printf("%s : %d \n", count, reads[count]) + foreach (count in reads- limit 10) + printf("%s : %d \n", count, reads[count]) } @@ -591,13 +591,13 @@ probe timer.s(3) global reads probe vfs.read { - reads[execname()] ++ + reads[execname()] ++ } probe timer.s(3) { - foreach (count in reads) - printf("%s : %d \n", count, reads[count]) - delete reads + foreach (count in reads) + printf("%s : %d \n", count, reads[count]) + delete reads } @@ -608,20 +608,20 @@ probe timer.s(3) global reads probe vfs.read { - reads[execname()] ++ - + reads[execname()] ++ } -probe timer.s(2) + +probe timer.s(3) { - printf("=======\n") - foreach (count in reads+) - printf("%s : %d \n", count, reads[count]) - delete reads + printf("=======\n") + foreach (count in reads+) + printf("%s : %d \n", count, reads[count]) + delete reads } --> -In , the second probe prints the number of VFS reads each process made within the probed 2-second period only. The delete reads statement clears the reads array within the probe. +In , the second probe prints the number of VFS reads each process made within the probed 3-second period only. The delete reads statement clears the reads array within the probe. Note @@ -651,34 +651,34 @@ probe timer.s(2) clearing arrays/array elements array operations - You can have multiple array operations within the same probe. Using the examples from and , you can track the number of VFS reads each process makes per 2-second period and tally the cumulative VFS reads of those same processes. Consider the following example: + You can have multiple array operations within the same probe. Using the examples from and , you can track the number of VFS reads each process makes per 3-second period and tally the cumulative VFS reads of those same processes. Consider the following example: global reads, totalreads -probe kernel.function("vfs_read") +probe vfs.read { - reads[execname()] ++ - totalreads[execname()] ++ + reads[execname()] ++ + totalreads[execname()] ++ } -probe timer.s(2) +probe timer.s(3) { - printf("=======\n") - foreach (count in reads+) - printf("%s : %d \n", count, reads[count]) - delete reads - + printf("=======\n") + foreach (count in reads+) + printf("%s : %d \n", count, reads[count]) + delete reads } + probe end { - printf("TOTALS\n") - foreach (total in totalreads+) - printf("%s : %d \n", total, totalreads[total]) + printf("TOTALS\n") + foreach (total in totalreads+) + printf("%s : %d \n", total, totalreads[total]) } -In this example, the arrays reads and totalreads track the same information, and are printed out in a similar fashion. The only difference here is that reads is cleared every 2-second period, whereas totalreads keeps growing. +In this example, the arrays reads and totalreads track the same information, and are printed out in a similar fashion. The only difference here is that reads is cleared every 3-second period, whereas totalreads keeps growing.
@@ -711,39 +711,38 @@ probe end global reads probe vfs.read { - reads[execname()] ++ + reads[execname()] ++ } -probe timer.s(2) +probe timer.s(3) { - printf("=======\n") - foreach (count in reads-) - if (reads[count] >= 1024) - printf("%s : %dkB \n", count, reads[count]/1024) - else - printf("%s : %dB \n", count, reads[count]) + printf("=======\n") + foreach (count in reads-) + if (reads[count] >= 1024) + printf("%s : %dkB \n", count, reads[count]/1024) + else + printf("%s : %dB \n", count, reads[count]) } -Every two seconds, prints out a list of all processes, along with how many times each process performed a VFS read. If the associated value of a process name is equal or greater than 1024, the if statement in the script converts and prints it out in kB. +Every three seconds, prints out a list of all processes, along with how many times each process performed a VFS read. If the associated value of a process name is equal or greater than 1024, the if statement in the script converts and prints it out in kB. @@ -98,7 +98,7 @@ arrays -Since associative arrays are normally processed in multiple probes (as we will demonstrate later), they are declared as global variables in the SystemTap script. The syntax for manipulating arrays (i.e. accessing elements in an associative array) is similar to that of awk, and is as follows: +Since associative arrays are normally processed in multiple probes (as we will demonstrate later), they are declared as global variables in the SystemTap script. The syntax for accessing an element in an associative array is similar to that of awk, and is as follows: arrays @@ -126,10 +126,10 @@ -array_name[index_expression] operation +array_name[index_expression] -Here, the array_name is any arbitrary name the array uses. The index_expression is used to refer to a specific unique key (or set of unique keys) in the array, and the operation defines what to do with the index_expression. To illustrate, let us try to build an array named foo that specifies the ages of three people (i.e. the unique keys): tom, dick, and harry. To assign them the ages (i.e. associated values) of 23, 24, and 25 respectively, we'd use the following array statements: +Here, the array_name is any arbitrary name the array uses. The index_expression is used to refer to a specific unique key in the array. To illustrate, let us try to build an array named foo that specifies the ages of three people (i.e. the unique keys): tom, dick, and harry. To assign them the ages (i.e. associated values) of 23, 24, and 25 respectively, we'd use the following array statements: @@ -158,13 +158,13 @@ foo["dick"] = 24 foo["harry"] = 25 - + Important All associate arrays must be declared as global, regardless of whether the associate array is used in one or multiple probes. @@ -220,13 +220,13 @@ probe begin { foo[4,"hello"] ++ } You can also use a handler function in as the unique_key. 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. -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 vfs_read, use the handler execname() to identify which processes performed the VFS read, and tally the reads of each process using the associative array named reads, as in +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 execname() to identify which processes performed the VFS read, and tally the reads of each process using the associative array named reads, as in tallying-in-arrays.stp -probe kernel.function("vfs_read") +probe vfs.read { reads[execname()] += $count } @@ -234,4 +234,4 @@ probe kernel.function("vfs_read") In , the first time that the probe returns the process name gnome-terminal (i.e. the first time gnome-terminal performs a VFS read), that process name is set as a unique key. The next time that the probe returns the process name gnome-terminal, SystemTap increments the associated value of gnome-terminal by 1. SystemTap performs this operation for all process names as the probe returns them. --> -
\ No newline at end of file + -- cgit