cli-command | mi-command
[ token ] cli-command nl, where cli-command is any existing gdb CLI command.
[ token ] "-" operation ( " " option )* [ " -" ] ( " " parameter )* nl
"any sequence of digits"
"-" parameter [ " " parameter ]
non-blank-sequence | c-string
any of the operations described in this chapter
anything, provided it doesn't contain special characters such as "-", nl, """ and of course " "
""" seven-bit-iso-c-string-content """
CR | CR-LF
Notes:
The CLI commands are still handled by the mi interpreter; their output is described below.
The token, when present, is passed back when the command finishes.
Some mi commands accept optional arguments as part of the parameter list. Each option is identified by a leading - (dash) and may be followed by an optional argument parameter. Options occur first in the parameter list and can be delimited from normal parameters using - (this is useful when some parameters begin with a dash).
Pragmatics:
We want easy access to the existing CLI syntax (for debugging).
We want it to be easy to spot a mi operation.
The output from gdb/mi consists of zero or more out-of-band records followed, optionally, by a single result record. This result record is for the most recent command. The sequence of output records is terminated by (gdb).
If an input command was prefixed with a token then the corresponding output for that command will also be prefixed by that same token.
( out-of-band-record )* [ result-record ] "(gdb)" nl
[ token ] "^" result-class ( "," result )* nl
async-record | stream-record
exec-async-output | status-async-output | notify-async-output
[ token ] "*" async-output
[ token ] "+" async-output
[ token ] "=" async-output
async-class ( "," result )* nl
"done" | "running" | "connected" | "error" | "exit"
"stopped" | others (where others will be added depending on the needs--this is still in development).
variable "=" value
string
const | tuple | list
c-string
"{}" | "{" result ( "," result )* "}"
"[]" | "[" value ( "," value )* "]" | "[" result ( "," result )* "]"
console-stream-output | target-stream-output | log-stream-output
"~" c-string
"@" c-string
"&" c-string
CR | CR-LF
any sequence of digits.
Notes:
All output sequences end in a single line containing a period.
The token is from the corresponding request. If an execution command is interrupted by the -exec-interrupt command, the token associated with the *stopped message is the one of the original execution command, not the one of the interrupt command.
status-async-output contains on-going status information about the progress of a slow operation. It can be discarded. All status output is prefixed by +.
exec-async-output contains asynchronous state change on the target (stopped, started, disappeared). All async output is prefixed by *.
notify-async-output contains supplementary information that the client should handle (e.g., a new breakpoint information). All notify output is prefixed by =.
console-stream-output is output that should be displayed as is in the console. It is the textual response to a CLI command. All the console output is prefixed by ~.
target-stream-output is the output produced by the target program. All the target output is prefixed by @.
log-stream-output is output text coming from gdb's internals, for instance messages that should be displayed as part of an error log. All the log output is prefixed by &.
New gdb/mi commands should only output lists containing values.
Refer to Section 26.6.2 gdb/mi Stream Records, for more details about the various output records.
This subsection presents several simple examples of interaction using the gdb/mi interface. In these examples, -> means that the following line is passed to gdb/mi as input, while <- means the output received from gdb/mi.
Here's an example of stopping the inferior process:
-> -stop <- (gdb) |
and later:
<- *stop,reason="stop",address="0x123",source="a.c:123" <- (gdb) |
Here's an example of a simple CLI command being passed through gdb/mi and on to the CLI.
-> print 1+2 <- &"print 1+2\n" <- ~"$1 = 3\n" <- ^done <- (gdb) |