D.4 General Query Packets

Packets starting with q are general query packets; packets starting with Q are general set packets. General query and set packets are a semi-unified form for retrieving and sending information to and from the stub.

The initial letter of a query or set packet is followed by a name indicating what sort of thing the packet applies to. For example, gdb may use a qSymbol packet to exchange symbol definitions with the stub. These packet names follow some conventions:

The name of a query or set packet should be separated from any parameters by a :; the parameters themselves should be separated by , or ;. Stubs must be careful to match the full packet name, and check for a separator or the end of the packet, in case two packet names share a common prefix. New packets should not begin with qC, qP, or qL1.

Like the descriptions of the other packets, each description here has a template showing the packet's overall syntax, followed by an explanation of the packet's meaning. We include spaces in some of the templates for clarity; these are not part of the packet's syntax. No gdb packet uses spaces to separate its components.

Here are the currently defined query and set packets:

QAllow:op:val...
Specify which operations gdb expects to request of the target, as a semicolon-separated list of operation name and value pairs. Possible values for op include WriteReg, WriteMem, InsertBreak, InsertTrace, InsertFastTrace, and Stop. val is either 0, indicating that gdb will not request the operation, or 1, indicating that it may. (The target can then use this to set up its own internals optimally, for instance if the debugger never expects to insert breakpoints, it may not need to install its own trap handler.)
qC
Return the current thread ID.

Reply:

QC thread-id
Where thread-id is a thread ID as documented in thread-id syntax.
(anything else)
Any other reply implies the old thread ID.

qCRC:addr,length
Compute the CRC checksum of a block of memory using CRC-32 defined in IEEE 802.3. The CRC is computed byte at a time, taking the most significant bit of each byte first. The initial pattern code 0xffffffff is used to ensure leading zeros affect the CRC.

Note: This is the same CRC used in validating separate debug files (see Debugging Information in Separate Files). However the algorithm is slightly different. When validating separate debug files, the CRC is computed taking the least significant bit of each byte first, and the final result is inverted to detect trailing zeros.

Reply:

E NN
An error (such as memory fault)
C crc32
The specified memory region's checksum is crc32.

qfThreadInfo
qsThreadInfo
Obtain a list of all active thread IDs from the target (OS). Since there may be too many active threads to fit into one reply packet, this query works iteratively: it may require more than one query/reply sequence to obtain the entire list of threads. The first query of the sequence will be the qfThreadInfo query; subsequent queries in the sequence will be the qsThreadInfo query.

NOTE: This packet replaces the qL query (see below).

Reply:

m thread-id
A single thread ID
m thread-id,thread-id...
a comma-separated list of thread IDs
l
(lower case letter L) denotes end of list.

In response to each query, the target will reply with a list of one or more thread IDs, separated by commas. gdb will respond to each reply with a request for more thread ids (using the qs form of the query), until the target responds with l (lower-case ell, for last). Refer to thread-id syntax, for the format of the thread-id fields.

qGetTLSAddr:thread-id,offset,lm
Fetch the address associated with thread local storage specified by thread-id, offset, and lm.

thread-id is the thread ID associated with the thread for which to fetch the TLS address. See thread-id syntax.

offset is the (big endian, hex encoded) offset associated with the thread local variable. (This offset is obtained from the debug information associated with the variable.)

lm is the (big endian, hex encoded) OS/ABI-specific encoding of the the load module associated with the thread local storage. For example, a gnu/Linux system will pass the link map address of the shared object associated with the thread local storage under consideration. Other operating environments may choose to represent the load module differently, so the precise meaning of this parameter will vary.

Reply:

XX...
Hex encoded (big endian) bytes representing the address of the thread local storage requested.
E nn
An error occurred. nn are hex digits.
An empty reply indicates that qGetTLSAddr is not supported by the stub.

qGetTIBAddr:thread-id
Fetch address of the Windows OS specific Thread Information Block.

thread-id is the thread ID associated with the thread.

Reply:

XX...
Hex encoded (big endian) bytes representing the linear address of the thread information block.
E nn
An error occured. This means that either the thread was not found, or the address could not be retrieved.
An empty reply indicates that qGetTIBAddr is not supported by the stub.

qL startflag threadcount nextthread
Obtain thread information from RTOS. Where: startflag (one hex digit) is one to indicate the first query and zero to indicate a subsequent query; threadcount (two hex digits) is the maximum number of threads the response packet can contain; and nextthread (eight hex digits), for subsequent queries (startflag is zero), is returned in the response as argthread.

