From c8c12f3cc2181a1964611af79d69b3ffef4e0d34 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 11 Dec 2008 15:12:45 +1000 Subject: edited index terms as per wcohen --- doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 1141 ++++++++++++----------- 1 file changed, 581 insertions(+), 560 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide/en-US/Scripts.xml') diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index a0fc7d52..fe2e69f4 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. + + +
-
-- cgit