OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [gdb/] [doc/] [gdb.info-10] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
2
 
3
INFO-DIR-SECTION Programming & development tools.
4
START-INFO-DIR-ENTRY
5
* Gdb: (gdb).                     The GNU debugger.
6
END-INFO-DIR-ENTRY
7
 
8
   This file documents the GNU debugger GDB.
9
 
10
   This is the Ninth Edition, April 2001, of `Debugging with GDB: the
11
GNU Source-Level Debugger' for GDB Version 20010707.
12
 
13
   Copyright (C)
14
1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
15
Free Software Foundation, Inc.
16
 
17
   Permission is granted to copy, distribute and/or modify this document
18
under the terms of the GNU Free Documentation License, Version 1.1 or
19
any later version published by the Free Software Foundation; with the
20
Invariant Sections being "A Sample GDB Session" and "Free Software",
21
with the Front-Cover texts being "A GNU Manual," and with the
22
Back-Cover Texts as in (a) below.
23
 
24
   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
25
modify this GNU Manual, like GNU software.  Copies published by the Free
26
Software Foundation raise funds for GNU development."
27
 
28

29
File: gdb.info,  Node: Define,  Next: Hooks,  Up: Sequences
30
 
31
User-defined commands
32
=====================
33
 
34
   A "user-defined command" is a sequence of GDB commands to which you
35
assign a new name as a command.  This is done with the `define'
36
command.  User commands may accept up to 10 arguments separated by
37
whitespace.  Arguments are accessed within the user command via
38
$ARG0...$ARG9.  A trivial example:
39
 
40
     define adder
41
       print $arg0 + $arg1 + $arg2
42
 
43
To execute the command use:
44
 
45
     adder 1 2 3
46
 
47
This defines the command `adder', which prints the sum of its three
48
arguments.  Note the arguments are text substitutions, so they may
49
reference variables, use complex expressions, or even perform inferior
50
functions calls.
51
 
52
`define COMMANDNAME'
53
     Define a command named COMMANDNAME.  If there is already a command
54
     by that name, you are asked to confirm that you want to redefine
55
     it.
56
 
57
     The definition of the command is made up of other GDB command
58
     lines, which are given following the `define' command.  The end of
59
     these commands is marked by a line containing `end'.
60
 
61
`if'
62
     Takes a single argument, which is an expression to evaluate.  It
63
     is followed by a series of commands that are executed only if the
64
     expression is true (nonzero).  There can then optionally be a line
65
     `else', followed by a series of commands that are only executed if
66
     the expression was false.  The end of the list is marked by a line
67
     containing `end'.
68
 
69
`while'
70
     The syntax is similar to `if': the command takes a single argument,
71
     which is an expression to evaluate, and must be followed by the
72
     commands to execute, one per line, terminated by an `end'.  The
73
     commands are executed repeatedly as long as the expression
74
     evaluates to true.
75
 
76
`document COMMANDNAME'
77
     Document the user-defined command COMMANDNAME, so that it can be
78
     accessed by `help'.  The command COMMANDNAME must already be
79
     defined.  This command reads lines of documentation just as
80
     `define' reads the lines of the command definition, ending with
81
     `end'.  After the `document' command is finished, `help' on command
82
     COMMANDNAME displays the documentation you have written.
83
 
84
     You may use the `document' command again to change the
85
     documentation of a command.  Redefining the command with `define'
86
     does not change the documentation.
87
 
88
`help user-defined'
89
     List all user-defined commands, with the first line of the
90
     documentation (if any) for each.
91
 
92
`show user'
93
`show user COMMANDNAME'
94
     Display the GDB commands used to define COMMANDNAME (but not its
95
     documentation).  If no COMMANDNAME is given, display the
96
     definitions for all user-defined commands.
97
 
98
   When user-defined commands are executed, the commands of the
99
definition are not printed.  An error in any command stops execution of
100
the user-defined command.
101
 
102
   If used interactively, commands that would ask for confirmation
103
proceed without asking when used inside a user-defined command.  Many
104
GDB commands that normally print messages to say what they are doing
105
omit the messages when used in a user-defined command.
106
 
107

108
File: gdb.info,  Node: Hooks,  Next: Command Files,  Prev: Define,  Up: Sequences
109
 
110
User-defined command hooks
111
==========================
112
 
113
   You may define "hooks", which are a special kind of user-defined
114
command.  Whenever you run the command `foo', if the user-defined
115
command `hook-foo' exists, it is executed (with no arguments) before
116
that command.
117
 
118
   A hook may also be defined which is run after the command you
119
executed.  Whenever you run the command `foo', if the user-defined
120
command `hookpost-foo' exists, it is executed (with no arguments) after
121
that command.  Post-execution hooks may exist simultaneously with
122
pre-execution hooks, for the same command.
123
 
124
   It is valid for a hook to call the command which it hooks.  If this
125
occurs, the hook is not re-executed, thereby avoiding infinte recursion.
126
 
127
   In addition, a pseudo-command, `stop' exists.  Defining
128
(`hook-stop') makes the associated commands execute every time
129
execution stops in your program: before breakpoint commands are run,
130
displays are printed, or the stack frame is printed.
131
 
132
   For example, to ignore `SIGALRM' signals while single-stepping, but
133
treat them normally during normal execution, you could define:
134
 
135
     define hook-stop
136
     handle SIGALRM nopass
137
     end
138
 
139
     define hook-run
140
     handle SIGALRM pass
141
     end
142
 
143
     define hook-continue
144
     handle SIGLARM pass
145
     end
146
 
147
   As a further example, to hook at the begining and end of the `echo'
148
command, and to add extra text to the beginning and end of the message,
149
you could define:
150
 
151
     define hook-echo
152
     echo <<<---
153
     end
154
 
155
     define hookpost-echo
156
     echo --->>>\n
157
     end
158
 
159
     (gdb) echo Hello World
160
     <<<---Hello World--->>>
161
     (gdb)
162
 
163
   You can define a hook for any single-word command in GDB, but not
164
for command aliases; you should define a hook for the basic command
165
name, e.g.  `backtrace' rather than `bt'.  If an error occurs during
166
the execution of your hook, execution of GDB commands stops and GDB
167
issues a prompt (before the command that you actually typed had a
168
chance to run).
169
 
170
   If you try to define a hook which does not match any known command,
171
you get a warning from the `define' command.
172
 
173

174
File: gdb.info,  Node: Command Files,  Next: Output,  Prev: Hooks,  Up: Sequences
175
 
176
Command files
177
=============
178
 
179
   A command file for GDB is a file of lines that are GDB commands.
180
Comments (lines starting with `#') may also be included.  An empty line
181
in a command file does nothing; it does not mean to repeat the last
182
command, as it would from the terminal.
183
 
