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: Stop Reply Packets</title> 18 19<meta name="description" content="Debugging with GDB: Stop Reply Packets"> 20<meta name="keywords" content="Debugging with GDB: Stop Reply Packets"> 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="Remote-Protocol.html#Remote-Protocol" rel="up" title="Remote Protocol"> 29<link href="General-Query-Packets.html#General-Query-Packets" rel="next" title="General Query Packets"> 30<link href="Packets.html#Packets" rel="previous" title="Packets"> 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="Stop-Reply-Packets"></a> 65<div class="header"> 66<p> 67Next: <a href="General-Query-Packets.html#General-Query-Packets" accesskey="n" rel="next">General Query Packets</a>, Previous: <a href="Packets.html#Packets" accesskey="p" rel="previous">Packets</a>, Up: <a href="Remote-Protocol.html#Remote-Protocol" accesskey="u" rel="up">Remote Protocol</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="Stop-Reply-Packets-1"></a> 71<h3 class="section">E.3 Stop Reply Packets</h3> 72<a name="index-stop-reply-packets"></a> 73 74<p>The ‘<samp>C</samp>’, ‘<samp>c</samp>’, ‘<samp>S</samp>’, ‘<samp>s</samp>’, ‘<samp>vCont</samp>’, 75‘<samp>vAttach</samp>’, ‘<samp>vRun</samp>’, ‘<samp>vStopped</samp>’, and ‘<samp>?</samp>’ packets can 76receive any of the below as a reply. Except for ‘<samp>?</samp>’ 77and ‘<samp>vStopped</samp>’, that reply is only returned 78when the target halts. In the below the exact meaning of <em>signal 79number</em> is defined by the header <samp>include/gdb/signals.h</samp> in the 80<small>GDB</small> source code. 81</p> 82<p>In non-stop mode, the server will simply reply ‘<samp>OK</samp>’ to commands 83such as ‘<samp>vCont</samp>’; any stop will be the subject of a future 84notification. See <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>. 85</p> 86<p>As in the description of request packets, we include spaces in the 87reply templates for clarity; these are not part of the reply packet’s 88syntax. No <small>GDB</small> stop reply packet uses spaces to separate its 89components. 90</p> 91<dl compact="compact"> 92<dt>‘<samp>S <var>AA</var></samp>’</dt> 93<dd><p>The program received signal number <var>AA</var> (a two-digit hexadecimal 94number). This is equivalent to a ‘<samp>T</samp>’ response with no 95<var>n</var>:<var>r</var> pairs. 96</p> 97</dd> 98<dt>‘<samp>T <var>AA</var> <var>n1</var>:<var>r1</var>;<var>n2</var>:<var>r2</var>;…</samp>’</dt> 99<dd><a name="index-T-packet-reply"></a> 100<p>The program received signal number <var>AA</var> (a two-digit hexadecimal 101number). This is equivalent to an ‘<samp>S</samp>’ response, except that the 102‘<samp><var>n</var>:<var>r</var></samp>’ pairs can carry values of important registers 103and other information directly in the stop reply packet, reducing 104round-trip latency. Single-step and breakpoint traps are reported 105this way. Each ‘<samp><var>n</var>:<var>r</var></samp>’ pair is interpreted as follows: 106</p> 107<ul> 108<li> If <var>n</var> is a hexadecimal number, it is a register number, and the 109corresponding <var>r</var> gives that register’s value. The data <var>r</var> is a 110series of bytes in target byte order, with each byte given by a 111two-digit hex number. 112 113</li><li> If <var>n</var> is ‘<samp>thread</samp>’, then <var>r</var> is the <var>thread-id</var> of 114the stopped thread, as specified in <a href="Packets.html#thread_002did-syntax">thread-id syntax</a>. 115 116</li><li> If <var>n</var> is ‘<samp>core</samp>’, then <var>r</var> is the hexadecimal number of 117the core on which the stop event was detected. 118 119</li><li> If <var>n</var> is a recognized <em>stop reason</em>, it describes a more 120specific event that stopped the target. The currently defined stop 121reasons are listed below. The <var>aa</var> should be ‘<samp>05</samp>’, the trap 122signal. At most one stop reason should be present. 123 124</li><li> Otherwise, <small>GDB</small> should ignore this ‘<samp><var>n</var>:<var>r</var></samp>’ pair 125and go on to the next; this allows us to extend the protocol in the 126future. 127</li></ul> 128 129<p>The currently defined stop reasons are: 130</p> 131<dl compact="compact"> 132<dt>‘<samp>watch</samp>’</dt> 133<dt>‘<samp>rwatch</samp>’</dt> 134<dt>‘<samp>awatch</samp>’</dt> 135<dd><p>The packet indicates a watchpoint hit, and <var>r</var> is the data address, in 136hex. 137</p> 138</dd> 139<dt>‘<samp>syscall_entry</samp>’</dt> 140<dt>‘<samp>syscall_return</samp>’</dt> 141<dd><p>The packet indicates a syscall entry or return, and <var>r</var> is the 142syscall number, in hex. 143</p> 144<a name="index-shared-library-events_002c-remote-reply"></a> 145</dd> 146<dt>‘<samp>library</samp>’</dt> 147<dd><p>The packet indicates that the loaded libraries have changed. 148<small>GDB</small> should use ‘<samp>qXfer:libraries:read</samp>’ to fetch a new 149list of loaded libraries. The <var>r</var> part is ignored. 150</p> 151<a name="index-replay-log-events_002c-remote-reply"></a> 152</dd> 153<dt>‘<samp>replaylog</samp>’</dt> 154<dd><p>The packet indicates that the target cannot continue replaying 155logged execution events, because it has reached the end (or the 156beginning when executing backward) of the log. The value of <var>r</var> 157will be either ‘<samp>begin</samp>’ or ‘<samp>end</samp>’. See <a href="Reverse-Execution.html#Reverse-Execution">Reverse Execution</a>, 158for more information. 159</p> 160</dd> 161<dt>‘<samp>swbreak</samp>’</dt> 162<dd><a name="swbreak-stop-reason"></a><p>The packet indicates a software breakpoint instruction was executed, 163irrespective of whether it was <small>GDB</small> that planted the 164breakpoint or the breakpoint is hardcoded in the program. The <var>r</var> 165part must be left empty. 166</p> 167<p>On some architectures, such as x86, at the architecture level, when a 168breakpoint instruction executes the program counter points at the 169breakpoint address plus an offset. On such targets, the stub is 170responsible for adjusting the PC to point back at the breakpoint 171address. 172</p> 173<p>This packet should not be sent by default; older <small>GDB</small> versions 174did not support it. <small>GDB</small> requests it, by supplying an 175appropriate ‘<samp>qSupported</samp>’ feature (see <a href="General-Query-Packets.html#qSupported">qSupported</a>). The 176remote stub must also supply the appropriate ‘<samp>qSupported</samp>’ feature 177indicating support. 178</p> 179<p>This packet is required for correct non-stop mode operation. 180</p> 181</dd> 182<dt>‘<samp>hwbreak</samp>’</dt> 183<dd><p>The packet indicates the target stopped for a hardware breakpoint. 184The <var>r</var> part must be left empty. 185</p> 186<p>The same remarks about ‘<samp>qSupported</samp>’ and non-stop mode above 187apply. 188</p> 189<a name="index-fork-events_002c-remote-reply"></a> 190</dd> 191<dt>‘<samp>fork</samp>’</dt> 192<dd><p>The packet indicates that <code>fork</code> was called, and <var>r</var> 193is the thread ID of the new child process. Refer to 194<a href="Packets.html#thread_002did-syntax">thread-id syntax</a> for the format of the <var>thread-id</var> 195field. This packet is only applicable to targets that support 196fork events. 197</p> 198<p>This packet should not be sent by default; older <small>GDB</small> versions 199did not support it. <small>GDB</small> requests it, by supplying an 200appropriate ‘<samp>qSupported</samp>’ feature (see <a href="General-Query-Packets.html#qSupported">qSupported</a>). The 201remote stub must also supply the appropriate ‘<samp>qSupported</samp>’ feature 202indicating support. 203</p> 204<a name="index-vfork-events_002c-remote-reply"></a> 205</dd> 206<dt>‘<samp>vfork</samp>’</dt> 207<dd><p>The packet indicates that <code>vfork</code> was called, and <var>r</var> 208is the thread ID of the new child process. Refer to 209<a href="Packets.html#thread_002did-syntax">thread-id syntax</a> for the format of the <var>thread-id</var> 210field. This packet is only applicable to targets that support 211vfork events. 212</p> 213<p>This packet should not be sent by default; older <small>GDB</small> versions 214did not support it. <small>GDB</small> requests it, by supplying an 215appropriate ‘<samp>qSupported</samp>’ feature (see <a href="General-Query-Packets.html#qSupported">qSupported</a>). The 216remote stub must also supply the appropriate ‘<samp>qSupported</samp>’ feature 217indicating support. 218</p> 219<a name="index-vforkdone-events_002c-remote-reply"></a> 220</dd> 221<dt>‘<samp>vforkdone</samp>’</dt> 222<dd><p>The packet indicates that a child process created by a vfork 223has either called <code>exec</code> or terminated, so that the 224address spaces of the parent and child process are no longer 225shared. The <var>r</var> part is ignored. This packet is only 226applicable to targets that support vforkdone events. 227</p> 228<p>This packet should not be sent by default; older <small>GDB</small> versions 229did not support it. <small>GDB</small> requests it, by supplying an 230appropriate ‘<samp>qSupported</samp>’ feature (see <a href="General-Query-Packets.html#qSupported">qSupported</a>). The 231remote stub must also supply the appropriate ‘<samp>qSupported</samp>’ feature 232indicating support. 233</p> 234<a name="index-exec-events_002c-remote-reply"></a> 235</dd> 236<dt>‘<samp>exec</samp>’</dt> 237<dd><p>The packet indicates that <code>execve</code> was called, and <var>r</var> 238is the absolute pathname of the file that was executed, in hex. 239This packet is only applicable to targets that support exec events. 240</p> 241<p>This packet should not be sent by default; older <small>GDB</small> versions 242did not support it. <small>GDB</small> requests it, by supplying an 243appropriate ‘<samp>qSupported</samp>’ feature (see <a href="General-Query-Packets.html#qSupported">qSupported</a>). The 244remote stub must also supply the appropriate ‘<samp>qSupported</samp>’ feature 245indicating support. 246</p> 247<a name="index-thread-create-event_002c-remote-reply"></a> 248<a name="thread-create-event"></a></dd> 249<dt>‘<samp>create</samp>’</dt> 250<dd><p>The packet indicates that the thread was just created. The new thread 251is stopped until <small>GDB</small> sets it running with a resumption packet 252(see <a href="Packets.html#vCont-packet">vCont packet</a>). This packet should not be sent by default; 253<small>GDB</small> requests it with the <a href="General-Query-Packets.html#QThreadEvents">QThreadEvents</a> packet. See 254also the ‘<samp>w</samp>’ (see <a href="#thread-exit-event">thread exit event</a>) remote reply below. The 255<var>r</var> part is ignored. 256</p> 257</dd> 258</dl> 259 260</dd> 261<dt>‘<samp>W <var>AA</var></samp>’</dt> 262<dt>‘<samp>W <var>AA</var> ; process:<var>pid</var></samp>’</dt> 263<dd><p>The process exited, and <var>AA</var> is the exit status. This is only 264applicable to certain targets. 265</p> 266<p>The second form of the response, including the process ID of the 267exited process, can be used only when <small>GDB</small> has reported 268support for multiprocess protocol extensions; see <a href="General-Query-Packets.html#multiprocess-extensions">multiprocess extensions</a>. Both <var>AA</var> and <var>pid</var> are formatted as big-endian 269hex strings. 270</p> 271</dd> 272<dt>‘<samp>X <var>AA</var></samp>’</dt> 273<dt>‘<samp>X <var>AA</var> ; process:<var>pid</var></samp>’</dt> 274<dd><p>The process terminated with signal <var>AA</var>. 275</p> 276<p>The second form of the response, including the process ID of the 277terminated process, can be used only when <small>GDB</small> has reported 278support for multiprocess protocol extensions; see <a href="General-Query-Packets.html#multiprocess-extensions">multiprocess extensions</a>. Both <var>AA</var> and <var>pid</var> are formatted as big-endian 279hex strings. 280</p> 281<a name="thread-exit-event"></a><a name="index-thread-exit-event_002c-remote-reply"></a> 282</dd> 283<dt>‘<samp>w <var>AA</var> ; <var>tid</var></samp>’</dt> 284<dd> 285<p>The thread exited, and <var>AA</var> is the exit status. This response 286should not be sent by default; <small>GDB</small> requests it with the 287<a href="General-Query-Packets.html#QThreadEvents">QThreadEvents</a> packet. See also <a href="#thread-create-event">thread create event</a> above. 288<var>AA</var> is formatted as a big-endian hex string. 289</p> 290</dd> 291<dt>‘<samp>N</samp>’</dt> 292<dd><p>There are no resumed threads left in the target. In other words, even 293though the process is alive, the last resumed thread has exited. For 294example, say the target process has two threads: thread 1 and thread 2952. The client leaves thread 1 stopped, and resumes thread 2, which 296subsequently exits. At this point, even though the process is still 297alive, and thus no ‘<samp>W</samp>’ stop reply is sent, no thread is actually 298executing either. The ‘<samp>N</samp>’ stop reply thus informs the client 299that it can stop waiting for stop replies. This packet should not be 300sent by default; older <small>GDB</small> versions did not support it. 301<small>GDB</small> requests it, by supplying an appropriate 302‘<samp>qSupported</samp>’ feature (see <a href="General-Query-Packets.html#qSupported">qSupported</a>). The remote stub must 303also supply the appropriate ‘<samp>qSupported</samp>’ feature indicating 304support. 305</p> 306</dd> 307<dt>‘<samp>O <var>XX</var>…</samp>’</dt> 308<dd><p>‘<samp><var>XX</var>…</samp>’ is hex encoding of <small>ASCII</small> data, to be 309written as the program’s console output. This can happen at any time 310while the program is running and the debugger should continue to wait 311for ‘<samp>W</samp>’, ‘<samp>T</samp>’, etc. This reply is not permitted in non-stop mode. 312</p> 313</dd> 314<dt>‘<samp>F <var>call-id</var>,<var>parameter</var>…</samp>’</dt> 315<dd><p><var>call-id</var> is the identifier which says which host system call should 316be called. This is just the name of the function. Translation into the 317correct system call is only applicable as it’s defined in <small>GDB</small>. 318See <a href="File_002dI_002fO-Remote-Protocol-Extension.html#File_002dI_002fO-Remote-Protocol-Extension">File-I/O Remote Protocol Extension</a>, for a list of implemented 319system calls. 320</p> 321<p>‘<samp><var>parameter</var>…</samp>’ is a list of parameters as defined for 322this very system call. 323</p> 324<p>The target replies with this packet when it expects <small>GDB</small> to 325call a host system call on behalf of the target. <small>GDB</small> replies 326with an appropriate ‘<samp>F</samp>’ packet and keeps up waiting for the next 327reply packet from the target. The latest ‘<samp>C</samp>’, ‘<samp>c</samp>’, ‘<samp>S</samp>’ 328or ‘<samp>s</samp>’ action is expected to be continued. See <a href="File_002dI_002fO-Remote-Protocol-Extension.html#File_002dI_002fO-Remote-Protocol-Extension">File-I/O Remote Protocol Extension</a>, for more details. 329</p> 330</dd> 331</dl> 332 333<hr> 334<div class="header"> 335<p> 336Next: <a href="General-Query-Packets.html#General-Query-Packets" accesskey="n" rel="next">General Query Packets</a>, Previous: <a href="Packets.html#Packets" accesskey="p" rel="previous">Packets</a>, Up: <a href="Remote-Protocol.html#Remote-Protocol" accesskey="u" rel="up">Remote Protocol</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> 337</div> 338 339 340 341</body> 342</html> 343