From b866b7adfac0649db534a98b723b13692c1da4d9 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Mon, 8 Dec 2008 22:37:17 -0500 Subject: Edits to Scripts.xml and ScriptConstructs.xml. --- .../en-US/ScriptConstructs.xml | 67 ++++++++++++++----- doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 75 +++++++++++++--------- 2 files changed, 97 insertions(+), 45 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide/en-US') diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml index e0917280..a139015d 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml @@ -61,7 +61,8 @@ SystemTap handler constructs handlers - Variables can be used freely throughout a handler; simply choose a name, assign it to a function, and use it in an expression. SystemTap automatically identifies whether a variable should be identified as a string or integer, based on the function it is assigned to. For instance, if you use set the variable foo to gettimeofday_s() (as in foo = gettimeofday_s()), then foo can be used as an integer argument (%d) in printf(). + Variables can be used freely throughout a handler; simply choose a +name, assign a value from a function or expression to it, and use it in an expression. SystemTap automatically identifies whether a variable should be typed as a string or integer, based on the type of the values assigned to it. For instance, if you use set the variable foo to gettimeofday_s() (as in foo = gettimeofday_s()), then foo is typed as an number and can be printed in a printf() with the integer format specifier (%d). @@ -82,7 +83,7 @@ SystemTap handler constructs handlers -Note, however, that by default variables are only local to the probe they are used in. This means that variables are initialized, used and disposed at each probe handler invocation. To share a variable between probes, declare the variable name first using global outside of any probe. Consider the following example: +Note, however, that by default variables are only local to the probe they are used in. This means that variables are initialized, used and disposed at each probe handler invocation. To share a variable between probes, declare the variable name using global outside of the probes. Consider the following example: timer-jiffies.stp @@ -104,7 +105,7 @@ probe timer.ms(12345) CONFIG_HZ, computing for - attempts to compute the CONFIG_HZ setting of the kernel using timers that count jiffies and milliseconds, then computing accordingly. The global statement allows the script to use the variables count_jiffies and count_ms (set in their own respective probes) to be shared with probe timer.ms(12345). + computes the CONFIG_HZ setting of the kernel using timers that count jiffies and milliseconds, then computing accordingly. The global statement allows the script to use the variables count_jiffies and count_ms (set in their own respective probes) to be shared with probe timer.ms(12345). Note @@ -165,25 +166,38 @@ You can do this by using conditionals in handlers. SystemTa Format: -if (condition) - {statement} else {statement} +if (condition) + statement1 +else + statement2 + +The statement1 is executed if the +condition expression is +non-zero. The statement2 is +executed if the condition +expression is zero. The else is optional. Both +statement1 and +statement2 can be statement +blocks. + + ifelse.stp global countread, countnonread probe kernel.function("vfs_read"),kernel.function("vfs_write") { - if (probefunc()=="vfs_read") - countread ++ - else - countnonread ++ + if (probefunc()=="vfs_read") + countread ++ + else + countnonread ++ } probe timer.s(5) { exit() } probe end { - printf("VFS reads total %d\n VFS writes total %d\n", countread, countnonread) + printf("VFS reads total %d\n VFS writes total %d\n", countread, countnonread) } @@ -217,8 +231,17 @@ probe end Format: -while (condition) {statement} +while (condition) + statement + +So long as condition is non-zero +the block of statements in +statement are executed. The +statement is often a statement +block and it must change a value so +condition will eventually be zero. + @@ -350,7 +384,9 @@ for (argument1; argument2; SystemTap handler constructs handlers - You can also allow a SystemTap script to accept simple command-line arguments and declare them in the script without using target(). One way to do this is to use the variable notation $ or @. + You can also allow a SystemTap script to accept simple command-line arguments using a $ or @ immediately +followed by the number of the argument on the command line. Use $ if you are expecting the user to enter an integer as a command-line argument, and @ if you are expecting a string. + @@ -381,7 +417,6 @@ probe kernel.function(@1).return { } SystemTap handler constructs handlers -Both variable notations $ and @ also represent a specific variable type. Use $ if you are expecting the user to enter an integer as a command-line argument, and @ if you are expecting a string. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index e6ffc4ef..a0fc7d52 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -159,18 +159,16 @@ probe event {statements} Each probe has a corresponding statement block. This statement block is - enclosed in braces ({ }) and contains the handlers to be executed per event. - SystemTap executes these handlers (i.e. "statements") in sequence; special separators or - terminators are generally not necessary between multiple handlers. + enclosed in braces ({ }) and contains the statements to be executed per event. + SystemTap executes these statements in sequence; special separators or + terminators are generally not necessary between multiple statements. Note Statement blocks in SystemTap scripts follow the same syntax and semantics as the C - programming language. A statement block can also nest another statement block, although - for the most part this is used only to organize code in the script for the benefit of the - administrator. + programming language. A statement block can be nested within another statement block. @@ -247,7 +245,7 @@ probe event {function_name A synchronous event occurs when any process - executes an instruction that references a particular location in kernel + executes an instruction at a particular location in kernel code. This gives other events a reference point from which more contextual data may be available. @@ -351,7 +349,7 @@ probe event {function_name events wildcards - When defining functions, you can use asterisk (*) + When defining probe events, you can use asterisk (*) for wildcards. You can also trace the entry or exit of a function in a kernel source file. Consider the following example: @@ -364,14 +362,15 @@ probe kernel.function("*@net/socket.c").return { } - Wild cards also work for other things, e.g. syscall.* + Wild cards also work for other types of events, e.g. syscall.* In the previous example, the first probe's event specifies the entry of ALL functions in the kernel source file net/socket.c. The second probe specifies the - exit of all those functions. Note that in this example, no handler - was specified; as such, no information will be displayed. + exit of all those functions. Note that in this example, + there are no statements in the handler; + as such, no information will be collected or displayed. @@ -399,11 +398,19 @@ probe module("ext3").function("*").return { } - The first probe in points to the entry of all functions for the ext3 module. The second probe points to the exits of all entries for that same module; the use of the .return suffix is similar to kernel.function(). Note that the probes in also do not contain probe bodies, and as such will not print any useful data (as in ). - + The first probe in + points to the entry of all functions for + the ext3 module. The second probe points to + the exits of all functions for that same module; the use of the + .return suffix is similar to + kernel.function(). Note that the probes in + do not contain statements + in the probe handlers, and as such will not print any useful + data (as in ). + - A system's loaded modules are typically located in /lib/modules/kernel version, where kernel version refers to the currently loaded kernel. Modules use the filename extension .ko. + A system's kernel modules are typically located in /lib/modules/kernel_version, where kernel_version refers to the currently loaded kernel version. Modules use the filename extension .ko. @@ -482,8 +489,8 @@ probe module("ext3").function("*").return { } - An event that specifies a handler to be executed every specified - period of time. For example: + An event that specifies a handler to be executed periodically. + For example: timer-s.stp @@ -601,7 +608,7 @@ probe begin -printf ("format string\n", argument) +printf ("format string\n", arguments) printf() @@ -614,7 +621,7 @@ printf ("format string\n", argument The format string specifies how - argument should be printed. The format string + arguments should be printed. The format string of simply instructs SystemTap to print hello world, and contains no format specifiers. @@ -672,8 +679,8 @@ probe syscall.open instructs SystemTap to probe all entries to the system call open; for each event, it prints the - current execname() (which is a string) and - pid() (which is a number), followed by the word + current execname() (a string with the executable name) and + pid() (the current process ID number), followed by the word open. A snippet of this probe's output would look like: @@ -827,6 +834,15 @@ hald(2360) open The number of seconds since UNIX epoch (January 1, 1970). + + + ctime() + + + Convert number of seconds since UNIX epoch to date. + + +