From c41e99c8f098302a9ed2eb4fcac6ff5e7cd79cab Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 27 Nov 2008 08:18:03 +1000 Subject: added index --- doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 453 +++++++++++++++++++++++- 1 file changed, 435 insertions(+), 18 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 b9eb036e..73f4c6b2 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -4,13 +4,54 @@
SystemTap Scripts - - + +scripts +introduction + + +SystemTap scripts +introduction + + + + + For the most part, SystemTap scripts are the foundation of each SystemTap session. SystemTap scripts instruct SystemTap on what type of information to collect, and what to do once that information is collected. - + +scripts +introduction +components + + +SystemTap scripts +introduction +components + + + + components + SystemTap scripts + introduction + + + +scripts +introduction +events and handlers + + +SystemTap scripts +introduction +events and handlers + + +handlers and events +SystemTap scripts +introduction + As stated in , SystemTap scripts are made up of two components: events and @@ -21,6 +62,21 @@ Note + +scripts +introduction +probes + + +SystemTap scripts +introduction +probes + + +probes +SystemTap scripts +introduction + An event and its corresponding handler is collectively called a probe. A SystemTap script can have multiple probes. @@ -51,6 +107,26 @@ Format + +scripts +introduction +format and syntax + + +SystemTap scripts +introduction +format and syntax + + +format and syntax +SystemTap scripts +introduction + + +syntax and format +SystemTap scripts +introduction + SystemTap scripts use the file extension .stp, and are conatains probes written in the following format: @@ -66,7 +142,21 @@ probe event {statements} single probe, SystemTap will execute the handler when any of the specified events occur. - + +scripts +introduction +statement blocks + + +SystemTap scripts +introduction +statement blocks + + +statement blocks +SystemTap scripts +introduction + Each probe has a corresponding statement block. This statement block is enclosed in braces ({ }) and contains the handlers to be executed per event. @@ -83,7 +173,21 @@ probe event {statements} administrator. - + +scripts +introduction +functions + + +SystemTap scripts +introduction +functions + + +functions +SystemTap scripts +introduction + Systemtap allows you to write functions to factor out code to be used by a number of probes. Thus, rather than repeatedly writing the same @@ -120,7 +224,10 @@ probe event {function_name
Event - + +Events +introduction + SystemTap events can be broadly classified into two types: synchronous and @@ -129,6 +236,15 @@ probe event {function_name Synchronous Events + +Events +synchronous events + + + +synchronous events +Events + A synchronous event occurs when any process executes an instruction that references a particular location in kernel @@ -140,7 +256,15 @@ probe event {function_name - + +Events +examples of synchronous and asynchronous events + + + +examples of synchronous and asynchronous events +Events + Examples of synchronous events include: @@ -148,6 +272,16 @@ probe event {function_name syscall.system_call + +Events +syscall.system_call + + + +syscall.system_call +Events + + The entry to the system call system_call. If the exit from a syscall @@ -161,13 +295,23 @@ probe event {function_name - vfs.file_op + vfs.file_operation + +Events +vfs.file_operation + + + +vfs.file_operation +Events + + - The entry to the file_op event for + The entry to the file_operation event for Virtual File System (VFS). Similar to syscall event, appending a .return to the event monitors - the exit of the file_op operation. + the exit of the file_operation operation. @@ -175,6 +319,15 @@ probe event {function_name kernel.function("function") + +Events +kernel.function("function") + + + +kernel.function("function") +Events + The entry to the kernel function function. For example, @@ -186,7 +339,17 @@ probe event {function_name string to the event statement; i.e. kernel.function("sys_open").return. - + +Events +wildcards + + + +wildcards in events + + + events wildcards + When defining functions, you can use asterisk (*) for wildcards. You can also trace the entry or exit of a function in @@ -217,6 +380,15 @@ probe kernel.function("*@net/socket.c").return { } module("module").function("function") + +Events +module("module + + + +module("module +Events + Allows you to probe functions within modules. For example: moduleprobe.stp @@ -240,6 +412,16 @@ probe module("ext3").function("*").return { } Asynchronous Events + +Events +asynchronous events + + + +asynchronous events +Events + + Asynchronous events are not tied to a particular instruction or location in code. This family of probe points consists @@ -255,6 +437,15 @@ probe module("ext3").function("*").return { } begin + +Events +begin + + + +begin +Events + The startup of a SystemTap session; i.e. as soon as the SystemTap script is run. @@ -265,12 +456,31 @@ probe module("ext3").function("*").return { } end + +Events +end + + + +end +Events + The end of a SystemTap session. timer events + +Events +timer events + + + +timer events +Events + + An event that specifies a handler to be executed every specified period of time. For example: @@ -329,10 +539,13 @@ probe timer.s(4) is reference appropriate? too advanced for readers (it seems so to me)? please advise.
- +
Systemtap Handler/Body - + +Handlers +introduction + Consider the following sample script: helloworld.stp @@ -354,6 +567,15 @@ probe begin Note + +Handlers +exit() + + + +exit() +Handlers + SystemTap scripts continue to run until the exit() function executes. If the users wants to stop @@ -364,6 +586,11 @@ probe begin printf ( ) Statements + + printf() + format strings + + The printf () statement is one of the simplest functions for printing data. printf () can also be @@ -376,14 +603,30 @@ probe begin printf ("format string\n", argument) - + +printf() +format strings + + + +format strings +printf() + The format string specifies how argument 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 @@ -394,6 +637,19 @@ printf ("format string\n", argument 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 @@ -437,7 +693,25 @@ hald(2360) open - SystemTap Functions + 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. @@ -448,6 +722,10 @@ hald(2360) open 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: @@ -455,6 +733,24 @@ hald(2360) open tid() + +Handlers +handler functions +tid() + + + +handler functions +Handlers +tid() + + + +tid() +Handlers +handler functions + + The ID of the current thread. @@ -462,6 +758,23 @@ hald(2360) open uid() + +Handlers +handler functions +uid() + + + +handler functions +Handlers +uid() + + + +uid() +Handlers +handler functions + The ID of the current user. @@ -469,6 +782,23 @@ hald(2360) open cpu() + +Handlers +handler functions +cpu() + + + +handler functions +Handlers +cpu() + + + +cpu() +Handlers +handler functions + The current CPU number. @@ -476,6 +806,24 @@ hald(2360) open 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). @@ -491,6 +839,23 @@ hald(2360) open pp() + +Handlers +handler functions +pp() + + + +handler functions +Handlers +pp() + + + +pp() +Handlers +handler functions + A string describing the probe point currently being handled. @@ -506,7 +871,24 @@ hald(2360) open thread_indent() - + +Handlers +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. When used with an indentation parameter (for example, -1), it allows the probe @@ -584,6 +966,23 @@ that thread_indent is defined in tapsets as a special function of sorts name + +Handlers +handler functions +name + + + +handler functions +Handlers +name + + + +name +Handlers +handler functions + Identifies the name of a specific system call. This function can only be used in probes that use the event syscall.system_call. @@ -594,7 +993,25 @@ that thread_indent is defined in tapsets as a special function of sorts target() - + + +Handlers +handler functions +target() + + + +handler functions +Handlers +target() + + + +target() +Handlers +handler functions + + Used in conjunction with stap script -x process ID or stap -- cgit