<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.2.2. Systemtap Handler/Body</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css" /><meta name="generator" content="publican 1.6" /><meta name="package" content="Systemtap-SystemTap_Beginners_Guide-1.0-en-US-2.0-2" /><link rel="home" href="index.html" title="SystemTap Beginners Guide" /><link rel="up" href="scripts.html" title="3.2. SystemTap Scripts" /><link rel="prev" href="scripts.html" title="3.2. SystemTap Scripts" /><link rel="next" href="scriptconstructions.html" title="3.3. Basic SystemTap Handler Constructs" /></head><body class=""><p id="title"><a class="left" href="http://www.fedoraproject.org"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="http://docs.fedoraproject.org"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="scripts.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="scriptconstructions.html"><strong>Next</strong></a></li></ul><div class="section" title="3.2.2. Systemtap Handler/Body"><div class="titlepage"><div><div><h3 class="title" id="systemtapscript-handler">3.2.2. Systemtap Handler/Body</h3></div></div></div><a id="id2808650" class="indexterm"></a><div class="para">
Consider the following sample script:
</div><div class="example" id="helloworld"><div class="example-contents"><pre class="programlisting">
probe begin
{
printf ("hello world\n")
exit ()
}
</pre></div><h6>Example 3.4. helloworld.stp</h6></div><br class="example-break" /><div class="para">
In <a class="xref" href="systemtapscript-handler.html#helloworld" title="Example 3.4. helloworld.stp">Example 3.4, “helloworld.stp”</a>, the event <code class="command">begin</code> (i.e. the start of the session) triggers the handler enclosed in <code class="command">{ }</code>, which simply prints <code class="command">hello world</code> followed by a new-line, then exits.
</div><div class="note"><h2>Note</h2><a id="id2808588" class="indexterm"></a><a id="id2808577" class="indexterm"></a><div class="para">
SystemTap scripts continue to run until the <code class="command">exit()</code> function executes. If the users wants to stop the execution of the script, it can interrupted manually with <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>C</strong></span>.
</div></div><div class="formalpara"><h5 class="formalpara" id="printf">printf ( ) Statements</h5><a id="id2808532" class="indexterm"></a>
The <code class="command">printf ()</code> statement is one of the simplest functions for printing data. <code class="command">printf ()</code> can also be used to display data using a wide variety of SystemTap functions in the following format:
</div><pre class="programlisting">
printf ("<em class="replaceable"><code>format string</code></em>\n", <em class="replaceable"><code>arguments</code></em>)
</pre><a id="id2808487" class="indexterm"></a><a id="id2977510" class="indexterm"></a><div class="para">
The <em class="replaceable"><code>format string</code></em> specifies how <em class="replaceable"><code>arguments</code></em> should be printed. The format string of <a class="xref" href="systemtapscript-handler.html#helloworld" title="Example 3.4. helloworld.stp">Example 3.4, “helloworld.stp”</a> simply instructs SystemTap to print <code class="command">hello world</code>, and contains no format specifiers.
</div><a id="id2977476" class="indexterm"></a><a id="id2977461" class="indexterm"></a><div class="para">
You can use the format specifiers <code class="command">%s</code> (for strings) and <code class="command">%d</code> (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 (<code class="command">,</code>).
</div><div class="note"><h2>Note</h2><a id="id2977423" class="indexterm"></a><a id="id2977411" class="indexterm"></a><a id="id2977386" class="indexterm"></a><div class="para">
Semantically, the SystemTap <code class="command">printf</code> function is very similar to its C language counterpart. The aforementioned syntax and format for SystemTap's <code class="command">printf</code> function is identical to that of the C-style <code class="command">printf</code>.
</div></div><div class="para">
To illustrate this, consider the following probe example:
</div><div class="example" id="syscall-open"><div class="example-contents"><pre class="programlisting">
probe syscall.open
{
printf ("%s(%d) open\n", execname(), pid())
}
</pre></div><h6>Example 3.5. variables-in-printf-statements.stp</h6></div><br class="example-break" /><div class="para">
<a class="xref" href="systemtapscript-handler.html#syscall-open" title="Example 3.5. variables-in-printf-statements.stp">Example 3.5, “variables-in-printf-statements.stp”</a> instructs SystemTap to probe all entries to the system call <code class="command">open</code>; for each event, it prints the current <code class="command">execname()</code> (a string with the executable name) and <code class="command">pid()</code> (the current process ID number), followed by the word <code class="command">open</code>. A snippet of this probe's output would look like:
</div><pre class="screen">
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
</pre><div class="formalpara"><h5 class="formalpara" id="systemtapscript-functions">SystemTap Functions</h5><a id="id2804619" class="indexterm"></a><a id="id2804609" class="indexterm"></a><a id="id2804600" class="indexterm"></a>
SystemTap supports a wide variety of functions that can be used as <code class="command">printf ()</code> arguments. <a class="xref" href="systemtapscript-handler.html#syscall-open" title="Example 3.5. variables-in-printf-statements.stp">Example 3.5, “variables-in-printf-statements.stp”</a> uses the SystemTap functions <code class="command">execname()</code> (name of the process that called a kernel function/performed a system call) and <code class="command">pid()</code> (current process ID).
</div><div class="para">
The following is a list of commonly-used SystemTap functions:
</div><div class="variablelist"><dl><dt><span class="term">tid()</span></dt><dd><a id="id2804546" class="indexterm"></a><a id="id2804527" class="indexterm"></a><a id="id2804510" class="indexterm"></a><div class="para">
The ID of the current thread.
</div></dd><dt><span class="term">uid()</span></dt><dd><a id="id2804471" class="indexterm"></a><a id="id2750620" class="indexterm"></a><div class="para">
The ID of the current user.
</div></dd><dt><span class="term">cpu()</span></dt><dd><a id="id2750587" class="indexterm"></a><a id="id2750569" class="indexterm"></a><div class="para">
The current CPU number.
</div></dd><dt><span class="term">gettimeofday_s()</span></dt><dd><a id="id2750533" class="indexterm"></a><a id="id2750514" class="indexterm"></a><div class="para">
The number of seconds since UNIX epoch (January 1, 1970).
</div></dd><dt><span class="term">ctime()</span></dt><dd><a id="id2750468" class="indexterm"></a><a id="id2750451" class="indexterm"></a><div class="para">
Convert number of seconds since UNIX epoch to date.
</div></dd><dt><span class="term">pp()</span></dt><dd><a id="id3111450" class="indexterm"></a><a id="id3111432" class="indexterm"></a><div class="para">
A string describing the probe point currently being handled.
</div></dd><dt><span class="term">thread_indent()</span></dt><dd><a id="id3111396" class="indexterm"></a><a id="id3111378" class="indexterm"></a><div class="para">
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.
</div><div class="para">
The generic data included in the returned string includes a timestamp (number of microseconds since the first call to <code class="command">thread_indent()</code> 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.
</div><div class="para">
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.
</div><div class="para">
Consider the following example on the use of <code class="command">thread_indent()</code>:
</div><div class="example" id="thread_indent"><div class="example-contents"><pre class="programlisting">
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())
}
</pre></div><h6>Example 3.6. thread_indent.stp</h6></div><br class="example-break" /><div class="para">
<a class="xref" href="systemtapscript-handler.html#thread_indent" title="Example 3.6. thread_indent.stp">Example 3.6, “thread_indent.stp”</a> prints out the <code class="command">thread_indent()</code> and probe functions at each event in the following format:
</div><pre class="screen">
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
</pre><div class="para">
This sample output contains the following information:
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
The time (in microseconds) since the initial <code class="command">thread_ident()</code> call for the thread (included in the string from <code class="command">thread_ident()</code>).
</div></li><li class="listitem"><div class="para">
The process name (and its corresponding ID) that made the function call (included in the string from <code class="command">thread_ident()</code>).
</div></li><li class="listitem"><div class="para">
An arrow signifying whether the call was an entry (<code class="computeroutput"><-</code>) or an exit (<code class="computeroutput">-></code>); the indentations help you match specific function call entries with their corresponding exits.
</div></li><li class="listitem"><div class="para">
The name of the function called by the process.
</div></li></ul></div></dd><dt><span class="term">name</span></dt><dd><a id="id2828719" class="indexterm"></a><a id="id2828693" class="indexterm"></a><a id="id2828671" class="indexterm"></a><div class="para">
Identifies the name of a specific system call. This variable can only be used in probes that use the event <code class="command">syscall.<em class="replaceable"><code>system_call</code></em></code>.
</div></dd><dt><span class="term">target()</span></dt><dd><a id="id2828602" class="indexterm"></a><a id="id2796899" class="indexterm"></a><div class="para">
Used in conjunction with <code class="command">stap <em class="replaceable"><code>script</code></em> -x <em class="replaceable"><code>process ID</code></em></code> or <code class="command">stap <em class="replaceable"><code>script</code></em> -c <em class="replaceable"><code>command</code></em></code>. If you want to specify a script to take an argument of a process ID or command, use <code class="command">target()</code> as the variable in the script to refer to it. For example:
</div><div class="example" id="targetexample"><div class="example-contents"><pre class="programlisting">
probe syscall.* {
if (pid() == target())
printf("%s/n", name)
}
</pre></div><h6>Example 3.7. targetexample.stp</h6></div><br class="example-break" /><div class="para">
When <a class="xref" href="systemtapscript-handler.html#targetexample" title="Example 3.7. targetexample.stp">Example 3.7, “targetexample.stp”</a> is run with the argument <code class="command">-x <em class="replaceable"><code>process ID</code></em></code>, it watches all system calls (as specified by the event <code class="command">syscall.*</code>) and prints out the name of all system calls made by the specified process.
</div><div class="para">
This has the same effect as specifying <code class="command">if (pid() == <em class="replaceable"><code>process ID</code></em>)</code> each time you wish to target a specific process. However, using <code class="command">target()</code> 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. <code class="command">stap targetexample.stp -x <em class="replaceable"><code>process ID</code></em></code>).
</div></dd></dl></div><div class="para">
For more information about supported SystemTap functions, refer to <code class="command">man stapfuncs</code>.
</div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="scripts.html"><strong>Prev</strong>3.2. SystemTap Scripts</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="scriptconstructions.html"><strong>Next</strong>3.3. Basic SystemTap Handler Constructs</a></li></ul></body></html>
