diff options
Diffstat (limited to 'SystemTap_Beginners_Guide/targetvariables.html')
| -rw-r--r-- | SystemTap_Beginners_Guide/targetvariables.html | 34 |
1 files changed, 18 insertions, 16 deletions
diff --git a/SystemTap_Beginners_Guide/targetvariables.html b/SystemTap_Beginners_Guide/targetvariables.html index f0d61bda..ff16815e 100644 --- a/SystemTap_Beginners_Guide/targetvariables.html +++ b/SystemTap_Beginners_Guide/targetvariables.html | |||
| @@ -1,12 +1,13 @@ | |||
| 1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?> | 1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| 2 | <!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="publican v4.0.0" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="SystemTap-SystemTap_Beginners_Guide-2.6-en-US-2.0-1" /><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"><a class="left" href="https://fedorahosted.org/publican"><img alt="Product Site" src="Common_Content/images//image_left.png" /></a><a class="right" href="https://fedorahosted.org/publican"><img alt="Documentation Site" src="Common_Content/images//image_right.png" /></a></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="idm47951454931216" class="indexterm"></a><a id="idm47951469594800" class="indexterm"></a><div class="para"> | 2 | <!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="publican v4.1.3" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="SystemTap-SystemTap_Beginners_Guide-2.6-en-US-2.0-1" /><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"><a class="left" href="https://fedorahosted.org/publican"><img alt="Product Site" src="Common_Content/images//image_left.png" /></a><a class="right" href="https://fedorahosted.org/publican"><img alt="Documentation Site" src="Common_Content/images//image_right.png" /></a></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"> |
| 3 | The probe events that map to actual locations in the code (for example <code class="command">kernel.function("<em class="replaceable"><code>function</code></em>")</code> and <code class="command">kernel.statement("<em class="replaceable"><code>statement</code></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: | 3 | </a>3.3.2. Target Variables</h3></div></div></div><a id="idm214011621104" class="indexterm"></a><a id="idm214026509296" class="indexterm"></a><div class="para"> |
| 4 | 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: | ||
| 4 | </div><pre class="screen">stap -L 'kernel.function("vfs_read")'</pre><div class="para"> | 5 | </div><pre class="screen">stap -L 'kernel.function("vfs_read")'</pre><div class="para"> |
| 5 | This will yield something similar to the following: | 6 | This will yield something similar to the following: |
| 6 | </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"> | 7 | </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"> |
| 7 | 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. | 8 | 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. |
| 8 | </div><div class="para"> | 9 | </div><div class="para"> |
| 9 | 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"><code>varname</code></em>@<em class="replaceable"><code>src/file.c</code></em>")</code></span>”</span>. | 10 | 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>. |
| 10 | </div><div class="para"> | 11 | </div><div class="para"> |
| 11 | 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. | 12 | 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. |
| 12 | </div><div class="para"> | 13 | </div><div class="para"> |
| @@ -22,19 +23,20 @@ stap -e 'probe kernel.function("vfs_read") { | |||
| 22 | current files_stat max_files: 386070 | 23 | current files_stat max_files: 386070 |
| 23 | </pre><div class="para"> | 24 | </pre><div class="para"> |
| 24 | 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. | 25 | 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. |
| 25 | </div><div class="variablelist"><dl class="variablelist"><dt><span class="term">kernel_char(<em class="replaceable"><code>address</code></em>)</span></dt><dd><div class="para"> | 26 | </div><div class="variablelist"><dl class="variablelist"><dt><span class="term">kernel_char(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> |
| 26 | Obtain the character at <em class="replaceable"><code>address</code></em> from kernel memory. | 27 | Obtain the character at <em class="replaceable">address</em> from kernel memory. |
| 27 | </div></dd><dt><span class="term">kernel_short(<em class="replaceable"><code>address</code></em>)</span></dt><dd><div class="para"> | 28 | </div></dd><dt><span class="term">kernel_short(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> |
| 28 | Obtain the short at <em class="replaceable"><code>address</code></em> from kernel memory. | 29 | Obtain the short at <em class="replaceable">address</em> from kernel memory. |
| 29 | </div></dd><dt><span class="term">kernel_int(<em class="replaceable"><code>address</code></em>)</span></dt><dd><div class="para"> | 30 | </div></dd><dt><span class="term">kernel_int(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> |
| 30 | Obtain the int at <em class="replaceable"><code>address</code></em> from kernel memory. | 31 | Obtain the int at <em class="replaceable">address</em> from kernel memory. |
| 31 | </div></dd><dt><span class="term">kernel_long(<em class="replaceable"><code>address</code></em>)</span></dt><dd><div class="para"> | 32 | </div></dd><dt><span class="term">kernel_long(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> |
| 32 | Obtain the long at <em class="replaceable"><code>address</code></em> from kernel memory | 33 | Obtain the long at <em class="replaceable">address</em> from kernel memory |
| 33 | </div></dd><dt><span class="term">kernel_string(<em class="replaceable"><code>address</code></em>)</span></dt><dd><div class="para"> | 34 | </div></dd><dt><span class="term">kernel_string(<em class="replaceable">address</em>)</span></dt><dd><div class="para"> |
| 34 | Obtain the string at <em class="replaceable"><code>address</code></em> from kernel memory. | 35 | Obtain the string at <em class="replaceable">address</em> from kernel memory. |
| 35 | </div></dd><dt><span class="term">kernel_string_n(<em class="replaceable"><code>address</code></em>, <em class="replaceable"><code>n</code></em>)</span></dt><dd><div class="para"> | 36 | </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"> |
| 36 | Obtain the string at <em class="replaceable"><code>address</code></em> from the kernel memory and limits the string to <em class="replaceable"><code>n</code></em> bytes. | 37 | Obtain the string at <em class="replaceable">address</em> from the kernel memory and limits the string to <em class="replaceable">n</em> bytes. |
| 37 | </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="idm47951427939728" class="indexterm"></a><div class="para"> | 38 | </div></dd></dl></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="targetprettyprinting"> |
| 39 | </a>3.3.2.1. Pretty Printing Target Variables</h4></div></div></div><a id="idm213967451808" class="indexterm"></a><div class="para"> | ||
| 38 | 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: | 40 | 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: |
| 39 | </div><div class="variablelist"><dl class="variablelist"><dt><span class="term">$$vars</span></dt><dd><div class="para"> | 41 | </div><div class="variablelist"><dl class="variablelist"><dt><span class="term">$$vars</span></dt><dd><div class="para"> |
| 40 | 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. | 42 | 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. |