184
   When you start GDB, it automatically executes commands from its
185
"init files".  These are files named `.gdbinit' on Unix and `gdb.ini'
186
on DOS/Windows.  During startup, GDB does the following:
187
 
188
  1. Reads the init file (if any) in your home directory(1).
189
 
190
  2. Processes command line options and operands.
191
 
192
  3. Reads the init file (if any) in the current working directory.
193
 
194
  4. Reads command files specified by the `-x' option.
195
 
196
   The init file in your home directory can set options (such as `set
197
complaints') that affect subsequent processing of command line options
198
and operands.  Init files are not executed if you use the `-nx' option
199
(*note Choosing modes: Mode Options.).
200
 
201
   On some configurations of GDB, the init file is known by a different
202
name (these are typically environments where a specialized form of GDB
203
may need to coexist with other forms, hence a different name for the
204
specialized version's init file).  These are the environments with
205
special init file names:
206
 
207
   * VxWorks (Wind River Systems real-time OS): `.vxgdbinit'
208
 
209
   * OS68K (Enea Data Systems real-time OS): `.os68gdbinit'
210
 
211
   * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit'
212
 
213
   You can also request the execution of a command file with the
214
`source' command:
215
 
216
`source FILENAME'
217
     Execute the command file FILENAME.
218
 
219
   The lines in a command file are executed sequentially.  They are not
220
printed as they are executed.  An error in any command terminates
221
execution of the command file.
222
 
223
   Commands that would ask for confirmation if used interactively
224
proceed without asking when used in a command file.  Many GDB commands
225
that normally print messages to say what they are doing omit the
226
messages when called from command files.
227
 
228
   ---------- Footnotes ----------
229
 
230
   (1) On DOS/Windows systems, the home directory is the one pointed to
231
by the `HOME' environment variable.
232
 
233

234
File: gdb.info,  Node: Output,  Prev: Command Files,  Up: Sequences
235
 
236
Commands for controlled output
237
==============================
238
 
239
   During the execution of a command file or a user-defined command,
240
normal GDB output is suppressed; the only output that appears is what is
241
explicitly printed by the commands in the definition.  This section
242
describes three commands useful for generating exactly the output you
243
want.
244
 
245
`echo TEXT'
246
     Print TEXT.  Nonprinting characters can be included in TEXT using
247
     C escape sequences, such as `\n' to print a newline.  *No newline
248
     is printed unless you specify one.* In addition to the standard C
249
     escape sequences, a backslash followed by a space stands for a
250
     space.  This is useful for displaying a string with spaces at the
251
     beginning or the end, since leading and trailing spaces are
252
     otherwise trimmed from all arguments.  To print ` and foo = ', use
253
     the command `echo \ and foo = \ '.
254
 
255
     A backslash at the end of TEXT can be used, as in C, to continue
256
     the command onto subsequent lines.  For example,
257
 
258
          echo This is some text\n\
259
          which is continued\n\
260
          onto several lines.\n
261
 
262
     produces the same output as
263
 
264
          echo This is some text\n
265
          echo which is continued\n
266
          echo onto several lines.\n
267
 
268
`output EXPRESSION'
269
     Print the value of EXPRESSION and nothing but that value: no
270
     newlines, no `$NN = '.  The value is not entered in the value
271
     history either.  *Note Expressions: Expressions, for more
272
     information on expressions.
273
 
274
`output/FMT EXPRESSION'
275
     Print the value of EXPRESSION in format FMT.  You can use the same
276
     formats as for `print'.  *Note Output formats: Output Formats, for
277
     more information.
278
 
279
`printf STRING, EXPRESSIONS...'
280
     Print the values of the EXPRESSIONS under the control of STRING.
281
     The EXPRESSIONS are separated by commas and may be either numbers
282
     or pointers.  Their values are printed as specified by STRING,
283
     exactly as if your program were to execute the C subroutine
284
 
285
          printf (STRING, EXPRESSIONS...);
286
 
287
     For example, you can print two values in hex like this:
288
 
289
          printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
290
 
291
     The only backslash-escape sequences that you can use in the format
292
     string are the simple ones that consist of backslash followed by a
293
     letter.
294
 
295

296
File: gdb.info,  Node: Emacs,  Next: Annotations,  Prev: Sequences,  Up: Top
297
 
298
Using GDB under GNU Emacs
299
*************************
300
 
301
   A special interface allows you to use GNU Emacs to view (and edit)
302
the source files for the program you are debugging with GDB.
303
 
304
   To use this interface, use the command `M-x gdb' in Emacs.  Give the
305
executable file you want to debug as an argument.  This command starts
306
GDB as a subprocess of Emacs, with input and output through a newly
307
created Emacs buffer.
308
 
309
   Using GDB under Emacs is just like using GDB normally except for two
310
things:
311
 
312
   * All "terminal" input and output goes through the Emacs buffer.
313
 
314
   This applies both to GDB commands and their output, and to the input
315
and output done by the program you are debugging.
316
 
317
   This is useful because it means that you can copy the text of
318
previous commands and input them again; you can even use parts of the
319
output in this way.
320
 
321
   All the facilities of Emacs' Shell mode are available for interacting
322
with your program.  In particular, you can send signals the usual
323
way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop.
324
 
325
   * GDB displays source code through Emacs.
326
 
327
   Each time GDB displays a stack frame, Emacs automatically finds the
