From c8c12f3cc2181a1964611af79d69b3ffef4e0d34 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 11 Dec 2008 15:12:45 +1000 Subject: [PATCH] edited index terms as per wcohen --- .../en-US/Array-Operations.xml | 42 +- .../en-US/Arrays.xml | 24 +- .../en-US/ScriptConstructs.xml | 18 +- .../en-US/Scripts.xml | 1141 +++++++++-------- .../en-US/Useful_Scripts-disktop.xml | 19 +- .../en-US/Useful_Scripts-iotime.xml | 22 + .../en-US/Useful_Scripts-traceio.xml | 17 + 7 files changed, 681 insertions(+), 602 deletions(-) diff --git a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml index 789bf6079..bf4963210 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml @@ -962,23 +962,23 @@ probe vfs.read array operations computing for statistical aggregates -count (integer extractor) +@count (integer extractor) operations computing for statistical aggregates -count (integer extractor) +@count (integer extractor) computing for statistical aggregates array operations -count (integer extractor) +@count (integer extractor) -count (integer extractor) + @count (integer extractor) computing for statistical aggregates array operations @@ -997,23 +997,23 @@ probe vfs.read array operations computing for statistical aggregates -sum (integer extractor) +@sum (integer extractor) operations computing for statistical aggregates -sum (integer extractor) +@sum (integer extractor) computing for statistical aggregates array operations -sum (integer extractor) +@sum (integer extractor) -sum (integer extractor) + @sum (integer extractor) computing for statistical aggregates array operations @@ -1033,23 +1033,23 @@ probe vfs.read array operations computing for statistical aggregates -min (integer extractor) +@min (integer extractor) operations computing for statistical aggregates -min (integer extractor) +@min (integer extractor) computing for statistical aggregates array operations -min (integer extractor) +@min (integer extractor) -min (integer extractor) + @min (integer extractor) computing for statistical aggregates array operations @@ -1069,23 +1069,23 @@ probe vfs.read array operations computing for statistical aggregates -max (integer extractor) +@max (integer extractor) operations computing for statistical aggregates -max (integer extractor) +@max (integer extractor) computing for statistical aggregates array operations -max (integer extractor) +@max (integer extractor) -max (integer extractor) + @max (integer extractor) computing for statistical aggregates array operations @@ -1105,23 +1105,23 @@ probe vfs.read array operations computing for statistical aggregates -avg (integer extractor) +@avg (integer extractor) operations computing for statistical aggregates -avg (integer extractor) +@avg (integer extractor) computing for statistical aggregates array operations -avg (integer extractor) +@avg (integer extractor) -avg (integer extractor) + @avg (integer extractor) computing for statistical aggregates array operations @@ -1163,7 +1163,7 @@ probe vfs.read } probe timer.s(3) { - foreach([var1,var2] in reads) + foreach([var1,var2] in reads) printf("%s (%d) : %d \n", var1, var2, @count(reads[var1,var2])) } diff --git a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml index 63c3df04d..ac320fcdc 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml @@ -6,7 +6,7 @@ Associative Arrays arrays -introduction +associative arrays @@ -20,11 +20,13 @@ + associative arrays @@ -38,14 +40,14 @@ arrays - + associative arrays introduction @@ -58,14 +60,14 @@ arrays - + associative arrays introduction @@ -78,14 +80,14 @@ arrays - + associative arrays introduction @@ -99,13 +101,13 @@ 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: - + associative arrays introduction @@ -131,14 +133,14 @@ 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: - + associative arrays introduction diff --git a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml index a139015db..2550efce4 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/ScriptConstructs.xml @@ -45,7 +45,7 @@ -SystemTap handlers + SystemTap statements SystemTap handler constructs variables @@ -73,7 +73,7 @@ name, assign a value from a function or expression to it, and use it in an expre -SystemTap handlers + SystemTap statements SystemTap handler constructs global @@ -130,7 +130,7 @@ probe timer.jiffies(100) { count_jiffies ++ } -SystemTap handlers + SystemTap statements conditional statements @@ -153,7 +153,7 @@ You can do this by using conditionals in handlers. SystemTa -SystemTap handlers + SystemTap statements conditional statements if/else @@ -219,7 +219,7 @@ probe end -SystemTap handlers + SystemTap statements conditional statements while loops @@ -271,7 +271,7 @@ printf("goodbye world\n") -SystemTap handlers + SystemTap statements conditional statements for loops @@ -326,7 +326,7 @@ while (conditional) { -SystemTap handlers + SystemTap statements conditional statements conditional operators @@ -374,7 +374,7 @@ while (conditional) { -SystemTap handlers + SystemTap statements SystemTap handler constructs command-line arguments @@ -407,7 +407,7 @@ probe kernel.function(@1).return { } -SystemTap handlers + SystemTap statements SystemTap handler constructs variable notations diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index a0fc7d526..fe2e69f4a 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -547,578 +547,599 @@ probe timer.s(4) -
- Systemtap Handler/Body - -Handlers -introduction - - Consider the following sample script: - -helloworld.stp - -probe begin -{ - printf ("hello world\n") - exit () -} - - - - - In , the event begin - (i.e. the start of the session) triggers the handler enclosed in - { }, which simply prints hello - world, then exits. - - - - Note - -Handlers -exit() - - - -exit() -Handlers - - - SystemTap scripts continue to run until the - exit() function executes. If the users wants to stop - the execution of the script, it can interrupted manually with - CtrlC. - - - - - printf ( ) Statements - - printf() - format strings - - - - The printf () statement is one of the simplest - functions for printing data. printf () can also be - used to display data using a wide variety of SystemTap functions in the - following format: - - - - - -printf ("format string\n", arguments) - - -printf() -format strings - - - -format strings -printf() - - - The format string specifies how - arguments should be printed. The format string - of simply instructs SystemTap to print - hello world, and contains no format specifiers. - - -printf() -format specifiers - - - -format specifiers -printf() - - - You can use the format specifiers %s (for strings) - and %d (for numbers) in format strings, depending on - your list of arguments. Format strings can have multiple format - specifiers, each matching a corresponding argument; multiple arguments - are delimited by a comma (,). - - - - Note - -printf() -syntax and format - - - -syntax and format -printf() - - -format and syntax -printf() - - Semantically, the SystemTap printf function is - very similar to its C language counterpart. The aforementioned syntax - and format for SystemTap's printf function is - identical to that of the C-style printf. - - - - To illustrate this, consider the following probe example: - - -variables-in-printf-statements.stp - -probe syscall.open -{ - printf ("%s(%d) open\n", execname(), pid()) -} - - - - - instructs SystemTap to probe all entries to - the system call open; for each event, it prints the - 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: - - - editorial review: does a clarification that "format specifier1" is - to "argument1", "format specifier2" is to "argument2", or is this clear - enough? - - -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 - - - - SystemTap Functions - -functions - - - -SystemTap script functions - - - - Handlers - handler functions - - - - handler functions - Handlers - - - - SystemTap supports a wide variety of functions that can be used as - printf () arguments. - uses the SystemTap functions execname() (name of the - process that called a kernel function/performed a system call) and - pid() (current process ID). - - - - is "handler function" an appropriate term? wcohen: use "SystemTap functions" to match up language in man pages - -Handlers -handler functions - - - The following is a list of commonly-used SystemTap functions: - - - - tid() - - -Handlers -handler functions -tid() - - - -handler functions -Handlers -tid() - - - -tid() -Handlers -handler functions - - - The ID of the current thread. - - - - - uid() - - -Handlers -handler functions -uid() - - - -handler functions -Handlers -uid() - - - -uid() -Handlers -handler functions - - The ID of the current user. - - - - - cpu() - - -Handlers -handler functions -cpu() - - - -handler functions -Handlers -cpu() - - - -cpu() -Handlers -handler functions - - The current CPU number. - - - - - gettimeofday_s() - - -Handlers -handler functions -gettimeofday_s() - - - -handler functions -Handlers -gettimeofday_s() - - - -gettimeofday_s() -Handlers -handler functions - - - The number of seconds since UNIX epoch (January 1, 1970). - - - - - ctime() - - - Convert number of seconds since UNIX epoch to date. - - - - - - - pp() - - -Handlers -handler functions -pp() - - - -handler functions -Handlers -pp() - - - -pp() -Handlers -handler functions - - A string describing the probe point currently being handled. - - - - - - thread_indent() - - -Handlers -handler functions -thread_indent() - - - -handler functions -Handlers -thread_indent() - - - -thread_indent() -Handlers -handler functions - +
+ Systemtap Handler/Body + + handlers + introduction + + Consider the following sample script: + + helloworld.stp + + probe begin + { + printf ("hello world\n") + exit () + } + + + - This particular function is quite useful, providing you with a way - to better organize your print results. The function takes one - argument, an indentation delta, which indicates how many - spaces to add or remove from a thread's "indentation counter". - It then returns a - string with some generic trace data along with an appropriate number - of indentation spaces. - - - - The generic data included in the returned string includes a - timestamp (number of microseconds since the - first call to thread_indent() by the thread), - a process name, and the thread ID. This allows you to - identify what functions were called, who called them, and the - duration of each function call. - - - - If call entries and exits immediately precede each other, it is easy - to match them. However, in most cases, after a first function call - entry is made several other call entries and exits may be made - before the first call exits. The indentation counter helps you match - an entry with its corresponding exit by indenting the next function - call if it is not the exit of the previous one. - + In , the event begin + (i.e. the start of the session) triggers the handler enclosed in + { }, which simply prints hello + world, then exits. + + + + Note + + functions (used in handlers) + exit() + - - Consider the following example on the use of - thread_indent(): - + + exit() + Handlers + + + SystemTap scripts continue to run until the + exit() function executes. If the users wants to stop + the execution of the script, it can interrupted manually with + CtrlC. + + + + + printf ( ) Statements + + printf() + format strings + -thread_indent.stp - -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()) -} - - - - - prints out the - thread_indent() and probe functions at each event - in the following format: + + The printf () statement is one of the simplest + functions for printing data. printf () can also be + used to display data using a wide variety of SystemTap functions in the + following format: + + - - 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 - - -This sample output contains the following information: - - - The time (in microseconds) since the initial thread_ident() call for the thread (included in the string from thread_ident()). - The process name (and its corresponding ID) that made the function call (included in the string from thread_ident()). + + printf ("format string\n", arguments) + + + printf() + format strings + - An arrow signifying whether the call was an entry (<-) or an exit (->); the indentations help you match specific function call entries with their corresponding exits. + + format strings + printf() + + + The format string specifies how + arguments should be printed. The format string + of simply instructs SystemTap to print + hello world, and contains no format specifiers. + + + printf() + format specifiers + - The name of the function called by the process. - - -remember to add a reference later to "tapsets" from here, to clarify -that thread_indent is defined in tapsets as a special function of sorts + + format specifiers + printf() + + + You can use the format specifiers %s (for strings) + and %d (for numbers) in format strings, depending on + your list of arguments. Format strings can have multiple format + specifiers, each matching a corresponding argument; multiple arguments + are delimited by a comma (,). + + + + Note + + printf() + syntax and format + + + + syntax and format + printf() + + + format and syntax + printf() + + Semantically, the SystemTap printf function is + very similar to its C language counterpart. The aforementioned syntax + and format for SystemTap's printf function is + identical to that of the C-style printf. + + + + To illustrate this, consider the following probe example: + + + variables-in-printf-statements.stp + + probe syscall.open + { + printf ("%s(%d) open\n", execname(), pid()) + } + + - - - - - name - - -Handlers -handler functions -name - - - -handler functions -Handlers -name - - - -name -Handlers -handler functions - - Identifies the name of a specific system call. This variable can - only be used in probes that use the event - syscall.system_call. - - - - - - target() - - - -Handlers -handler functions -target() - - - -handler functions -Handlers -target() - - - -target() -Handlers -handler functions - - Used in conjunction with stap - script -x process - ID or stap - script -c - command. If you want to specify - a script to take an argument of a process ID or command, use - target() as the variable in the script to refer - to it. For example: - - - -targetexample.stp - -probe syscall.* { - if (pid() == target()) - printf("%s/n", name) -} - - - - - When is run with the argument - -x process ID, it - watches all system calls (as specified by the event - syscall.*) and prints out the name of all system - calls made by the specified process. - + instructs SystemTap to probe all entries to + the system call open; for each event, it prints the + 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: + - - This has the same effect as specifying if (pid() == - process ID) each time you wish - to target a specific process. However, using - target() makes it easier for you to re-use the - script, giving you the ability to simply pass a process ID as an - argument each time you wish to run the script (e.g. stap - targetexample.stp -x process ID). - - - - - - - - - - For more information about supported SystemTap functions, refer to - man stapfuncs. - - -will need a complete listing of supported handler functions? also, SystemTap function descriptions seem ambiguous, please advise. - - - + + handler functions + + + + SystemTap supports a wide variety of functions that can be used as + printf () arguments. + uses the SystemTap functions execname() (name of the + process that called a kernel function/performed a system call) and + pid() (current process ID). + + + + is "handler function" an appropriate term? wcohen: use "SystemTap functions" to match up language in man pages + + The following is a list of commonly-used SystemTap functions: + + + + tid() + + + functions + handler functions + tid() + + + + handler functions + Handlers + tid() + + + + tid() + Handlers + handler functions + + + The ID of the current thread. + + + + + uid() + + + functions + handler functions + uid() + + + + handler functions + Handlers + uid() + + + + uid() + Handlers + handler functions + + The ID of the current user. + + + + + cpu() + + + functions + handler functions + cpu() + + + + handler functions + Handlers + cpu() + + + + cpu() + Handlers + handler functions + + The current CPU number. + + + + + gettimeofday_s() + + + functions + handler functions + gettimeofday_s() + + + + handler functions + Handlers + gettimeofday_s() + + + + gettimeofday_s() + Handlers + handler functions + + + The number of seconds since UNIX epoch (January 1, 1970). + + + + + ctime() + + + functions + handler functions + ctime() + + + + handler functions + Handlers + ctime() + + + + ctime() + Handlers + handler functions + + + Convert number of seconds since UNIX epoch to date. + + + + + + + + pp() + + + functions + handler functions + pp() + + + + handler functions + Handlers + pp() + + + + pp() + Handlers + handler functions + + A string describing the probe point currently being handled. + + + + + + thread_indent() + + + functions + handler functions + thread_indent() + + + + handler functions + Handlers + thread_indent() + + + + thread_indent() + Handlers + handler functions + + + This particular function is quite useful, providing you with a way + to better organize your print results. The function takes one + argument, an indentation delta, which indicates how many + spaces to add or remove from a thread's "indentation counter". + It then returns a + string with some generic trace data along with an appropriate number + of indentation spaces. + + + + The generic data included in the returned string includes a + timestamp (number of microseconds since the + first call to thread_indent() by the thread), + a process name, and the thread ID. This allows you to + identify what functions were called, who called them, and the + duration of each function call. + + + + If call entries and exits immediately precede each other, it is easy + to match them. However, in most cases, after a first function call + entry is made several other call entries and exits may be made + before the first call exits. The indentation counter helps you match + an entry with its corresponding exit by indenting the next function + call if it is not the exit of the previous one. + + + + Consider the following example on the use of + thread_indent(): + + + thread_indent.stp + + 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()) + } + + + + + prints out the + thread_indent() and probe functions at each event + in the following format: + + + 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 + + + This sample output contains the following information: + + + The time (in microseconds) since the initial thread_ident() call for the thread (included in the string from thread_ident()). + + The process name (and its corresponding ID) that made the function call (included in the string from thread_ident()). + + An arrow signifying whether the call was an entry (<-) or an exit (->); the indentations help you match specific function call entries with their corresponding exits. + + The name of the function called by the process. + + + remember to add a reference later to "tapsets" from here, to clarify + that thread_indent is defined in tapsets as a special function of sorts + + + + + + name + + +local variables +name + + + +variables (local) +name + + + +name +local variables + + + Identifies the name of a specific system call. This variable can + only be used in probes that use the event + syscall.system_call. + + + + + + target() + + + + functions + handler functions + target() + + + + handler functions + Handlers + target() + + + + target() + Handlers + handler functions + + + Used in conjunction with stap + script -x process + ID or stap + script -c + command. If you want to specify + a script to take an argument of a process ID or command, use + target() as the variable in the script to refer + to it. For example: + + + + targetexample.stp + + probe syscall.* { + if (pid() == target()) + printf("%s/n", name) + } + + + + + When is run with the argument + -x process ID, it + watches all system calls (as specified by the event + syscall.*) and prints out the name of all system + calls made by the specified process. + + + + This has the same effect as specifying if (pid() == + process ID) each time you wish + to target a specific process. However, using + target() makes it easier for you to re-use the + script, giving you the ability to simply pass a process ID as an + argument each time you wish to run the script (e.g. stap + targetexample.stp -x process ID). + + + + + + + + + + For more information about supported SystemTap functions, refer to + man stapfuncs. + + + will need a complete listing of supported handler functions? also, SystemTap function descriptions seem ambiguous, please advise. + + +
-
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml index 42f1986b0..8a786d82a 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml @@ -107,7 +107,24 @@ The time and date in the output of is returned by the functions ctime() and gettimeofday_s(). ctime() derives calendar time in terms of seconds passed since the Unix epoch (January 1, 1970). gettimeofday_s() counts the actual number of seconds since Unix epoch, which gives a fairly accurate human-readable timestamp for the output. - + + + local variables + sample usage + $return + + + + variables (local) + sample usage + $return + + + + $return + sample usage + local variables + In this script, the $return is a local variable that stores the actual number of bytes each process reads or writes from the virtual file system. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml index 7a1633aa7..4d7d6b17c 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml @@ -52,6 +52,26 @@ of microseconds it takes for any reads or writes to finish and tracks the amount of data (in bytes) read from or written to the file. + + + + local variables + sample usage + $count + + + + variables (local) + sample usage + $count + + + + $count + sample usage + local variables + + also uses the local variable $count to track the @@ -70,8 +90,10 @@ [...] 825946 3364 (NetworkManager) access /sys/class/net/eth0/carrier read: 8190 write: 0 825955 3364 (NetworkManager) iotime /sys/class/net/eth0/carrier time: 9 +[...] 117061 2460 (pcscd) access /dev/bus/usb/003/001 read: 43 write: 0 117065 2460 (pcscd) iotime /dev/bus/usb/003/001 time: 7 +[...] 3973737 2886 (sendmail) access /proc/loadavg read: 4096 write: 0 3973744 2886 (sendmail) iotime /proc/loadavg time: 11 [...] diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml index ab260d63c..1af1475d7 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml @@ -55,7 +55,24 @@ executables. This information is tracked and printed out in 1-second intervals, and in descending order. + + + local variables + sample usage + $return + + + variables (local) + sample usage + $return + + + + $return + sample usage + local variables + Note that also uses the local variable $return, which is also used by from . -- 2.43.5