1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Static Probe Points</title> 18 19<meta name="description" content="Debugging with GDB: Static Probe Points"> 20<meta name="keywords" content="Debugging with GDB: Static Probe Points"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Breakpoints.html#Breakpoints" rel="up" title="Breakpoints"> 29<link href="Error-in-Breakpoints.html#Error-in-Breakpoints" rel="next" title="Error in Breakpoints"> 30<link href="Save-Breakpoints.html#Save-Breakpoints" rel="previous" title="Save Breakpoints"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Static-Probe-Points"></a> 65<div class="header"> 66<p> 67Next: <a href="Error-in-Breakpoints.html#Error-in-Breakpoints" accesskey="n" rel="next">Error in Breakpoints</a>, Previous: <a href="Save-Breakpoints.html#Save-Breakpoints" accesskey="p" rel="previous">Save Breakpoints</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Static-Probe-Points-1"></a> 71<h4 class="subsection">5.1.10 Static Probe Points</h4> 72 73<a name="index-static-probe-point_002c-SystemTap"></a> 74<a name="index-static-probe-point_002c-DTrace"></a> 75<p><small>GDB</small> supports <em>SDT</em> probes in the code. <acronym>SDT</acronym> stands 76for Statically Defined Tracing, and the probes are designed to have a tiny 77runtime code and data footprint, and no dynamic relocations. 78</p> 79<p>Currently, the following types of probes are supported on 80ELF-compatible systems: 81</p> 82<ul> 83<li> <code>SystemTap</code> (<a href="http://sourceware.org/systemtap/">http://sourceware.org/systemtap/</a>) 84<acronym>SDT</acronym> probes<a name="DOCF5" href="#FOOT5"><sup>5</sup></a>. <code>SystemTap</code> probes are usable 85from assembly, C and C<tt>++</tt> languages<a name="DOCF6" href="#FOOT6"><sup>6</sup></a>. 86 87</li><li> <code>DTrace</code> (<a href="http://oss.oracle.com/projects/DTrace">http://oss.oracle.com/projects/DTrace</a>) 88<acronym>USDT</acronym> probes. <code>DTrace</code> probes are usable from C and 89C<tt>++</tt> languages. 90</li></ul> 91 92<a name="index-semaphores-on-static-probe-points"></a> 93<p>Some <code>SystemTap</code> probes have an associated semaphore variable; 94for instance, this happens automatically if you defined your probe 95using a DTrace-style <samp>.d</samp> file. If your probe has a semaphore, 96<small>GDB</small> will automatically enable it when you specify a 97breakpoint using the ‘<samp>-probe-stap</samp>’ notation. But, if you put a 98breakpoint at a probe’s location by some other method (e.g., 99<code>break file:line</code>), then <small>GDB</small> will not automatically set 100the semaphore. <code>DTrace</code> probes do not support semaphores. 101</p> 102<p>You can examine the available static static probes using <code>info 103probes</code>, with optional arguments: 104</p> 105<dl compact="compact"> 106<dd><a name="index-info-probes"></a> 107</dd> 108<dt><code>info probes <span class="roman">[</span><var>type</var><span class="roman">]</span> <span class="roman">[</span><var>provider</var> <span class="roman">[</span><var>name</var> <span class="roman">[</span><var>objfile</var><span class="roman">]</span><span class="roman">]</span><span class="roman">]</span></code></dt> 109<dd><p>If given, <var>type</var> is either <code>stap</code> for listing 110<code>SystemTap</code> probes or <code>dtrace</code> for listing <code>DTrace</code> 111probes. If omitted all probes are listed regardless of their types. 112</p> 113<p>If given, <var>provider</var> is a regular expression used to match against provider 114names when selecting which probes to list. If omitted, probes by all 115probes from all providers are listed. 116</p> 117<p>If given, <var>name</var> is a regular expression to match against probe names 118when selecting which probes to list. If omitted, probe names are not 119considered when deciding whether to display them. 120</p> 121<p>If given, <var>objfile</var> is a regular expression used to select which 122object files (executable or shared libraries) to examine. If not 123given, all object files are considered. 124</p> 125</dd> 126<dt><code>info probes all</code></dt> 127<dd><p>List the available static probes, from all types. 128</p></dd> 129</dl> 130 131<a name="index-enabling-and-disabling-probes"></a> 132<p>Some probe points can be enabled and/or disabled. The effect of 133enabling or disabling a probe depends on the type of probe being 134handled. Some <code>DTrace</code> probes can be enabled or 135disabled, but <code>SystemTap</code> probes cannot be disabled. 136</p> 137<p>You can enable (or disable) one or more probes using the following 138commands, with optional arguments: 139</p> 140<dl compact="compact"> 141<dd><a name="index-enable-probes"></a> 142</dd> 143<dt><code>enable probes <span class="roman">[</span><var>provider</var> <span class="roman">[</span><var>name</var> <span class="roman">[</span><var>objfile</var><span class="roman">]</span><span class="roman">]</span><span class="roman">]</span></code></dt> 144<dd><p>If given, <var>provider</var> is a regular expression used to match against 145provider names when selecting which probes to enable. If omitted, 146all probes from all providers are enabled. 147</p> 148<p>If given, <var>name</var> is a regular expression to match against probe 149names when selecting which probes to enable. If omitted, probe names 150are not considered when deciding whether to enable them. 151</p> 152<p>If given, <var>objfile</var> is a regular expression used to select which 153object files (executable or shared libraries) to examine. If not 154given, all object files are considered. 155</p> 156<a name="index-disable-probes"></a> 157</dd> 158<dt><code>disable probes <span class="roman">[</span><var>provider</var> <span class="roman">[</span><var>name</var> <span class="roman">[</span><var>objfile</var><span class="roman">]</span><span class="roman">]</span><span class="roman">]</span></code></dt> 159<dd><p>See the <code>enable probes</code> command above for a description of the 160optional arguments accepted by this command. 161</p></dd> 162</dl> 163 164<a name="index-_0024_005fprobe_005farg_002c-convenience-variable"></a> 165<p>A probe may specify up to twelve arguments. These are available at the 166point at which the probe is defined—that is, when the current PC is 167at the probe’s location. The arguments are available using the 168convenience variables (see <a href="Convenience-Vars.html#Convenience-Vars">Convenience Vars</a>) 169<code>$_probe_arg0</code>…<code>$_probe_arg11</code>. In <code>SystemTap</code> 170probes each probe argument is an integer of the appropriate size; 171types are not preserved. In <code>DTrace</code> probes types are preserved 172provided that they are recognized as such by <small>GDB</small>; otherwise 173the value of the probe argument will be a long integer. The 174convenience variable <code>$_probe_argc</code> holds the number of arguments 175at the current probe point. 176</p> 177<p>These variables are always available, but attempts to access them at 178any location other than a probe point will cause <small>GDB</small> to give 179an error message. 180</p> 181 182<div class="footnote"> 183<hr> 184<h4 class="footnotes-heading">Footnotes</h4> 185 186<h3><a name="FOOT5" href="#DOCF5">(5)</a></h3> 187<p>See 188<a href="http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps">http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps</a> 189for more information on how to add <code>SystemTap</code> <acronym>SDT</acronym> 190probes in your applications.</p> 191<h3><a name="FOOT6" href="#DOCF6">(6)</a></h3> 192<p>See 193<a href="http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation">http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation</a> 194for a good reference on how the <acronym>SDT</acronym> probes are implemented.</p> 195</div> 196<hr> 197<div class="header"> 198<p> 199Next: <a href="Error-in-Breakpoints.html#Error-in-Breakpoints" accesskey="n" rel="next">Error in Breakpoints</a>, Previous: <a href="Save-Breakpoints.html#Save-Breakpoints" accesskey="p" rel="previous">Save Breakpoints</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 200</div> 201 202 203 204</body> 205</html> 206