328
source file for that frame and puts an arrow (`=>') at the left margin
329
of the current line.  Emacs uses a separate buffer for source display,
330
and splits the screen to show both your GDB session and the source.
331
 
332
   Explicit GDB `list' or search commands still produce output as
333
usual, but you probably have no reason to use them from Emacs.
334
 
335
     _Warning:_ If the directory where your program resides is not your
336
     current directory, it can be easy to confuse Emacs about the
337
     location of the source files, in which case the auxiliary display
338
     buffer does not appear to show your source.  GDB can find programs
339
     by searching your environment's `PATH' variable, so the GDB input
340
     and output session proceeds normally; but Emacs does not get
341
     enough information back from GDB to locate the source files in
342
     this situation.  To avoid this problem, either start GDB mode from
343
     the directory where your program resides, or specify an absolute
344
     file name when prompted for the `M-x gdb' argument.
345
 
346
     A similar confusion can result if you use the GDB `file' command to
347
     switch to debugging a program in some other location, from an
348
     existing GDB buffer in Emacs.
349
 
350
   By default, `M-x gdb' calls the program called `gdb'.  If you need
351
to call GDB by a different name (for example, if you keep several
352
configurations around, with different names) you can set the Emacs
353
variable `gdb-command-name'; for example,
354
 
355
     (setq gdb-command-name "mygdb")
356
 
357
(preceded by `M-:' or `ESC :', or typed in the `*scratch*' buffer, or
358
in your `.emacs' file) makes Emacs call the program named "`mygdb'"
359
instead.
360
 
361
   In the GDB I/O buffer, you can use these special Emacs commands in
362
addition to the standard Shell mode commands:
363
 
364
`C-h m'
365
     Describe the features of Emacs' GDB Mode.
366
 
367
`M-s'
368
     Execute to another source line, like the GDB `step' command; also
369
     update the display window to show the current file and location.
370
 
371
`M-n'
372
     Execute to next source line in this function, skipping all function
373
     calls, like the GDB `next' command.  Then update the display window
374
     to show the current file and location.
375
 
376
`M-i'
377
     Execute one instruction, like the GDB `stepi' command; update
378
     display window accordingly.
379
 
380
`M-x gdb-nexti'
381
     Execute to next instruction, using the GDB `nexti' command; update
382
     display window accordingly.
383
 
384
`C-c C-f'
385
     Execute until exit from the selected stack frame, like the GDB
386
     `finish' command.
387
 
388
`M-c'
389
     Continue execution of your program, like the GDB `continue'
390
     command.
391
 
392
     _Warning:_ In Emacs v19, this command is `C-c C-p'.
393
 
394
`M-u'
395
     Go up the number of frames indicated by the numeric argument
396
     (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
397
     command.
398
 
399
     _Warning:_ In Emacs v19, this command is `C-c C-u'.
400
 
401
`M-d'
402
     Go down the number of frames indicated by the numeric argument,
403
     like the GDB `down' command.
404
 
405
     _Warning:_ In Emacs v19, this command is `C-c C-d'.
406
 
407
`C-x &'
408
     Read the number where the cursor is positioned, and insert it at
409
     the end of the GDB I/O buffer.  For example, if you wish to
410
     disassemble code around an address that was displayed earlier,
411
     type `disassemble'; then move the cursor to the address display,
412
     and pick up the argument for `disassemble' by typing `C-x &'.
413
 
414
     You can customize this further by defining elements of the list
415
     `gdb-print-command'; once it is defined, you can format or
416
     otherwise process numbers picked up by `C-x &' before they are
417
     inserted.  A numeric argument to `C-x &' indicates that you wish
418
     special formatting, and also acts as an index to pick an element
419
     of the list.  If the list element is a string, the number to be
420
     inserted is formatted using the Emacs function `format'; otherwise
421
     the number is passed as an argument to the corresponding list
422
     element.
423
 
424
   In any source file, the Emacs command `C-x SPC' (`gdb-break') tells
425
GDB to set a breakpoint on the source line point is on.
426
 
427
   If you accidentally delete the source-display buffer, an easy way to
428
get it back is to type the command `f' in the GDB buffer, to request a
429
frame display; when you run under Emacs, this recreates the source
430
buffer if necessary to show you the context of the current frame.
431
 
432
   The source files displayed in Emacs are in ordinary Emacs buffers
433
which are visiting the source files in the usual way.  You can edit the
434
files with these buffers if you wish; but keep in mind that GDB
435
communicates with Emacs in terms of line numbers.  If you add or delete
436
lines from the text, the line numbers that GDB knows cease to
437
correspond properly with the code.
438
 
439

440
File: gdb.info,  Node: Annotations,  Next: GDB/MI,  Prev: Emacs,  Up: Top
441
 
442
GDB Annotations
443
***************
444
 
445
   This chapter describes annotations in GDB.  Annotations are designed
446
to interface GDB to graphical user interfaces or other similar programs
447
which want to interact with GDB at a relatively high level.
448
 
449
* Menu:
450
 
451
* Annotations Overview::  What annotations are; the general syntax.
452
* Server Prefix::       Issuing a command without affecting user state.
453
* Value Annotations::   Values are marked as such.
454
* Frame Annotations::   Stack frames are annotated.
455
* Displays::            GDB can be told to display something periodically.
456
* Prompting::           Annotations marking GDB's need for input.
457
* Errors::              Annotations for error messages.
458
* Breakpoint Info::     Information on breakpoints.
459
* Invalidation::        Some annotations describe things now invalid.
460
* Annotations for Running::
461
                        Whether the program is running, how it stopped, etc.
462
* Source Annotations::  Annotations describing source code.
463
* TODO::                Annotations which might be added in the future.
464
 
465

466
File: gdb.info,  Node: Annotations Overview,  Next: Server Prefix,  Up: Annotations
467
 
468
What is an Annotation?
469
======================
470
 
471
   To produce annotations, start GDB with the `--annotate=2' option.
472
 
473
   Annotations start with a newline character, two `control-z'
474
characters, and the name of the annotation.  If there is no additional
475
information associated with this annotation, the name of the annotation
476
is followed immediately by a newline.  If there is additional
477
information, the name of the annotation is followed by a space, the
478
additional information, and a newline.  The additional information
479
cannot contain newline characters.
480
 
481
   Any output not beginning with a newline and two `control-z'
482
characters denotes literal output from GDB.  Currently there is no need
483
for GDB to output a newline followed by two `control-z' characters, but
484
if there was such a need, the annotations could be extended with an
485
`escape' annotation which means those three characters as output.
486
 
487
   A simple example of starting up GDB with annotations is:
488
 
489
     $ gdb --annotate=2
490
     GNU GDB 5.0
491
     Copyright 2000 Free Software Foundation, Inc.
492
     GDB is free software, covered by the GNU General Public License,
493
     and you are welcome to change it and/or distribute copies of it
494
     under certain conditions.
495
     Type "show copying" to see the conditions.
496
     There is absolutely no warranty for GDB.  Type "show warranty"
497
     for details.
498
     This GDB was configured as "sparc-sun-sunos4.1.3"
499
 
500
     ^Z^Zpre-prompt
501
     (gdb)
502
     ^Z^Zprompt
503
     quit
504
 
505
     ^Z^Zpost-prompt
506
     $
507
 
508
   Here `quit' is input to GDB; the rest is output from GDB.  The three
509
lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
510
annotations; the rest is output from GDB.
511
 
512

513
File: gdb.info,  Node: Server Prefix,  Next: Value Annotations,  Prev: Annotations Overview,  Up: Annotations
514
 
515
The Server Prefix
516
=================
517
 
518
   To issue a command to GDB without affecting certain aspects of the
519
state which is seen by users, prefix it with `server '.  This means
520
that this command will not affect the command history, nor will it
521
affect GDB's notion of which command to repeat if  is pressed on a
522
line by itself.
523
 
524
   The server prefix does not affect the recording of values into the
525
value history; to print a value without recording it into the value
526
history, use the `output' command instead of the `print' command.
527
 
528

529
File: gdb.info,  Node: Value Annotations,  Next: Frame Annotations,  Prev: Server Prefix,  Up: Annotations
530
 
531
Values
532
======
533
 
534
   When a value is printed in various contexts, GDB uses annotations to
535
delimit the value from the surrounding text.
536
 
537
   If a value is printed using `print' and added to the value history,
538
the annotation looks like
539
 
540
     ^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS
541
     HISTORY-STRING
542
     ^Z^Zvalue-history-value
543
     THE-VALUE
544
     ^Z^Zvalue-history-end
545
 
546
where HISTORY-NUMBER is the number it is getting in the value history,
547
HISTORY-STRING is a string, such as `$5 = ', which introduces the value
548
to the user, THE-VALUE is the output corresponding to the value itself,
549
and VALUE-FLAGS is `*' for a value which can be dereferenced and `-'
550
for a value which cannot.
551
 
552
   If the value is not added to the value history (it is an invalid
553
float or it is printed with the `output' command), the annotation is
554
similar:
555
 
556
     ^Z^Zvalue-begin VALUE-FLAGS
557
     THE-VALUE
558
     ^Z^Zvalue-end
559
 
560
   When GDB prints an argument to a function (for example, in the output
561
from the `backtrace' command), it annotates it as follows:
562
 
563
     ^Z^Zarg-begin
564
     ARGUMENT-NAME
565
     ^Z^Zarg-name-end
566
     SEPARATOR-STRING
567
     ^Z^Zarg-value VALUE-FLAGS
568
     THE-VALUE
569
     ^Z^Zarg-end
570
 
571
where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is
572
text which separates the name from the value for the user's benefit
573
(such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as
574
in a `value-history-begin' annotation.
575
 
576
   When printing a structure, GDB annotates it as follows:
577
 
578
     ^Z^Zfield-begin VALUE-FLAGS
579
     FIELD-NAME
580
     ^Z^Zfield-name-end
581
     SEPARATOR-STRING
582
     ^Z^Zfield-value
583
     THE-VALUE
584
     ^Z^Zfield-end
585
 
586
where FIELD-NAME is the name of the field, SEPARATOR-STRING is text
587
which separates the name from the value for the user's benefit (such as
588
`='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a
589
`value-history-begin' annotation.
590
 
591
   When printing an array, GDB annotates it as follows:
592
 
593
     ^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS
594
 
595
where ARRAY-INDEX is the index of the first element being annotated and
596
VALUE-FLAGS has the same meaning as in a `value-history-begin'
597
annotation.  This is followed by any number of elements, where is
598
element can be either a single element:
599
 
600
     `,' WHITESPACE         ; omitted for the first element
601
     THE-VALUE
602
     ^Z^Zelt
603
 
604
   or a repeated element
605
 
606
     `,' WHITESPACE         ; omitted for the first element
607
     THE-VALUE
608
     ^Z^Zelt-rep NUMBER-OF-REPITITIONS
609
     REPETITION-STRING
610
     ^Z^Zelt-rep-end
611
 
612
   In both cases, THE-VALUE is the output for the value of the element
613
and WHITESPACE can contain spaces, tabs, and newlines.  In the repeated
614
case, NUMBER-OF-REPITITONS is the number of consecutive array elements
615
which contain that value, and REPETITION-STRING is a string which is
616
designed to convey to the user that repitition is being depicted.
617
 
618
   Once all the array elements have been output, the array annotation is
619
ended with
620
 
621
     ^Z^Zarray-section-end
622
 
623

624
File: gdb.info,  Node: Frame Annotations,  Next: Displays,  Prev: Value Annotations,  Up: Annotations
625
 
626
Frames
627
======
628
 
629
   Whenever GDB prints a frame, it annotates it.  For example, this
630
applies to frames printed when GDB stops, output from commands such as
631
`backtrace' or `up', etc.
632
 
633
   The frame annotation begins with
634
 
635
     ^Z^Zframe-begin LEVEL ADDRESS
636
     LEVEL-STRING
637
 
638
where LEVEL is the number of the frame (0 is the innermost frame, and
639
other frames have positive numbers), ADDRESS is the address of the code
640
executing in that frame, and LEVEL-STRING is a string designed to
641
convey the level to the user.  ADDRESS is in the form `0x' followed by
642
one or more lowercase hex digits (note that this does not depend on the
643
language).  The frame ends with
644
 
645
     ^Z^Zframe-end
646
 
647
   Between these annotations is the main body of the frame, which can
648
consist of
649
 
650
   *      ^Z^Zfunction-call
651
          FUNCTION-CALL-STRING
652
 
653
     where FUNCTION-CALL-STRING is text designed to convey to the user
654
     that this frame is associated with a function call made by GDB to a
655
     function in the program being debugged.
656
 
657
   *      ^Z^Zsignal-handler-caller
658
          SIGNAL-HANDLER-CALLER-STRING
659
 
660
     where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to
661
     the user that this frame is associated with whatever mechanism is
662
     used by this operating system to call a signal handler (it is the
663
     frame which calls the signal handler, not the frame for the signal
664
     handler itself).
665
 
666
   * A normal frame.
667
 
668
     This can optionally (depending on whether this is thought of as
669
     interesting information for the user to see) begin with
670
 
671
          ^Z^Zframe-address
672
          ADDRESS
673
          ^Z^Zframe-address-end
674
          SEPARATOR-STRING
675
 
676
     where ADDRESS is the address executing in the frame (the same
677
     address as in the `frame-begin' annotation, but printed in a form
678
     which is intended for user consumption--in particular, the syntax
679
     varies depending on the language), and SEPARATOR-STRING is a string
680
     intended to separate this address from what follows for the user's
681
     benefit.
682
 
683
     Then comes
684
 
685
          ^Z^Zframe-function-name
686
          FUNCTION-NAME
687
          ^Z^Zframe-args
688
          ARGUMENTS
689
 
690
     where FUNCTION-NAME is the name of the function executing in the
691
     frame, or `??' if not known, and ARGUMENTS are the arguments to
692
     the frame, with parentheses around them (each argument is annotated
693
     individually as well, *note Value Annotations::).
694
 
695
     If source information is available, a reference to it is then
696
     printed:
697
 
698
          ^Z^Zframe-source-begin
699
          SOURCE-INTRO-STRING
700
          ^Z^Zframe-source-file
701
          FILENAME
702
          ^Z^Zframe-source-file-end
703
          :
704
          ^Z^Zframe-source-line
705
          LINE-NUMBER
706
          ^Z^Zframe-source-end
707
 
708
     where SOURCE-INTRO-STRING separates for the user's benefit the
709
     reference from the text which precedes it, FILENAME is the name of
710
     the source file, and LINE-NUMBER is the line number within that
711
     file (the first line is line 1).
712
 
713
     If GDB prints some information about where the frame is from (which
714
     library, which load segment, etc.; currently only done on the
715
     RS/6000), it is annotated with
716
 
717
          ^Z^Zframe-where
718
          INFORMATION
719
 
720
     Then, if source is to actually be displayed for this frame (for
721
     example, this is not true for output from the `backtrace'
722
     command), then a `source' annotation (*note Source Annotations::)
723
     is displayed.  Unlike most annotations, this is output instead of
724
     the normal text which would be output, not in addition.
725
 
726

727
File: gdb.info,  Node: Displays,  Next: Prompting,  Prev: Frame Annotations,  Up: Annotations
728
 
729
Displays
730
========
731
 
732
   When GDB is told to display something using the `display' command,
733
the results of the display are annotated:
734
 
735
     ^Z^Zdisplay-begin
736
     NUMBER
737
     ^Z^Zdisplay-number-end
738
     NUMBER-SEPARATOR
739
     ^Z^Zdisplay-format
740
     FORMAT
741
     ^Z^Zdisplay-expression
742
     EXPRESSION
743
     ^Z^Zdisplay-expression-end
744
     EXPRESSION-SEPARATOR
745
     ^Z^Zdisplay-value
746
     VALUE
747
     ^Z^Zdisplay-end
748
 
749
where NUMBER is the number of the display, NUMBER-SEPARATOR is intended
750
to separate the number from what follows for the user, FORMAT includes
751
information such as the size, format, or other information about how
752
the value is being displayed, EXPRESSION is the expression being
753
displayed, EXPRESSION-SEPARATOR is intended to separate the expression
754
from the text that follows for the user, and VALUE is the actual value
755
being displayed.
756
 
757

758
File: gdb.info,  Node: Prompting,  Next: Errors,  Prev: Displays,  Up: Annotations
759
 
760
Annotation for GDB Input
761
========================
762
 
763
   When GDB prompts for input, it annotates this fact so it is possible
764
to know when to send output, when the output from a given command is
765
over, etc.
766
 
767
   Different kinds of input each have a different "input type".  Each
768
input type has three annotations: a `pre-' annotation, which denotes
769
the beginning of any prompt which is being output, a plain annotation,
770
which denotes the end of the prompt, and then a `post-' annotation
771
which denotes the end of any echo which may (or may not) be associated
772
with the input.  For example, the `prompt' input type features the
773
following annotations:
774
 
775
     ^Z^Zpre-prompt
776
     ^Z^Zprompt
777
     ^Z^Zpost-prompt
778
 
779
   The input types are
780
 
781
`prompt'
782
     When GDB is prompting for a command (the main GDB prompt).
783
 
784
`commands'
785
     When GDB prompts for a set of commands, like in the `commands'
786
     command.  The annotations are repeated for each command which is
787
     input.
788
 
789
`overload-choice'
790
     When GDB wants the user to select between various overloaded
791
     functions.
792
 
793
`query'
794
     When GDB wants the user to confirm a potentially dangerous
795
     operation.
796
 
797
`prompt-for-continue'
798
     When GDB is asking the user to press return to continue.  Note:
799
     Don't expect this to work well; instead use `set height 0' to
800
     disable prompting.  This is because the counting of lines is buggy
801
     in the presence of annotations.
802
 
803

804
File: gdb.info,  Node: Errors,  Next: Breakpoint Info,  Prev: Prompting,  Up: Annotations
805
 
806
Errors
807
======
808
 
809
     ^Z^Zquit
810
 
811
   This annotation occurs right before GDB responds to an interrupt.
812
 
813
     ^Z^Zerror
814
 
815
   This annotation occurs right before GDB responds to an error.
816
 
817
   Quit and error annotations indicate that any annotations which GDB
818
was in the middle of may end abruptly.  For example, if a
819
`value-history-begin' annotation is followed by a `error', one cannot
820
expect to receive the matching `value-history-end'.  One cannot expect
821
not to receive it either, however; an error annotation does not
822
necessarily mean that GDB is immediately returning all the way to the
823
top level.
824
 
825
   A quit or error annotation may be preceded by
826
 
827
     ^Z^Zerror-begin
828
 
829
   Any output between that and the quit or error annotation is the error
830
message.
831
 
832
   Warning messages are not yet annotated.
833
 
834

835
File: gdb.info,  Node: Breakpoint Info,  Next: Invalidation,  Prev: Errors,  Up: Annotations
836
 
837
Information on Breakpoints
838
==========================
839
 
840
   The output from the `info breakpoints' command is annotated as
841
follows:
842
 
843
     ^Z^Zbreakpoints-headers
844
     HEADER-ENTRY
845
     ^Z^Zbreakpoints-table
846
 
847
where HEADER-ENTRY has the same syntax as an entry (see below) but
848
instead of containing data, it contains strings which are intended to
849
convey the meaning of each field to the user.  This is followed by any
850
number of entries.  If a field does not apply for this entry, it is
851
omitted.  Fields may contain trailing whitespace.  Each entry consists
852
of:
853
 
854
     ^Z^Zrecord
855
     ^Z^Zfield 0
856
     NUMBER
857
     ^Z^Zfield 1
858
     TYPE
859
     ^Z^Zfield 2
860
     DISPOSITION
861
     ^Z^Zfield 3
862
     ENABLE
863
     ^Z^Zfield 4
864
     ADDRESS
865
     ^Z^Zfield 5
866
     WHAT
867
     ^Z^Zfield 6
868
     FRAME
869
     ^Z^Zfield 7
870
     CONDITION
871
     ^Z^Zfield 8
872
     IGNORE-COUNT
873
     ^Z^Zfield 9
874
     COMMANDS
875
 
876
   Note that ADDRESS is intended for user consumption--the syntax
877
varies depending on the language.
878
 
879
   The output ends with
880
 
881
     ^Z^Zbreakpoints-table-end
882
 
883

884
File: gdb.info,  Node: Invalidation,  Next: Annotations for Running,  Prev: Breakpoint Info,  Up: Annotations
885
 
886
Invalidation Notices
887
====================
888
 
889
   The following annotations say that certain pieces of state may have
890
changed.
891
 
892
`^Z^Zframes-invalid'
893
     The frames (for example, output from the `backtrace' command) may
894
     have changed.
895
 
896
`^Z^Zbreakpoints-invalid'
897
     The breakpoints may have changed.  For example, the user just
898
     added or deleted a breakpoint.
899
 
900

901
File: gdb.info,  Node: Annotations for Running,  Next: Source Annotations,  Prev: Invalidation,  Up: Annotations
902
 
903
Running the Program
904
===================
905
 
906
   When the program starts executing due to a GDB command such as
907
`step' or `continue',
908
 
909
     ^Z^Zstarting
910
 
911
   is output.  When the program stops,
912
 
913
     ^Z^Zstopped
914
 
915
   is output.  Before the `stopped' annotation, a variety of
916
annotations describe how the program stopped.
917
 
918
`^Z^Zexited EXIT-STATUS'
919
     The program exited, and EXIT-STATUS is the exit status (zero for
920
     successful exit, otherwise nonzero).
921
 
922
`^Z^Zsignalled'
923
     The program exited with a signal.  After the `^Z^Zsignalled', the
924
     annotation continues:
925
 
926
          INTRO-TEXT
927
          ^Z^Zsignal-name
928
          NAME
929
          ^Z^Zsignal-name-end
930
          MIDDLE-TEXT
931
          ^Z^Zsignal-string
932
          STRING
933
          ^Z^Zsignal-string-end
934
          END-TEXT
935
 
936
     where NAME is the name of the signal, such as `SIGILL' or
937
     `SIGSEGV', and STRING is the explanation of the signal, such as
938
     `Illegal Instruction' or `Segmentation fault'.  INTRO-TEXT,
939
     MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
940
     particular format.
941
 
942
`^Z^Zsignal'
943
     The syntax of this annotation is just like `signalled', but GDB is
944
     just saying that the program received the signal, not that it was
945
     terminated with it.
946
 
947
`^Z^Zbreakpoint NUMBER'
948
     The program hit breakpoint number NUMBER.
949
 
950
`^Z^Zwatchpoint NUMBER'
951
     The program hit watchpoint number NUMBER.
952
 
953

954
File: gdb.info,  Node: Source Annotations,  Next: TODO,  Prev: Annotations for Running,  Up: Annotations
955
 
956
Displaying Source
957
=================
958
 
959
   The following annotation is used instead of displaying source code:
960
 
961
     ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
962
 
963
   where FILENAME is an absolute file name indicating which source
964
file, LINE is the line number within that file (where 1 is the first
965
line in the file), CHARACTER is the character position within the file
966
(where 0 is the first character in the file) (for most debug formats
967
this will necessarily point to the beginning of a line), MIDDLE is
968
`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
969
the beginning of the line, and ADDR is the address in the target
970
program associated with the source which is being displayed.  ADDR is
971
in the form `0x' followed by one or more lowercase hex digits (note
972
that this does not depend on the language).
973
 