Don't use this packet; use the qfThreadInfo query instead (see above).

Reply:

qM count done argthread thread...
Where: count (two hex digits) is the number of threads being returned; done (one hex digit) is zero to indicate more threads and one indicates no further threads; argthreadid (eight hex digits) is nextthread from the request packet; thread... is a sequence of thread IDs from the target. threadid (eight hex digits). See remote.c:parse_threadlist_response().

qOffsets
Get section offsets that the target used when relocating the downloaded image.

Reply:

Text=xxx;Data=yyy[;Bss=zzz]
Relocate the Text section by xxx from its original address. Relocate the Data section by yyy from its original address. If the object file format provides segment information (e.g. elf PT_LOAD program headers), gdb will relocate entire segments by the supplied offsets.

Note: while a Bss offset may be included in the response, gdb ignores this and instead applies the Data offset to the Bss section.

TextSeg=xxx[;DataSeg=yyy]
Relocate the first segment of the object file, which conventionally contains program code, to a starting address of xxx. If DataSeg is specified, relocate the second segment, which conventionally contains modifiable data, to a starting address of yyy. gdb will report an error if the object file does not contain segment information, or does not contain at least as many segments as mentioned in the reply. Extra segments are kept at fixed offsets relative to the last relocated segment.

qP mode thread-id
Returns information on thread-id. Where: mode is a hex encoded 32 bit mode; thread-id is a thread ID (see thread-id syntax).

Don't use this packet; use the qThreadExtraInfo query instead (see below).

Reply: see remote.c:remote_unpack_thread_info_response().

QNonStop:1
QNonStop:0
Enter non-stop (QNonStop:1) or all-stop (QNonStop:0) mode. See Remote Non-Stop, for more information.

Reply:

OK
The request succeeded.
E nn
An error occurred. nn are hex digits.
An empty reply indicates that QNonStop is not supported by the stub.

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported). Use of this packet is controlled by the set non-stop command; see Non-Stop Mode.

QPassSignals: signal [;signal]...
Each listed signal should be passed directly to the inferior process. Signals are numbered identically to continue packets and stop replies (see Stop Reply Packets). Each signal list item should be strictly greater than the previous item. These signals do not need to stop the inferior, or be reported to gdb. All other signals should be reported to gdb. Multiple QPassSignals packets do not combine; any earlier QPassSignals list is completely replaced by the new list. This packet improves performance when using handle signal nostop noprint pass.

Reply:

OK
The request succeeded.
E nn
An error occurred. nn are hex digits.
An empty reply indicates that QPassSignals is not supported by the stub.

Use of this packet is controlled by the set remote pass-signals command (see set remote pass-signals). This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qRcmd,command
command (hex encoded) is passed to the local interpreter for execution. Invalid commands should be reported using the output string. Before the final result packet, the target may also respond with a number of intermediate Ooutput console output packets. Implementors should note that providing access to a stubs's interpreter may have security implications.

Reply:

OK
A command response with no output.
OUTPUT
A command response with the hex encoded output string OUTPUT.
E NN
Indicate a badly formed request.
An empty reply indicates that qRcmd is not recognized.

(Note that the qRcmd packet's name is separated from the command by a ,, not a :, contrary to the naming conventions above. Please don't use this packet as a model for new packets.)

qSearch:memory:address;length;search-pattern
Search length bytes at address for search-pattern. address and length are encoded in hex. search-pattern is a sequence of bytes, hex encoded.

Reply:

0
The pattern was not found.
1,address
The pattern was found at address.
E NN
A badly formed request or an error was encountered while searching memory.
An empty reply indicates that qSearch:memory is not recognized.

QStartNoAckMode
Request that the remote stub disable the normal +/- protocol acknowledgments (see Packet Acknowledgment).

Reply:

OK
The stub has switched to no-acknowledgment mode. gdb acknowledges this reponse, but neither the stub nor gdb shall send or expect further +/- acknowledgments in the current connection.
An empty reply indicates that the stub does not support no-acknowledgment mode.

