From 5340b57d969f027695befa58909d5eb9ff59d006 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Fri, 26 Sep 2008 14:28:21 +1000 Subject: added Usage item --- doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 32 ++++++++++++++++++++----- 1 file changed, 26 insertions(+), 6 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 e8f9c3cb..160597bf 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -45,7 +45,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. + The exit() condition is optional; this condition safely terminates the session once the script successfully traps the required information the first time. Important @@ -68,7 +68,7 @@ probe [event], kernel.function("[function]") - The entry to the kernel function function. For example, kernel.function("sys_open") refers to the "event" that the kernel function sys_open is used. To specify the return of the kernel function sys_open, append the return string to the event statement; i.e. kernel.function("sys_open").return. + The entry to the kernel function function. For example, kernel.function("sys_open") refers to the "event" that occurs when the kernel function sys_open is called by any thread in the system. To specify the return of the kernel function sys_open, append the return string to the event statement; i.e. kernel.function("sys_open").return. When defining functions, you can use asterisk (*) for wildcards. You can also trace the entry/exit of a function in a kernel source file. Consider the following example: Wildcards and Kernel Source Files in an Event @@ -142,7 +142,7 @@ probe kernel.function("*@net/socket.c").return { } - timer.ms() + timer events An event that specifies a handler to be executed "after X number of milliseconds". For example: @@ -156,7 +156,23 @@ probe timer.ms(4000) - is an example of a probe that allows you to terminate the script after 4000 milliseconds (or 4 seconds). When used in conjunction with another probe that traps a large quantity of data, a probe using timer.ms() allows you to limit the information your script is collecting (and printing out). + is an example of a probe that allows you to terminate the script after 4000 milliseconds. Note that you can also use the following timer events: + + + +timer.s([seconds]) + +timer.us([microseconds]) + +timer.ns([nanoseconds]) + +timer.hz([hertz]) + +timer.jiffies([jiffies]) + + + + When used in conjunction with another probe that traps a large quantity of data, timer events allow you to limit the information your script is collecting (and printing out). @@ -215,11 +231,10 @@ probe begin 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: + The printf () statement is one of the simplest functions for printing data. printf () can also be used to trap data using a wide variety of SystemTap handler functions using the following format: -is "handler tool" appropriate? @@ -234,6 +249,11 @@ printf ("[format string]\n", [argument]< 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. + + Note + 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: -- cgit