974

975
File: gdb.info,  Node: TODO,  Prev: Source Annotations,  Up: Annotations
976
 
977
Annotations We Might Want in the Future
978
=======================================
979
 
980
    - target-invalid
981
      the target might have changed (registers, heap contents, or
982
      execution status).  For performance, we might eventually want
983
      to hit `registers-invalid' and `all-registers-invalid' with
984
      greater precision
985
 
986
    - systematic annotation for set/show parameters (including
987
      invalidation notices).
988
 
989
    - similarly, `info' returns a list of candidates for invalidation
990
      notices.
991
 
992

993
File: gdb.info,  Node: GDB/MI,  Next: GDB Bugs,  Prev: Annotations,  Up: Top
994
 
995
The GDB/MI Interface
996
********************
997
 
998
Function and Purpose
999
====================
1000
 
1001
   GDB/MI is a line based machine oriented text interface to GDB.  It is
1002
specifically intended to support the development of systems which use
1003
the debugger as just one small component of a larger system.
1004
 
1005
   This chapter is a specification of the GDB/MI interface.  It is
1006
written in the form of a reference manual.
1007
 
1008
   Note that GDB/MI is still under construction, so some of the
1009
features described below are incomplete and subject to change.
1010
 
1011
Notation and Terminology
1012
========================
1013
 
1014
   This chapter uses the following notation:
1015
 
1016
   * `|' separates two alternatives.