qSupported [:gdbfeature [;gdbfeature]... ]
Tell the remote stub about features supported by gdb, and query the stub for features it supports. This packet allows gdb and the remote stub to take advantage of each others' features. qSupported also consolidates multiple feature probes at startup, to improve gdb performance—a single larger packet performs better than multiple smaller probe packets on high-latency links. Some features may enable behavior which must not be on by default, e.g. because it would confuse older clients or stubs. Other features may describe packets which could be automatically probed for, but are not. These features must be reported before gdb will use them. This “default unsupported” behavior is not appropriate for all packets, but it helps to keep the initial connection time under control with new versions of gdb which support increasing numbers of packets.

Reply:

stubfeature [;stubfeature]...
The stub supports or does not support each returned stubfeature, depending on the form of each stubfeature (see below for the possible forms).
An empty reply indicates that qSupported is not recognized, or that no features needed to be reported to gdb.

The allowed forms for each feature (either a gdbfeature in the qSupported packet, or a stubfeature in the response) are:

name=value
The remote protocol feature name is supported, and associated with the specified value. The format of value depends on the feature, but it must not include a semicolon.
name+
The remote protocol feature name is supported, and does not need an associated value.
name-
The remote protocol feature name is not supported.
name?
The remote protocol feature name may be supported, and gdb should auto-detect support in some other way when it is needed. This form will not be used for gdbfeature notifications, but may be used for stubfeature responses.

Whenever the stub receives a qSupported request, the supplied set of gdb features should override any previous request. This allows gdb to put the stub in a known state, even if the stub had previously been communicating with a different version of gdb.

The following values of gdbfeature (for the packet sent by gdb) are defined:

multiprocess
This feature indicates whether gdb supports multiprocess extensions to the remote protocol. gdb does not use such extensions unless the stub also reports that it supports them by including multiprocess+ in its qSupported reply. See multiprocess extensions, for details.
xmlRegisters
This feature indicates that gdb supports the XML target description. If the stub sees xmlRegisters= with target specific strings separated by a comma, it will report register description.
qRelocInsn
This feature indicates whether gdb supports the qRelocInsn packet (see Relocate instruction reply packet).

Stubs should ignore any unknown values for gdbfeature. Any gdb which sends a qSupported packet supports receiving packets of unlimited length (earlier versions of gdb may reject overly long responses). Additional values for gdbfeature may be defined in the future to let the stub take advantage of new features in gdb, e.g. incompatible improvements in the remote protocol—the multiprocess feature is an example of such a feature. The stub's reply should be independent of the gdbfeature entries sent by gdb; first gdb describes all the features it supports, and then the stub replies with all the features it supports.

Similarly, gdb will silently ignore unrecognized stub feature responses, as long as each response uses one of the standard forms.

Some features are flags. A stub which supports a flag feature should respond with a + form response. Other features require values, and the stub should respond with an = form response.

Each feature has a default value, which gdb will use if qSupported is not available or if the feature is not mentioned in the qSupported response. The default values are fixed; a stub is free to omit any feature responses that match the defaults.

Not all features can be probed, but for those which can, the probing mechanism is useful: in some cases, a stub's internal architecture may not allow the protocol layer to know some information about the underlying target in advance. This is especially common in stubs which may be configured for multiple targets.

These are the currently defined stub features and their properties:

Feature Name Value Required Default Probe Allowed


PacketSize Yes - No


qXfer:auxv:read No - Yes


qXfer:features:read No - Yes


qXfer:libraries:read No - Yes


qXfer:memory-map:read No - Yes


qXfer:sdata:read No - Yes


qXfer:spu:read No - Yes


qXfer:spu:write No - Yes


qXfer:siginfo:read No - Yes


qXfer:siginfo:write No - Yes


qXfer:threads:read No - Yes


QNonStop No - Yes


QPassSignals No - Yes


QStartNoAckMode No - Yes


multiprocess No - No


ConditionalTracepoints No - No


ReverseContinue No - No


ReverseStep No - No


TracepointSource No - No


QAllow No - No

These are the currently defined stub features, in more detail:

