diff options
author | Elliott Baron <elliott@localhost.localdomain> | 2008-12-19 10:13:52 -0500 |
---|---|---|
committer | Elliott Baron <elliott@localhost.localdomain> | 2008-12-19 10:13:52 -0500 |
commit | a46143af464b24e75e784a3ebaebf86bc52a44ed (patch) | |
tree | 8ab09ae8ff39e673fed163ad6ef225c3e0ae754a /doc/SystemTap_Beginners_Guide | |
parent | 30c94a80d5f7bef33450bd1a7e090c8e99b6db89 (diff) | |
parent | b00e123d3bc577a0b255628e36f7534dc7a1e641 (diff) | |
download | systemtap-steved-a46143af464b24e75e784a3ebaebf86bc52a44ed.tar.gz systemtap-steved-a46143af464b24e75e784a3ebaebf86bc52a44ed.tar.xz systemtap-steved-a46143af464b24e75e784a3ebaebf86bc52a44ed.zip |
Merge branch 'master' of ssh://ebaron@sources.redhat.com/git/systemtap
Diffstat (limited to 'doc/SystemTap_Beginners_Guide')
9 files changed, 144 insertions, 136 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml index bf496321..00a8673c 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml @@ -505,7 +505,7 @@ probe timer.s(3) } </screen> -<para>This <command>foreach</command> statement instructs the script to process the elements in the array <command>reads</command> in descending order (of associated value). The <command>limit 10</command> option instructs the script to only process the first ten elements in the array (i.e. the first 10, starting with the highest value).</para> +<para>This <command>foreach</command> statement instructs the script to process the elements in the array <command>reads</command> in descending order (of associated value). The <command>limit 10</command> option instructs the <command>foreach</command> to only process the first ten iterations (i.e. print the first 10, starting with the highest value).</para> </section> <section id="arrayops-deleting"> @@ -665,7 +665,7 @@ probe vfs.read probe timer.s(3) { printf("=======\n") - foreach (count in reads+) + foreach (count in reads-) printf("%s : %d \n", count, reads[count]) delete reads } @@ -673,7 +673,7 @@ probe timer.s(3) probe end { printf("TOTALS\n") - foreach (total in totalreads+) + foreach (total in totalreads-) printf("%s : %d \n", total, totalreads[total]) } </screen> @@ -788,7 +788,7 @@ probe timer.s(3) </formalpara> <screen> -if([<replaceable>index_expression</replaceable>] in <replaceable>array_name</replaceable>) +if([<replaceable>index_expression</replaceable>] in <replaceable>array_name</replaceable>) <replaceable>statement</replaceable> </screen> <para>To illustrate this, consider the following example:</para> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml index ac320fcd..3d3dec01 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml @@ -161,7 +161,7 @@ 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 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> +<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 process ID, and string "W". It associates the value of <command>devname</command> with that key.</para> <screen> device[pid(),execname(),uid(),ppid(),"W"] = devname diff --git a/doc/SystemTap_Beginners_Guide/en-US/Errors.xml b/doc/SystemTap_Beginners_Guide/en-US/Errors.xml index ffb70470..62e89580 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Errors.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Errors.xml @@ -101,7 +101,7 @@ replicate?</remark> <para> - The following invalid SystemTap script is missing the its probe + The following invalid SystemTap script is missing its probe handlers: </para> @@ -473,8 +473,9 @@ probe syscall.open <computeroutput><replaceable>foo</replaceable></computeroutput> refers to. This usually means that SystemTap could not find a match for <computeroutput><replaceable>foo</replaceable></computeroutput> in the - tapset library. The <replaceable>N</replaceable> refers to the column - the error occurred in.</para> + tapset library. The <replaceable>N</replaceable> refers to the + line and column of + the error.</para> </formalpara> <remark>how to explain N in previous? "The divergence from the “tree” of probe point namespace is at position N (starting with zero at left)." (from tutorial) </remark> @@ -807,6 +808,7 @@ An array containing aggregate values contains too many distinct key pairs at thi <para> Too many levels of function call nesting were attempted. + The default nesting of function calls allowed is 10. </para> </formalpara> @@ -843,7 +845,9 @@ An array containing aggregate values contains too many distinct key pairs at thi <tertiary>understainding SystemTap errors</tertiary> </indexterm> <para> - The probe handler attempted to execute too many statements in the probe handler. + The probe handler attempted to execute too many statements in the + probe handler. The default number of actions allow in a probe handler + is 1000. </para> </formalpara> diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml index 2550efce..89334eff 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml @@ -177,7 +177,8 @@ The <command><replaceable>statement1</replaceable></command> is executed if the <command><replaceable>condition</replaceable></command> expression is non-zero. The <command><replaceable>statement2</replaceable></command> is executed if the <command><replaceable>condition</replaceable></command> -expression is zero. The <command>else</command> is optional. Both +expression is zero. The <command>else</command> clause +(<command>else</command> <replaceable>statement2</replaceable>)is optional. Both <command><replaceable>statement1</replaceable></command> and <command><replaceable>statement2</replaceable></command> can be statement blocks. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index fe2e69f4..88aa42ab 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -129,7 +129,7 @@ </indexterm> <para> SystemTap scripts use the file extension <filename>.stp</filename>, and - are conatains probes written in the following format: + contains probes written in the following format: </para> </formalpara> <screen> @@ -555,21 +555,21 @@ probe timer.s(4) </indexterm> <para> Consider the following sample script: </para> - <example id="helloworld"><title>helloworld.stp</title> - <programlisting> - probe begin - { - printf ("hello world\n") - exit () - } - </programlisting> - </example> +<example id="helloworld"><title>helloworld.stp</title> +<programlisting> +probe begin +{ + printf ("hello world\n") + exit () +} +</programlisting> +</example> <para> In <xref linkend="helloworld"/>, the event <command>begin</command> (i.e. the start of the session) triggers the handler enclosed in <command>{ }</command>, which simply prints <command>hello - world</command>, then exits. + world</command> followed by a new-line, then exits. </para> <note> @@ -581,7 +581,7 @@ probe timer.s(4) <indexterm> <primary><command>exit()</command></primary> - <secondary>Handlers</secondary> + <secondary>functions</secondary> </indexterm> <para> SystemTap scripts continue to run until the @@ -666,15 +666,15 @@ probe timer.s(4) <para> To illustrate this, consider the following probe example: </para> - <example id="syscall-open"> - <title>variables-in-printf-statements.stp</title> - <programlisting> - probe syscall.open - { - printf ("%s(%d) open\n", execname(), pid()) - } - </programlisting> - </example> +<example id="syscall-open"> +<title>variables-in-printf-statements.stp</title> +<programlisting> +probe syscall.open +{ + printf ("%s(%d) open\n", execname(), pid()) +} +</programlisting> +</example> <para> <xref linkend="syscall-open"/> instructs SystemTap to probe all entries to @@ -688,16 +688,16 @@ probe timer.s(4) to "argument1", "format specifier2" is to "argument2", or is this clear enough? </remark> - <screen> - vmware-guestd(2206) open - hald(2360) open - hald(2360) open - hald(2360) open - df(3433) open - df(3433) open - df(3433) open - hald(2360) open - </screen> +<screen> +vmware-guestd(2206) open +hald(2360) open +hald(2360) open +hald(2360) open +df(3433) open +df(3433) open +df(3433) open +hald(2360) open +</screen> <formalpara id="systemtapscript-functions"> <title>SystemTap Functions</title> @@ -732,20 +732,20 @@ probe timer.s(4) <listitem> <indexterm> <primary>functions</primary> - <secondary>handler functions</secondary> - <tertiary><command>tid()</command></tertiary> + <secondary><command>tid()</command></secondary> +<!-- <tertiary><command>tid()</command></tertiary> --> </indexterm> <indexterm> - <primary>handler functions</primary> - <secondary>Handlers</secondary> - <tertiary><command>tid()</command></tertiary> + <primary>functions</primary> + <secondary><command>tid()</command></secondary> +<!-- <tertiary></tertiary> --> </indexterm> <indexterm> <primary><command>tid()</command></primary> - <secondary>Handlers</secondary> - <tertiary>handler functions</tertiary> + <secondary>functions</secondary> +<!-- <tertiary>handler </tertiary> --> </indexterm> <para>The ID of the current thread.</para> @@ -757,20 +757,20 @@ probe timer.s(4) <listitem> <indexterm> <primary>functions</primary> - <secondary>handler functions</secondary> - <tertiary><command>uid()</command></tertiary> + <!--<secondary>handler functions</secondary>--> + <secondary><command>uid()</command></secondary> </indexterm> - +<!-- <indexterm> <primary>handler functions</primary> <secondary>Handlers</secondary> <tertiary><command>uid()</command></tertiary> </indexterm> - + --> <indexterm> <primary><command>uid()</command></primary> - <secondary>Handlers</secondary> - <tertiary>handler functions</tertiary> + <secondary>functions</secondary> +<!-- <tertiary>handler functions</tertiary> --> </indexterm> <para>The ID of the current user.</para> </listitem> @@ -781,20 +781,20 @@ probe timer.s(4) <listitem> <indexterm> <primary>functions</primary> - <secondary>handler functions</secondary> - <tertiary><command>cpu()</command></tertiary> + <!--<secondary>handler functions</secondary>--> + <secondary><command>cpu()</command></secondary> </indexterm> - +<!-- <indexterm> <primary>handler functions</primary> <secondary>Handlers</secondary> <tertiary><command>cpu()</command></tertiary> </indexterm> - + --> <indexterm> <primary><command>cpu()</command></primary> - <secondary>Handlers</secondary> - <tertiary>handler functions</tertiary> + <secondary>functions</secondary> +<!-- <tertiary>handler functions</tertiary> --> </indexterm> <para>The current CPU number.</para> </listitem> @@ -805,20 +805,20 @@ probe timer.s(4) <listitem> <indexterm> <primary>functions</primary> - <secondary>handler functions</secondary> - <tertiary><command>gettimeofday_s()</command></tertiary> + <!--<secondary>handler functions</secondary>--> + <secondary><command>gettimeofday_s()</command></secondary> </indexterm> - +<!-- <indexterm> <primary>handler functions</primary> <secondary>Handlers</secondary> <tertiary><command>gettimeofday_s()</command></tertiary> </indexterm> - + --> <indexterm> <primary><command>gettimeofday_s()</command></primary> - <secondary>Handlers</secondary> - <tertiary>handler functions</tertiary> + <secondary>functions</secondary> +<!-- <tertiary>handler functions</tertiary> --> </indexterm> <para>The number of seconds since UNIX epoch (January 1, 1970).</para> @@ -830,20 +830,20 @@ probe timer.s(4) <listitem> <indexterm> <primary>functions</primary> - <secondary>handler functions</secondary> - <tertiary><command>ctime()</command></tertiary> + <!--<secondary>handler functions</secondary>--> + <secondary><command>ctime()</command></secondary> </indexterm> - +<!-- <indexterm> <primary>handler functions</primary> <secondary>Handlers</secondary> <tertiary><command>ctime()</command></tertiary> </indexterm> - + --> <indexterm> <primary><command>ctime()</command></primary> - <secondary>Handlers</secondary> - <tertiary>handler functions</tertiary> + <secondary>functions</secondary> +<!-- <tertiary>handler functions</tertiary> --> </indexterm> <para> Convert number of seconds since UNIX epoch to date. @@ -865,20 +865,20 @@ probe timer.s(4) <listitem> <indexterm> <primary>functions</primary> - <secondary>handler functions</secondary> - <tertiary><command>pp()</command></tertiary> + <!--<secondary>handler functions</secondary>--> + <secondary><command>pp()</command></secondary> </indexterm> - +<!-- <indexterm> <primary>handler functions</primary> <secondary>Handlers</secondary> <tertiary><command>pp()</command></tertiary> </indexterm> - + --> <indexterm> <primary><command>pp()</command></primary> - <secondary>Handlers</secondary> - <tertiary>handler functions</tertiary> + <secondary>functions</secondary> +<!-- <tertiary>handler functions</tertiary> --> </indexterm> <para>A string describing the probe point currently being handled.</para> </listitem> @@ -897,20 +897,20 @@ probe timer.s(4) <listitem> <indexterm> <primary>functions</primary> - <secondary>handler functions</secondary> - <tertiary><command>thread_indent()</command></tertiary> + <!--<secondary>handler functions</secondary>--> + <secondary><command>thread_indent()</command></secondary> </indexterm> - +<!-- <indexterm> <primary>handler functions</primary> <secondary>Handlers</secondary> <tertiary><command>thread_indent()</command></tertiary> </indexterm> - + --> <indexterm> <primary><command>thread_indent()</command></primary> - <secondary>Handlers</secondary> - <tertiary>handler functions</tertiary> + <secondary>functions</secondary> +<!-- <tertiary>handler functions</tertiary> --> </indexterm> <para> This particular function is quite useful, providing you with a way @@ -945,42 +945,42 @@ probe timer.s(4) <command>thread_indent()</command>: </para> - <example id="thread_indent"><title>thread_indent.stp</title> - <programlisting> - probe kernel.function("*@net/socket.c") - { - printf ("%s -> %s\n", thread_indent(1), probefunc()) - } - probe kernel.function("*@net/socket.c").return - { - printf ("%s <- %s\n", thread_indent(-1), probefunc()) - } - </programlisting> - </example> +<example id="thread_indent"><title>thread_indent.stp</title> +<programlisting> +probe kernel.function("*@net/socket.c") +{ + printf ("%s -> %s\n", thread_indent(1), probefunc()) +} +probe kernel.function("*@net/socket.c").return +{ + printf ("%s <- %s\n", thread_indent(-1), probefunc()) +} +</programlisting> +</example> <para> <xref linkend="thread_indent"/> prints out the <command>thread_indent()</command> and probe functions at each event in the following format:</para> - <screen> - 0 ftp(7223): -> sys_socketcall - 1159 ftp(7223): -> sys_socket - 2173 ftp(7223): -> __sock_create - 2286 ftp(7223): -> sock_alloc_inode - 2737 ftp(7223): <- sock_alloc_inode - 3349 ftp(7223): -> sock_alloc - 3389 ftp(7223): <- sock_alloc - 3417 ftp(7223): <- __sock_create - 4117 ftp(7223): -> sock_create - 4160 ftp(7223): <- sock_create - 4301 ftp(7223): -> sock_map_fd - 4644 ftp(7223): -> sock_map_file - 4699 ftp(7223): <- sock_map_file - 4715 ftp(7223): <- sock_map_fd - 4732 ftp(7223): <- sys_socket - 4775 ftp(7223): <- sys_socketcall - </screen> +<screen> +0 ftp(7223): -> sys_socketcall +1159 ftp(7223): -> sys_socket +2173 ftp(7223): -> __sock_create +2286 ftp(7223): -> sock_alloc_inode +2737 ftp(7223): <- sock_alloc_inode +3349 ftp(7223): -> sock_alloc +3389 ftp(7223): <- sock_alloc +3417 ftp(7223): <- __sock_create +4117 ftp(7223): -> sock_create +4160 ftp(7223): <- sock_create +4301 ftp(7223): -> sock_map_fd +4644 ftp(7223): -> sock_map_file +4699 ftp(7223): <- sock_map_file +4715 ftp(7223): <- sock_map_fd +4732 ftp(7223): <- sys_socket +4775 ftp(7223): <- sys_socketcall +</screen> <para>This sample output contains the following information:</para> @@ -1047,20 +1047,20 @@ probe timer.s(4) <indexterm> <primary>functions</primary> - <secondary>handler functions</secondary> - <tertiary><command>target()</command></tertiary> +<!-- <secondary>handler functions</secondary> --> + <secondary><command>target()</command></secondary> </indexterm> - +<!-- <indexterm> <primary>handler functions</primary> <secondary>Handlers</secondary> <tertiary><command>target()</command></tertiary> </indexterm> - + --> <indexterm> <primary><command>target()</command></primary> - <secondary>Handlers</secondary> - <tertiary>handler functions</tertiary> + <secondary>functions</secondary> +<!-- <tertiary>handler functions</tertiary> --> </indexterm> <para> Used in conjunction with <command>stap @@ -1073,15 +1073,15 @@ probe timer.s(4) to it. For example: </para> - <example id="targetexample"> - <title>targetexample.stp</title> - <programlisting> - probe syscall.* { - if (pid() == target()) - printf("%s/n", name) - } - </programlisting> - </example> +<example id="targetexample"> +<title>targetexample.stp</title> +<programlisting> +probe syscall.* { + if (pid() == target()) + printf("%s/n", name) +} +</programlisting> +</example> <para> When <xref linkend="targetexample"/> is run with the argument 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 4e61e247..d9fe6ab4 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 @@ -53,7 +53,7 @@ expiration, session termination, etc. A handler is a series of script language statements that specify the work to be done whenever the event occurs. This work normally includes extracting data from the event context, - storing them into internal variables, or printing results. + storing them into internal variables, and printing results. </para> <section id="understanding-architecture-tools"> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml index 098524ae..47cc4e16 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml @@ -59,7 +59,8 @@ no script in examples <remark>need to add references to sources/man pages that explain how "dev_nr = $file->f_dentry->d_inode->i_sb->s_dev" and "($1 << 20 | $2)".</remark> -<para><xref linkend="inodewatch"/> takes the following information about the file as an argument:</para> +<para><xref linkend="inodewatch"/> takes the following information about the +file as arguments on the command line:</para> <indexterm> <primary>script examples</primary> <secondary>file device number (integer format)</secondary> @@ -81,7 +82,9 @@ no script in examples </indexterm> <itemizedlist> - <listitem><para>The file's device number, in integer format. When this is passed to the script as the first argument, be sure to replace any <computeroutput>0</computeroutput> with a space.</para></listitem> + <listitem><para>The file's major device number.</para></listitem> + + <listitem><para>The file's minor device number.</para></listitem> <listitem><para>The file's <command>inode</command> number.</para></listitem> </itemizedlist> @@ -121,9 +124,9 @@ no script in examples <secondary>examples of SystemTap scripts</secondary> </indexterm> -<para><computeroutput>805</computeroutput> is the device number, while <computeroutput>1078319</computeroutput> is the <command>inode</command> number. To start monitoring <filename>/etc/crontab</filename>, run <command>stap inodewatch.stp 8 5 1078319</command>.</para> +<para><computeroutput>805</computeroutput> is the base-16 (hexadecimal) device number. The lower two digits are the minor device number and the upper digits are the major number. <computeroutput>1078319</computeroutput> is the <command>inode</command> number. To start monitoring <filename>/etc/crontab</filename>, run <command>stap inodewatch.stp 0x8 0x05 1078319</command> (The <command>0x</command> prefixes indicate base-16 values.</para> -<para>The output of this command contains the name and ID of any process performing a read/write, the function it is performing (i.e. <command>vfs_read</command> or <command>vfs_write</command>), the device number (in hex format), and the <command>inode</command> number. <xref linkend="inodewatchoutput"/> contains the output of <command>stap inodewatch.stp 8 5 1078319</command> (when <command>cat /etc/crontab</command> is executed while the script is running) :</para> +<para>The output of this command contains the name and ID of any process performing a read/write, the function it is performing (i.e. <command>vfs_read</command> or <command>vfs_write</command>), the device number (in hex format), and the <command>inode</command> number. <xref linkend="inodewatchoutput"/> contains the output of <command>stap inodewatch.stp 0x8 0x05 1078319</command> (when <command>cat /etc/crontab</command> is executed while the script is running) :</para> <example id="inodewatchoutput"> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml index 9a9e1c55..6e913b48 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml @@ -51,7 +51,7 @@ <title>socket-trace.stp</title> <para> <programlisting> - <xi:include parse="text" href="extras/testsuite/systemtap.examples/network/socket-trace.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<xi:include parse="text" href="extras/testsuite/systemtap.examples/network/socket-trace.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> </para> </formalpara> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml index 4fc7ecc2..7451de98 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml @@ -50,7 +50,7 @@ </para> <formalpara id="traceio2"> - <title>traceio2-simple.stp</title> + <title>traceio2.stp</title> <para> <programlisting> <xi:include parse="text" href="extras/testsuite/systemtap.examples/io/traceio2.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> |