1017
 
1018
   * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
1019
     may not be given.
1020
 
1021
   * `( GROUP )*' means that GROUP inside the parentheses may repeat
1022
     zero or more times.
1023
 
1024
   * `( GROUP )+' means that GROUP inside the parentheses may repeat
1025
     one or more times.
1026
 
1027
   * `"STRING"' means a literal STRING.
1028
 
1029
Acknowledgments
1030
===============
1031
 
1032
   In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
1033
Elena Zannoni.
1034
 
1035
* Menu:
1036
 
1037
* GDB/MI Command Syntax::
1038
* GDB/MI Compatibility with CLI::
1039
* GDB/MI Output Records::
1040
* GDB/MI Command Description Format::
1041
* GDB/MI Breakpoint Table Commands::
1042
* GDB/MI Data Manipulation::
1043
* GDB/MI Program Control::
1044
* GDB/MI Miscellaneous Commands::
1045
* GDB/MI Stack Manipulation::
1046
* GDB/MI Symbol Query::
1047
* GDB/MI Target Manipulation::
1048
* GDB/MI Thread Commands::
1049
* GDB/MI Tracepoint Commands::
1050
* GDB/MI Variable Objects::
1051
 
1052

1053
File: gdb.info,  Node: GDB/MI Command Syntax,  Next: GDB/MI Compatibility with CLI,  Up: GDB/MI
1054
 
1055
GDB/MI Command Syntax
1056
=====================
1057
 
1058
* Menu:
1059
 
1060
* GDB/MI Input Syntax::
1061
* GDB/MI Output Syntax::
1062
* GDB/MI Simple Examples::
1063
 
1064

1065
File: gdb.info,  Node: GDB/MI Input Syntax,  Next: GDB/MI Output Syntax,  Up: GDB/MI Command Syntax
1066
 
1067
GDB/MI Input Syntax
1068
-------------------
1069
 
1070
`COMMAND ==>'
1071
     `CLI-COMMAND | MI-COMMAND'
1072
 
1073
`CLI-COMMAND ==>'
1074
     `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
1075
     CLI command.
1076
 
1077
`MI-COMMAND ==>'
1078
     `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
1079
     PARAMETER )* NL'
1080
 
1081
`TOKEN ==>'
1082
     "any sequence of digits"
