1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | <?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 xmlns:d="http://docbook.org/ns/docbook">3.2.2. SystemTap Handler/Body</title><link rel="stylesheet" type="text/css" href="Common_Content/css/default.css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta xmlns:d="http://docbook.org/ns/docbook" name="generator" content="not publican" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="" /><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><p id="title"></p><ul class="docnav top"><li class="previous"><a accesskey="p" href="scripts.html"><strong>Prev</strong></a></li><li class="home">SystemTap Beginners Guide</li><li class="next"><a accesskey="n" href="scriptconstructions.html"><strong>Next</strong></a></li></ul><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="systemtapscript-handler"> </a>3.2.2. SystemTap Handler/Body</h3></div></div></div><a id="id2568" class="indexterm"></a><div class="para"> Consider the following sample script: </div><div class="example"><a id="helloworld"> </a><p class="title"><strong>Example 3.4. helloworld.stp</strong></p><div class="example-contents"><pre class="programlisting">probe begin { printf ("hello world\n") exit () }</pre></div></div><div class="para"> In <a class="xref" href="systemtapscript-handler.html#helloworld">Example 3.4, “helloworld.stp”</a>, the event <code class="command">begin</code> (that is, 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 xmlns:d="http://docbook.org/ns/docbook" class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><a id="id2582" class="indexterm"></a><a id="id2586" 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><div class="para"><div xmlns:d="http://docbook.org/ns/docbook" class="title">printf ( ) Statements</div><a id="id2597" 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">format string</em>\n", <em class="replaceable">arguments</em>) </pre><a id="id2607" class="indexterm"></a><a id="id2611" class="indexterm"></a><div class="para"> The <em class="replaceable">format string</em> specifies how <em class="replaceable">arguments</em> should be printed. The format string of <a class="xref" href="systemtapscript-handler.html#helloworld">Example 3.4, “helloworld.stp”</a> instructs SystemTap to print <code class="command">hello world</code>, and contains no format specifiers. </div><a id="id2620" class="indexterm"></a><a id="id2624" 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 xmlns:d="http://docbook.org/ns/docbook" class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><a id="id2634" class="indexterm"></a><a id="id2638" class="indexterm"></a><a id="id2642" 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><div class="para"> To illustrate this, consider the following probe example: </div><div class="example"><a id="syscall-open"> </a><p class="title"><strong>Example 3.5. variables-in-printf-statements.stp</strong></p><div class="example-contents"><pre class="programlisting">probe syscall.open { printf ("%s(%d) open\n", execname(), pid()) }</pre></div></div><div class="para"> <a class="xref" href="systemtapscript-handler.html#syscall-open">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="para"><div xmlns:d="http://docbook.org/ns/docbook" class="title">SystemTap Functions</div><a id="id2664" class="indexterm"></a><a id="id2666" class="indexterm"></a><a id="id2668" 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">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 class="variablelist"><dt><span class="term">tid()</span></dt><dd><a id="id2681" class="indexterm"></a><a id="id2685" class="indexterm"></a><a id="id2689" class="indexterm"></a><div class="para">The ID of the current thread.</div></dd><dt><span class="term">uid()</span></dt><dd><a id="id2697" class="indexterm"></a><a id="id2701" class="indexterm"></a><div class="para">The ID of the current user.</div></dd><dt><span class="term">cpu()</span></dt><dd><a id="id2709" class="indexterm"></a><a id="id2713" class="indexterm"></a><div class="para">The current CPU number.</div></dd><dt><span class="term">gettimeofday_s()</span></dt><dd><a id="id2721" class="indexterm"></a><a id="id2725" 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="id2733" class="indexterm"></a><a id="id2737" 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="id2745" class="indexterm"></a><a id="id2749" 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="id2757" class="indexterm"></a><a id="id2761" class="indexterm"></a><div class="para"> This particular function is quite useful in 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"><a id="thread_indent"> </a><p class="title"><strong>Example 3.6. thread_indent.stp</strong></p><div class="example-contents"><pre class="programlisting">probe kernel.function("*@net/socket.c").call { 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></div><div class="para"> <a class="xref" href="systemtapscript-handler.html#thread_indent">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 xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">The time (in microseconds) since the initial <code class="command">thread_indent()</code> call for the thread (included in the string from <code class="command">thread_indent()</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_indent()</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="id2797" class="indexterm"></a><a id="id2800" class="indexterm"></a><a id="id2803" 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">system_call</em></code>. </div></dd><dt><span class="term">target()</span></dt><dd><a id="id2812" class="indexterm"></a><a id="id2816" class="indexterm"></a><div class="para"> Used in conjunction with <code class="command">stap <em class="replaceable">script</em> -x <em class="replaceable">process ID</em></code> or <code class="command">stap <em class="replaceable">script</em> -c <em class="replaceable">command</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"><a id="targetexample"> </a><p class="title"><strong>Example 3.7. targetexample.stp</strong></p><div class="example-contents"><pre class="programlisting">probe syscall.* { if (pid() == target()) printf("%s\n", name) }</pre></div></div><div class="para"> When <a class="xref" href="systemtapscript-handler.html#targetexample">Example 3.7, “targetexample.stp”</a> is run with the argument <code class="command">-x <em class="replaceable">process ID</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">process ID</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 pass a process ID as an argument each time you wish to run the script (that is, <code class="command">stap targetexample.stp -x <em class="replaceable">process ID</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>
|
