From 6f57b072898d1858e0af448169c759dd44efddca Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 11 Sep 2008 12:06:50 +1000 Subject: [PATCH] added Handlers description, more cleanup --- .../en-US/Scripts.xml | 157 +++++++++++++++++- 1 file changed, 152 insertions(+), 5 deletions(-) diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index 24ab8a837..d61ec1cfb 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -32,7 +32,7 @@ SystemTap scripts use the file extension .stp, and are written in the following format: - + probe [event], [another event] @@ -41,7 +41,7 @@ probe [event], exit() } - + The exit() condition is optional, but it is recommended since it safely terminates the session once the script successfully traps the required information. @@ -108,17 +108,164 @@ probe kernel.function("*@net/socket.c").return { } - + + Important + + SystemTap supports the use of a large collection of probe events. For more information about supported events, refer to man stapprobes. The SEE ALSO section of man stapprobes also contains links to other man pages that discuss supported events for specific subsystems and components. + +
Handlers - SystemTap supports a wide variety of functions that can trap data when triggered by events. One way to display these functions is to use the print() +Consider the following sample script: + + +Hello World + +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. + + + + printf ( ) Statements + + The printf () statement is one of the simplest handler tools for printing data. printf () can also be used to trap data using a wide variety of SystemTap handler functions using the following format: + + + + +printf ("[format string]\n", [argument]) + + + + The [format string] region specifies how [argument] should be displayed. The format string of simply instructs SystemTap to print hello world, and contains no arguments. + + + + You can use the variables %s (for strings) and %d (for numbers) in format strings, depending on your list of arguments. Format strings can have multiple variables, each matching a corresponding argument; multiple arguments are delimited by a comma (,) and space. + + + + To illustrate this, consider the following probe example: + + + + Using Variables In printf ( ) Statements + +# This probe will need to be manually terminated with Ctrl-C +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() (which is a string) and pid() (which is a number), followed by the word open. A snippet of this probe's output would look like: + + + +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 + + + + Handler Functions + SystemTap supports a wide variety of handler functions that can be used as printf () arguments. uses the handler functions execname() (current process name) and pid() (current process ID). + + The following is a list of commonly-used handler functions: + + + + + tid() + + The ID of the current thread. + + + + + uid() + + The ID of the current user. + + + + + cpu() + + The current CPU number. + + + + + gettimeofday_s() + + The number of seconds since UNIX epoch (January 1, 1970). + + + + + get_cycles() + + A snapshot of the hardware cycle counter. + + + + + pp() + + A string describing the probe point currently being handled. + + + + + probefunc() + + If known, the name of the function in which the probe was placed. + + + + + +For more information about supported handler functions, refer to man stapfuncs. + + +