PacketSize=bytes
The remote stub can accept packets up to at least bytes in length. gdb will send packets up to this size for bulk transfers, and will never send larger packets. This is a limit on the data characters in the packet, including the frame and checksum. There is no trailing NUL byte in a remote protocol packet; if the stub stores packets in a NUL-terminated format, it should allow an extra byte in its buffer for the NUL. If this stub feature is not supported, gdb guesses based on the size of the g packet response.
qXfer:auxv:read
The remote stub understands the qXfer:auxv:read packet (see qXfer auxiliary vector read).
qXfer:features:read
The remote stub understands the qXfer:features:read packet (see qXfer target description read).
qXfer:libraries:read
The remote stub understands the qXfer:libraries:read packet (see qXfer library list read).
qXfer:memory-map:read
The remote stub understands the qXfer:memory-map:read packet (see qXfer memory map read).
qXfer:sdata:read
The remote stub understands the qXfer:sdata:read packet (see qXfer sdata read).
qXfer:spu:read
The remote stub understands the qXfer:spu:read packet (see qXfer spu read).
qXfer:spu:write
The remote stub understands the qXfer:spu:write packet (see qXfer spu write).
qXfer:siginfo:read
The remote stub understands the qXfer:siginfo:read packet (see qXfer siginfo read).
qXfer:siginfo:write
The remote stub understands the qXfer:siginfo:write packet (see qXfer siginfo write).
qXfer:threads:read
The remote stub understands the qXfer:threads:read packet (see qXfer threads read).
QNonStop
The remote stub understands the QNonStop packet (see QNonStop).
QPassSignals
The remote stub understands the QPassSignals packet (see QPassSignals).
QStartNoAckMode
The remote stub understands the QStartNoAckMode packet and prefers to operate in no-acknowledgment mode. See Packet Acknowledgment.
multiprocess
The remote stub understands the multiprocess extensions to the remote protocol syntax. The multiprocess extensions affect the syntax of thread IDs in both packets and replies (see thread-id syntax), and add process IDs to the D packet and W and X replies. Note that reporting this feature indicates support for the syntactic extensions only, not that the stub necessarily supports debugging of more than one process at a time. The stub must not use multiprocess extensions in packet replies unless gdb has also indicated it supports them in its qSupported request.
qXfer:osdata:read
The remote stub understands the qXfer:osdata:read packet ((see qXfer osdata read).
ConditionalTracepoints
The remote stub accepts and implements conditional expressions defined for tracepoints (see Tracepoint Conditions).
ReverseContinue
The remote stub accepts and implements the reverse continue packet (see bc).
ReverseStep
The remote stub accepts and implements the reverse step packet (see bs).
TracepointSource
The remote stub understands the QTDPsrc packet that supplies the source form of tracepoint definitions.
QAllow
The remote stub understands the QAllow packet.
StaticTracepoint
The remote stub supports static tracepoints.

qSymbol::
Notify the target that gdb is prepared to serve symbol lookup requests. Accept requests from the target for the values of symbols.

Reply:

OK
The target does not need to look up any (more) symbols.
qSymbol:sym_name
The target requests the value of symbol sym_name (hex encoded). gdb may provide the value by using the qSymbol:sym_value:sym_name message, described below.

qSymbol:sym_value:sym_name
Set the value of sym_name to sym_value.

sym_name (hex encoded) is the name of a symbol whose value the target has previously requested.

sym_value (hex) is the value for symbol sym_name. If gdb cannot supply a value for sym_name, then this field will be empty.

Reply:

OK
The target does not need to look up any (more) symbols.
qSymbol:sym_name
The target requests the value of a new symbol sym_name (hex encoded). gdb will continue to supply the values of symbols (if available), until the target ceases to request them.

qTBuffer
QTBuffer
QTDisconnected
QTDP
QTDPsrc
QTDV
qTfP
qTfV
QTFrame
See Tracepoint Packets.
qThreadExtraInfo,thread-id
Obtain a printable string description of a thread's attributes from the target OS. thread-id is a thread ID; see thread-id syntax. This string may contain anything that the target OS thinks is interesting for gdb to tell the user about the thread. The string is displayed in gdb's info threads display. Some examples of possible thread extra info strings are Runnable, or Blocked on Mutex.

Reply:

XX...
Where XX... is a hex encoding of ascii data, comprising the printable string containing the extra information about the thread's attributes.

(Note that the qThreadExtraInfo packet's name is separated from the command by a ,, not a :, contrary to the naming conventions above. Please don't use this packet as a model for new packets.)

QTSave
qTsP
qTsV
QTStart
QTStop
QTinit
QTro
qTStatus
qTV
qTfSTM
qTsSTM
qTSTMat
See Tracepoint Packets.
qXfer:object:read:annex:offset,length
Read uninterpreted bytes from the target's special data area identified by the keyword object. Request length bytes starting at offset bytes into the data. The content and encoding of annex is specific to object; it can supply additional details about what data to access.

Here are the specific requests of this form defined so far. All qXfer:object:read:... requests use the same reply formats, listed below.

qXfer:auxv:read::offset,length
Access the target's auxiliary vector. See auxiliary vector. Note annex must be empty.

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qXfer:features:read:annex:offset,length
Access the target description. See Target Descriptions. The annex specifies which XML document to access. The main description is always loaded from the target.xml annex.

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qXfer:libraries:read:annex:offset,length
Access the target's list of loaded libraries. See Library List Format. The annex part of the generic qXfer packet must be empty (see qXfer read).

Targets which maintain a list of libraries in the program's memory do not need to implement this packet; it is designed for platforms where the operating system manages the list of loaded libraries.

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qXfer:memory-map:read::offset,length
Access the target's memory-map. See Memory Map Format. The annex part of the generic qXfer packet must be empty (see qXfer read).

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qXfer:sdata:read::offset,length

Read contents of the extra collected static tracepoint marker information. The annex part of the generic qXfer packet must be empty (see qXfer read). See Tracepoint Action Lists.

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qXfer:siginfo:read::offset,length
Read contents of the extra signal information on the target system. The annex part of the generic qXfer packet must be empty (see qXfer read).

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qXfer:spu:read:annex:offset,length
Read contents of an spufs file on the target system. The annex specifies which file to read; it must be of the form id/name, where id specifies an SPU context ID in the target process, and name identifes the spufs file in that context to be accessed.

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qXfer:threads:read::offset,length
Access the list of threads on target. See Thread List Format. The annex part of the generic qXfer packet must be empty (see qXfer read).

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qXfer:osdata:read::offset,length
Access the target's operating system information. See Operating System Information.

Reply:

m data
Data data (see Binary Data) has been read from the target. There may be more data at a higher address (although it is permitted to return m even for the last valid block of data, as long as at least one byte of data was read). data may have fewer bytes than the length in the request.
l data
Data data (see Binary Data) has been read from the target. There is no more data to be read. data may have fewer bytes than the length in the request.
l
The offset in the request is at the end of the data. There is no more data to be read.
E00
The request was malformed, or annex was invalid.
E nn
The offset was invalid, or there was an error encountered reading the data. nn is a hex-encoded errno value.
An empty reply indicates the object string was not recognized by the stub, or that the object does not support reading.

qXfer:object:write:annex:offset:data...
Write uninterpreted bytes into the target's special data area identified by the keyword object, starting at offset bytes into the data. data... is the binary-encoded data (see Binary Data) to be written. The content and encoding of annex is specific to object; it can supply additional details about what data to access.

Here are the specific requests of this form defined so far. All qXfer:object:write:... requests use the same reply formats, listed below.

qXfer:siginfo:write::offset:data...
Write data to the extra signal information on the target system. The annex part of the generic qXfer packet must be empty (see qXfer write).

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

qXfer:spu:write:annex:offset:data...
Write data to an spufs file on the target system. The annex specifies which file to write; it must be of the form id/name, where id specifies an SPU context ID in the target process, and name identifes the spufs file in that context to be accessed.

This packet is not probed by default; the remote stub must request it, by supplying an appropriate qSupported response (see qSupported).

Reply:

nn
nn (hex encoded) is the number of bytes written. This may be fewer bytes than supplied in the request.
E00
The request was malformed, or annex was invalid.
E nn
The offset was invalid, or there was an error encountered writing the data. nn is a hex-encoded errno value.
An empty reply indicates the object string was not recognized by the stub, or that the object does not support writing.

qXfer:object:operation:...
Requests of this form may be added in the future. When a stub does not recognize the object keyword, or its support for object does not recognize the operation keyword, the stub must respond with an empty packet.
qAttached:pid
Return an indication of whether the remote server attached to an existing process or created a new process. When the multiprocess protocol extensions are supported (see multiprocess extensions), pid is an integer in hexadecimal format identifying the target process. Otherwise, gdb will omit the pid field and the query packet will be simplified as qAttached.

This query is used, for example, to know whether the remote process should be detached or killed when a gdb session is ended with the quit command.

Reply:

1
The remote server attached to an existing process.
0
The remote server created a new process.
E NN
A badly formed request or an error was encountered.

Footnotes

[1] The qP and qL packets predate these conventions, and have arguments without any terminator for the packet name; we suspect they are in widespread use in places that are difficult to upgrade. The qC packet has no arguments, but some existing stubs (e.g. RedBoot) are known to not check for the end of the packet.