1083
 
1084
`OPTION ==>'
1085
     `"-" PARAMETER [ " " PARAMETER ]'
1086
 
1087
`PARAMETER ==>'
1088
     `NON-BLANK-SEQUENCE | C-STRING'
1089
 
1090
`OPERATION ==>'
1091
     _any of the operations described in this chapter_
1092
 
1093
`NON-BLANK-SEQUENCE ==>'
1094
     _anything, provided it doesn't contain special characters such as
1095
     "-", NL, """ and of course " "_
1096
 
1097
`C-STRING ==>'
1098
     `""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
1099
 
1100
`NL ==>'
1101
     `CR | CR-LF'
1102
 
1103
Notes:
1104
 
1105
   * The CLI commands are still handled by the MI interpreter; their
1106
     output is described below.
1107
 
1108
   * The `TOKEN', when present, is passed back when the command
1109
     finishes.
1110
 
1111
   * Some MI commands accept optional arguments as part of the parameter
1112
     list.  Each option is identified by a leading `-' (dash) and may be
1113
     followed by an optional argument parameter.  Options occur first
1114
     in the parameter list and can be delimited from normal parameters
1115
     using `--' (this is useful when some parameters begin with a dash).
1116
 
1117
   Pragmatics:
1118
 
1119
   * We want easy access to the existing CLI syntax (for debugging).
1120
 
1121
   * We want it to be easy to spot a MI operation.
1122
 
1123

1124
File: gdb.info,  Node: GDB/MI Output Syntax,  Next: GDB/MI Simple Examples,  Prev: GDB/MI Input Syntax,  Up: GDB/MI Command Syntax
1125
 
1126
GDB/MI Output Syntax
1127
--------------------
1128
 
1129
   The output from GDB/MI consists of zero or more out-of-band records
1130
followed, optionally, by a single result record.  This result record is
1131
for the most recent command.  The sequence of output records is
1132
terminated by `(gdb)'.
1133
 
1134
   If an input command was prefixed with a `TOKEN' then the
1135
corresponding output for that command will also be prefixed by that same
1136
TOKEN.
1137
 
1138
`OUTPUT ==>'
1139
     `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'
1140
 
1141
`RESULT-RECORD ==>'
1142
     ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'
1143
 
1144
`OUT-OF-BAND-RECORD ==>'
1145
     `ASYNC-RECORD | STREAM-RECORD'
1146
 
1147
`ASYNC-RECORD ==>'
1148
     `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'
1149
 
1150
`EXEC-ASYNC-OUTPUT ==>'
1151
     `[ TOKEN ] "*" ASYNC-OUTPUT'
1152
 
1153
`STATUS-ASYNC-OUTPUT ==>'
1154
     `[ TOKEN ] "+" ASYNC-OUTPUT'
1155
 
1156
`NOTIFY-ASYNC-OUTPUT ==>'
1157
     `[ TOKEN ] "=" ASYNC-OUTPUT'
1158
 
1159
`ASYNC-OUTPUT ==>'
1160
     `ASYNC-CLASS ( "," RESULT )* NL'
1161
 
1162
`RESULT-CLASS ==>'
1163
     `"done" | "running" | "connected" | "error" | "exit"'
1164
 
1165
`ASYNC-CLASS ==>'
1166
     `"stopped" | OTHERS' (where OTHERS will be added depending on the
1167
     needs--this is still in development).
1168
 
1169
`RESULT ==>'
1170
     ` VARIABLE "=" VALUE'
1171
 
1172
`VARIABLE ==>'
1173
     ` STRING '
1174
 
1175
`VALUE ==>'
1176
     ` CONST | TUPLE | LIST '
1177
 
1178
`CONST ==>'
1179
     `C-STRING'
1180
 
1181
`TUPLE ==>'
1182
     ` "{}" | "{" RESULT ( "," RESULT )* "}" '
1183
 
1184
`LIST ==>'
1185
     ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*
1186
     "]" '
1187
 
1188
`STREAM-RECORD ==>'
1189
     `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'
1190
 
1191
`CONSOLE-STREAM-OUTPUT ==>'
1192
     `"~" C-STRING'
1193
 
1194
`TARGET-STREAM-OUTPUT ==>'
1195
     `"@" C-STRING'
1196
 
1197
`LOG-STREAM-OUTPUT ==>'
1198
     `"&" C-STRING'
1199
 
1200
`NL ==>'
1201
     `CR | CR-LF'
1202
 
1203
`TOKEN ==>'
1204
     _any sequence of digits_.
1205
 
1206
Notes:
1207
 
1208
   * All output sequences end in a single line containing a period.
1209
 
1210
   * The `TOKEN' is from the corresponding request.  If an execution
1211
     command is interrupted by the `-exec-interrupt' command, the TOKEN
1212
     associated with the `*stopped' message is the one of the original
1213
     execution command, not the one of the interrupt command.
1214
 
1215
   * STATUS-ASYNC-OUTPUT contains on-going status information about the
1216
     progress of a slow operation.  It can be discarded.  All status
1217
     output is prefixed by `+'.
1218
 
1219
   * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
1220
     (stopped, started, disappeared).  All async output is prefixed by
1221
     `*'.
1222
 
1223
   * NOTIFY-ASYNC-OUTPUT contains supplementary information that the
1224
     client should handle (e.g., a new breakpoint information).  All
1225
     notify output is prefixed by `='.
1226
 
1227
   * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in
1228
     the console.  It is the textual response to a CLI command.  All
1229
     the console output is prefixed by `~'.
1230
 
1231
   * TARGET-STREAM-OUTPUT is the output produced by the target program.
1232
     All the target output is prefixed by `@'.
1233
 
1234
   * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
1235
     instance messages that should be displayed as part of an error
1236
     log.  All the log output is prefixed by `&'.
1237
 
1238
   * New GDB/MI commands should only output LISTS containing VALUES.
1239
 
1240
 
1241
   *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
1242
about the various output records.
1243
 
1244

1245
File: gdb.info,  Node: GDB/MI Simple Examples,  Prev: GDB/MI Output Syntax,  Up: GDB/MI Command Syntax
1246
 
1247
Simple Examples of GDB/MI Interaction
1248
-------------------------------------
1249
 
1250
   This subsection presents several simple examples of interaction using
1251
the GDB/MI interface.  In these examples, `->' means that the following
1252
line is passed to GDB/MI as input, while `<-' means the output received
1253
from GDB/MI.
1254
 
1255
Target Stop
1256
...........
1257
 
1258
   Here's an example of stopping the inferior process:
1259
 
1260
     -> -stop
1261
     <- (gdb)
1262
 
1263
and later:
1264
 
1265
     <- *stop,reason="stop",address="0x123",source="a.c:123"
1266
     <- (gdb)
1267
 
1268
Simple CLI Command
1269
..................
1270
 
1271
   Here's an example of a simple CLI command being passed through
1272
GDB/MI and on to the CLI.
1273
 
1274
     -> print 1+2
1275
     <- ~3\n
1276
     <- (gdb)
1277
 
1278
Command With Side Effects
1279
.........................
1280
 
1281
     -> -symbol-file xyz.exe
1282
     <- *breakpoint,nr="3",address="0x123",source="a.c:123"
1283
     <- (gdb)
1284
 
1285
A Bad Command
1286
.............
1287
 
1288
   Here's what happens if you pass a non-existent command:
1289
 
1290
     -> -rubbish
1291
     <- error,"Rubbish not found"
1292
     <- (gdb)
1293
 
1294

1295
File: gdb.info,  Node: GDB/MI Compatibility with CLI,  Next: GDB/MI Output Records,  Prev: GDB/MI Command Syntax,  Up: GDB/MI
1296
 
1297
GDB/MI Compatibility with CLI
1298
=============================
1299
 
1300
   To help users familiar with GDB's existing CLI interface, GDB/MI
1301
accepts existing CLI commands.  As specified by the syntax, such
1302
commands can be directly entered into the GDB/MI interface and GDB will
1303
respond.
1304
 
1305
   This mechanism is provided as an aid to developers of GDB/MI clients
1306
and not as a reliable interface into the CLI.  Since the command is
1307
being interpreteted in an environment that assumes GDB/MI behaviour,
1308
the exact output of such commands is likely to end up being an
1309
un-supported hybrid of GDB/MI and CLI output.
1310
 
1311

1312
File: gdb.info,  Node: GDB/MI Output Records,  Next: GDB/MI Command Description Format,  Prev: GDB/MI Compatibility with CLI,  Up: GDB/MI
1313
 
1314
GDB/MI Output Records
1315
=====================
1316
 
1317
* Menu:
1318
 
1319
* GDB/MI Result Records::
1320
* GDB/MI Stream Records::
1321
* GDB/MI Out-of-band Records::
1322
 
1323

1324
File: gdb.info,  Node: GDB/MI Result Records,  Next: GDB/MI Stream Records,  Up: GDB/MI Output Records
1325
 
1326
GDB/MI Result Records
1327
---------------------
1328
 
1329
   In addition to a number of out-of-band notifications, the response
1330
to a GDB/MI command includes one of the following result indications:
1331
 
1332
`"^done" [ "," RESULTS ]'
1333
     The synchronous operation was successful, `RESULTS' are the return
1334
     values.
1335
 
1336
`"^running"'
1337
     The asynchronous operation was successfully started.  The target is
1338
     running.
1339
 
1340
`"^error" "," C-STRING'
1341
     The operation failed.  The `C-STRING' contains the corresponding
1342
     error message.
1343
 
1344

1345
File: gdb.info,  Node: GDB/MI Stream Records,  Next: GDB/MI Out-of-band Records,  Prev: GDB/MI Result Records,  Up: GDB/MI Output Records
1346
 
1347
GDB/MI Stream Records
1348
---------------------
1349
 
1350
   GDB internally maintains a number of output streams: the console, the
1351
target, and the log.  The output intended for each of these streams is
1352
funneled through the GDB/MI interface using "stream records".
1353
 
1354
   Each stream record begins with a unique "prefix character" which
1355
identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
1356
Syntax.).  In addition to the prefix, each stream record contains a
1357
`STRING-OUTPUT'.  This is either raw text (with an implicit new line)
1358
or a quoted C string (which does not contain an implicit newline).
1359
 
1360
`"~" STRING-OUTPUT'
1361
     The console output stream contains text that should be displayed
1362
     in the CLI console window.  It contains the textual responses to
1363
     CLI commands.
1364
 
1365
`"@" STRING-OUTPUT'
1366
     The target output stream contains any textual output from the
1367
     running target.
1368
 
1369
`"&" STRING-OUTPUT'
1370
     The log stream contains debugging messages being produced by GDB's
1371
     internals.
1372
 
1373

1374
File: gdb.info,  Node: GDB/MI Out-of-band Records,  Prev: GDB/MI Stream Records,  Up: GDB/MI Output Records
1375
 
1376
GDB/MI Out-of-band Records
1377
--------------------------
1378
 
1379
   "Out-of-band" records are used to notify the GDB/MI client of
1380
additional changes that have occurred.  Those changes can either be a
1381
consequence of GDB/MI (e.g., a breakpoint modified) or a result of
1382
target activity (e.g., target stopped).
1383
 
1384
   The following is a preliminary list of possible out-of-band records.
1385
 
1386
`"*" "stop"'
1387

1388
File: gdb.info,  Node: GDB/MI Command Description Format,  Next: GDB/MI Breakpoint Table Commands,  Prev: GDB/MI Output Records,  Up: GDB/MI
1389
 
1390
GDB/MI Command Description Format
1391
=================================
1392
 
1393
   The remaining sections describe blocks of commands.  Each block of
1394
commands is laid out in a fashion similar to this section.
1395
 
1396
   Note the the line breaks shown in the examples are here only for
1397
readability.  They don't appear in the real output.  Also note that the
1398
commands with a non-available example (N.A.) are not yet implemented.
1399
 
1400
Motivation
1401
----------
1402
 
1403
   The motivation for this collection of commands.
1404
 
1405
Introduction
1406
------------
1407
 
1408
   A brief introduction to this collection of commands as a whole.
1409
 
1410
Commands
1411
--------
1412
 
1413
   For each command in the block, the following is described:
1414
 
1415
Synopsis
1416
........
1417
 
1418
      -command ARGS...
1419
 
1420
GDB Command
1421
...........
1422
 
1423
   The corresponding GDB CLI command.
1424
 
1425
Result
1426
......
1427
 
1428
Out-of-band
1429
...........
1430
 
1431
Notes
1432
.....
1433
 
1434
Example
1435
.......
1436
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.