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 | <?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.3.2. Target Variables</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="scriptconstructions.html" title="3.3. Basic SystemTap Handler Constructs" /><link rel="prev" href="scriptconstructions.html" title="3.3. Basic SystemTap Handler Constructs" /><link rel="next" href="typecasting.html" title="3.3.2.2. Typecasting" /></head><body><p id="title"></p><ul class="docnav top"><li class="previous"><a accesskey="p" href="scriptconstructions.html"><strong>Prev</strong></a></li><li class="home">SystemTap Beginners Guide</li><li class="next"><a accesskey="n" href="typecasting.html"><strong>Next</strong></a></li></ul><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="targetvariables"> </a>3.3.2. Target Variables</h3></div></div></div><a id="idm140174734582176" class="indexterm"></a><a id="idm140174734166944" class="indexterm"></a><div class="para"> The probe events that map to actual locations in the code (for example <code class="command">kernel.function("<em class="replaceable">function</em>")</code> and <code class="command">kernel.statement("<em class="replaceable">statement</em>")</code>) allow the use of <span class="emphasis"><em>target variables</em></span> to obtain the value of variables visible at that location in the code. You can use the <code class="command">-L</code> option to list the target variable available at a probe point. If the debug information is installed for the running kernel, you can run the following command to find out what target variables are available for the <code class="command">vfs_read</code> function: </div><pre class="screen">stap -L 'kernel.function("vfs_read")'</pre><div class="para"> This will yield something similar to the following: </div><pre class="screen">kernel.function("vfs_read@fs/read_write.c:277") $file:struct file* $buf:char* $count:size_t $pos:loff_t*</pre><div class="para"> Each target variable is proceeded by a <span class="quote">“<span class="quote"><code class="command">$</code></span>”</span> and the type of the target variable follows the <span class="quote">“<span class="quote"><code class="command">:</code></span>”</span>. The kernel's <code class="command">vfs_read</code> function has <code class="command">$file</code> (pointer to structure describing the file), <code class="command">$buf</code> (pointer to the user-space memory to store the read data), <code class="command">$count</code> (number of bytes to read), and <code class="command">$pos</code> (position to start reading from in the file) target variables at the entry to the function. </div><div class="para"> When a target variable is not local to the probe point, like a global external variable or a file local static variable defined in another file then it can be referenced through <span class="quote">“<span class="quote"><code class="command">@var("<em class="replaceable">varname</em>@<em class="replaceable">src/file.c</em>")</code></span>”</span>. </div><div class="para"> SystemTap tracks the typing information of the target variable and can examine the fields of a structure with the <code class="command">-></code> operator. The <code class="command">-></code> operator can be chained to look at data structures contained within data structures and follow pointers to other data structures. The <code class="command">-></code> operator will obtain the value in the field of the structure. The <code class="command">-></code> operator is used regardless whether accessing a field in a substructure or accessing another structure through a pointer. </div><div class="para"> For example to access a field of the static files_stat target variable defined in fs/file_table.c (which holds some of the current file system sysctl tunables), one could write: </div><pre class="screen"> stap -e 'probe kernel.function("vfs_read") { printf ("current files_stat max_files: %d\n", @var("files_stat@fs/file_table.c")->max_files); exit(); }' </pre><div class="para"> Which will yield something similar to the following: </div><pre class="screen"> current files_stat max_files: 386070 </pre><div class="para"> For pointers to base types such as integers and strings there are a number of functions listed below to access kernel-space data. The first argument for each functions is the pointer to the data item. Similar functions are described in <a class="xref" href="utargetvariable.html">Section 4.2, “Accessing User-Space Target Variables”</a> for accessing target variables in user-space code. </div><div class="variablelist"><dl class="variablelist"><dt><span class="term">kernel_char(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> Obtain the character at <em class="replaceable">address</em> from kernel memory. </div></dd><dt><span class="term">kernel_short(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> Obtain the short at <em class="replaceable">address</em> from kernel memory. </div></dd><dt><span class="term">kernel_int(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> Obtain the int at <em class="replaceable">address</em> from kernel memory. </div></dd><dt><span class="term">kernel_long(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> Obtain the long at <em class="replaceable">address</em> from kernel memory </div></dd><dt><span class="term">kernel_string(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> Obtain the string at <em class="replaceable">address</em> from kernel memory. </div></dd><dt><span class="term">kernel_string_n(<em class="replaceable">address</em>, <em class="replaceable">n</em>)</span></dt><dd><div class="para"> Obtain the string at <em class="replaceable">address</em> from the kernel memory and limits the string to <em class="replaceable">n</em> bytes. </div></dd></dl></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="targetprettyprinting"> </a>3.3.2.1. Pretty Printing Target Variables</h4></div></div></div><a id="idm140174738365648" class="indexterm"></a><div class="para"> SystemTap scripts are often used to observe what is happening within the code. In many cases just printing the values of the various context variables is sufficient. SystemTap makes a number operations available that can generate printable strings for target variables: </div><div class="variablelist"><dl class="variablelist"><dt><span class="term">$$vars</span></dt><dd><div class="para"> Expands to a character string that is equivalent to <code class="command">sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x", parm1, ..., parmN, var1, ..., varN)</code> for each variable in scope at the probe point. Some values may be printed as <span class="quote">“<span class="quote"><code class="command">=?</code></span>”</span> if their run-time location cannot be found. </div></dd><dt><span class="term">$$locals</span></dt><dd><div class="para"> Expands to a subset of <code class="command">$$vars</code> containing only the local variables. </div></dd><dt><span class="term">$$parms</span></dt><dd><div class="para"> Expands to a subset of <code class="command">$$vars</code> containing only the function parameters. </div></dd><dt><span class="term">$$return</span></dt><dd><div class="para"> Is available in return probes only. It expands to a string that is equivalent to <code class="command">sprintf("return=%x", $return)</code> if the probed function has a return value, or else an empty string. </div></dd></dl></div><div class="para"> Below is a command-line script that prints the values of the parameters passed into the function <code class="command">vfs_read</code>: </div><pre class="programlisting">stap -e 'probe kernel.function("vfs_read") {printf("%s\n", $$parms); exit(); }'</pre><div class="para"> There are four parameters passed into <code class="command">vfs_read</code>: <code class="command">file</code>, <code class="command">buf</code>, <code class="command">count</code>, and <code class="command">pos</code>. The <code class="command">$$parms</code> generates a string for the parameters passed into the function. In this case all but the <code class="command">count</code> parameter are pointers. The following is an example of the output from the previous command-line script: </div><pre class="programlisting">file=0xffff8800b40d4c80 buf=0x7fff634403e0 count=0x2004 pos=0xffff8800af96df48</pre><div class="para"> Having the address a pointer points to may not be useful. Instead the fields of the data structure the pointer points to may be of more use. Use the <span class="quote">“<span class="quote"><code class="command">$</code></span>”</span> suffix to pretty print the data structure. The following command-line example uses the pretty printing suffix to print more details about the data structures passed into the function <code class="command">vfs_read</code>: </div><pre class="programlisting">stap -e 'probe kernel.function("vfs_read") {printf("%s\n", $$parms$); exit(); }'</pre><div class="para"> The previous command line will generate something similar to the following with the fields of the data structure included in the output: </div><pre class="programlisting">file={.f_u={...}, .f_path={...}, .f_op=0xffffffffa06e1d80, .f_lock={...}, .f_count={...}, .f_flags=34818, .f_mode=31, .f_pos=0, .f_owner={...}, .f_cred=0xffff88013148fc80, .f_ra={...}, .f_version=0, .f_security=0xffff8800b8dce560, .private_data=0x0, .f_ep_links={...}, .f_mapping=0xffff880037f8fdf8} buf="" count=8196 pos=-131938753921208</pre><div class="para"> With the <span class="quote">“<span class="quote"><code class="command">$</code></span>”</span> suffix fields that are composed of data structures are not expanded. The <span class="quote">“<span class="quote"><code class="command">$$</code></span>”</span> suffix will print the values contained within the nested data structures. Below is an example using the <span class="quote">“<span class="quote"><code class="command">$$</code></span>”</span> suffix: </div><pre class="programlisting">stap -e 'probe kernel.function("vfs_read") {printf("%s\n", $$parms$$); exit(); }'</pre><div class="para"> The <span class="quote">“<span class="quote"><code class="command">$$</code></span>”</span> suffix, like all strings, is limited to the maximum string size. Below is a representative output from the previous command-line script, which is truncated because of the string size limit: </div><pre class="programlisting">file={.f_u={.fu_list={.next=0xffff8801336ca0e8, .prev=0xffff88012ded0840}, .fu_rcuhead={.next=0xffff8801336ca0e8, .func=0xffff88012ded0840}}, .f_path={.mnt=0xffff880132fc97c0, .dentry=0xffff88001a889cc0}, .f_op=0xffffffffa06f64c0, .f_lock={.raw_lock={.slock=196611}}, .f_count={.counter=2}, .f_flags=34818, .f_mode=31, .f_pos=0, .f_owner={.lock={.raw_lock={.lock=16777216}}, .pid=0x0, .pid_type=0, .uid=0, .euid=0, .signum=0}, .f_cred=0xffff880130129a80, .f_ra={.start=0, .size=0, .async_size=0, .ra_pages=32, .</pre></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="scriptconstructions.html"><strong>Prev</strong>3.3. Basic SystemTap Handler Constructs</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="typecasting.html"><strong>Next</strong>3.3.2.2. Typecasting</a></li></ul></body></html>
|
