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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [gdb/] [doc/] [gdb.info-9] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 362 markom
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
2 106 markom
 
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 Eighth Edition, March 2000, of `Debugging with GDB: the
11
GNU Source-Level Debugger' for GDB Version 5.0.
12
 
13
   Copyright (C) 1988-2000 Free Software Foundation, Inc.
14
 
15
   Permission is granted to make and distribute verbatim copies of this
16
manual provided the copyright notice and this permission notice are
17
preserved on all copies.
18
 
19
   Permission is granted to copy and distribute modified versions of
20
this manual under the conditions for verbatim copying, provided also
21
that the entire resulting derived work is distributed under the terms
22
of a permission notice identical to this one.
23
 
24
   Permission is granted to copy and distribute translations of this
25
manual into another language, under the above conditions for modified
26
versions.
27
 
28

29
File: gdb.info,  Node: Messages/Warnings,  Next: Debugging Output,  Prev: Numbers,  Up: Controlling GDB
30
 
31
Optional warnings and messages
32
==============================
33
 
34
   By default, GDB is silent about its inner workings.  If you are
35
running on a slow machine, you may want to use the `set verbose'
36
command.  This makes GDB tell you when it does a lengthy internal
37
operation, so you will not think it has crashed.
38
 
39
   Currently, the messages controlled by `set verbose' are those which
40
announce that the symbol table for a source file is being read; see
41
`symbol-file' in *Note Commands to specify files: Files.
42
 
43
`set verbose on'
44
     Enables GDB output of certain informational messages.
45
 
46
`set verbose off'
47
     Disables GDB output of certain informational messages.
48
 
49
`show verbose'
50
     Displays whether `set verbose' is on or off.
51
 
52
   By default, if GDB encounters bugs in the symbol table of an object
53
file, it is silent; but if you are debugging a compiler, you may find
54
this information useful (*note Errors reading symbol files: Symbol
55
Errors.).
56
 
57
`set complaints LIMIT'
58
     Permits GDB to output LIMIT complaints about each type of unusual
59
     symbols before becoming silent about the problem.  Set LIMIT to
60
     zero to suppress all complaints; set it to a large number to
61
     prevent complaints from being suppressed.
62
 
63
`show complaints'
64
     Displays how many symbol complaints GDB is permitted to produce.
65
 
66
   By default, GDB is cautious, and asks what sometimes seems to be a
67
lot of stupid questions to confirm certain commands.  For example, if
68
you try to run a program which is already running:
69
 
70
     (gdb) run
71
     The program being debugged has been started already.
72
     Start it from the beginning? (y or n)
73
 
74
   If you are willing to unflinchingly face the consequences of your own
75
commands, you can disable this "feature":
76
 
77
`set confirm off'
78
     Disables confirmation requests.
79
 
80
`set confirm on'
81
     Enables confirmation requests (the default).
82
 
83
`show confirm'
84
     Displays state of confirmation requests.
85
 
86

87
File: gdb.info,  Node: Debugging Output,  Prev: Messages/Warnings,  Up: Controlling GDB
88
 
89
Optional messages about internal happenings
90
===========================================
91
 
92
`set debug arch'
93
     Turns on or off display of gdbarch debugging info. The default is
94
     off
95
 
96
`show debug arch'
97
     Displays the current state of displaying gdbarch debugging info.
98
 
99
`set debug event'
100
     Turns on or off display of GDB event debugging info. The default
101
     is off.
102
 
103
`show debug event'
104
     Displays the current state of displaying GDB event debugging info.
105
 
106
`set debug expression'
107
     Turns on or off display of GDB expression debugging info. The
108
     default is off.
109
 
110
`show debug expression'
111
     Displays the current state of displaying GDB expression debugging
112
     info.
113
 
114
`set debug overload'
115
     Turns on or off display of GDB C++ overload debugging info. This
116
     includes info such as ranking of functions, etc. The default is
117
     off.
118
 
119
`show debug overload'
120
     Displays the current state of displaying GDB C++ overload
121
     debugging info.
122
 
123
`set debug remote'
124
     Turns on or off display of reports on all packets sent back and
125
     forth across the serial line to the remote machine.  The info is
126
     printed on the GDB standard output stream. The default is off.
127
 
128
`show debug remote'
129
     Displays the state of display of remote packets.
130
 
131
`set debug serial'
132
     Turns on or off display of GDB serial debugging info. The default
133
     is off.
134
 
135
`show debug serial'
136
     Displays the current state of displaying GDB serial debugging info.
137
 
138
`set debug target'
139
     Turns on or off display of GDB target debugging info. This info
140
     includes what is going on at the target level of GDB, as it
141
     happens. The default is off.
142
 
143
`show debug target'
144
     Displays the current state of displaying GDB target debugging info.
145
 
146
`set debug varobj'
147
     Turns on or off display of GDB variable object debugging info. The
148
     default is off.
149
 
150
`show debug varobj'
151
     Displays the current state of displaying GDB variable object
152
     debugging info.
153
 
154

155
File: gdb.info,  Node: Sequences,  Next: Emacs,  Prev: Controlling GDB,  Up: Top
156
 
157
Canned Sequences of Commands
158
****************************
159
 
160
   Aside from breakpoint commands (*note Breakpoint command lists:
161
Break Commands.), GDB provides two ways to store sequences of commands
162
for execution as a unit: user-defined commands and command files.
163
 
164
* Menu:
165
 
166
* Define::                      User-defined commands
167
* Hooks::                       User-defined command hooks
168
* Command Files::               Command files
169
* Output::                      Commands for controlled output
170
 
171

172
File: gdb.info,  Node: Define,  Next: Hooks,  Up: Sequences
173
 
174
User-defined commands
175
=====================
176
 
177
   A "user-defined command" is a sequence of GDB commands to which you
178
assign a new name as a command.  This is done with the `define'
179
command.  User commands may accept up to 10 arguments separated by
180
whitespace.  Arguments are accessed within the user command via
181
$ARG0...$ARG9.  A trivial example:
182
 
183
     define adder
184
       print $arg0 + $arg1 + $arg2
185
 
186
To execute the command use:
187
 
188
     adder 1 2 3
189
 
190
This defines the command `adder', which prints the sum of its three
191
arguments.  Note the arguments are text substitutions, so they may
192
reference variables, use complex expressions, or even perform inferior
193
functions calls.
194
 
195
`define COMMANDNAME'
196
     Define a command named COMMANDNAME.  If there is already a command
197
     by that name, you are asked to confirm that you want to redefine
198
     it.
199
 
200
     The definition of the command is made up of other GDB command
201
     lines, which are given following the `define' command.  The end of
202
     these commands is marked by a line containing `end'.
203
 
204
`if'
205
     Takes a single argument, which is an expression to evaluate.  It
206
     is followed by a series of commands that are executed only if the
207
     expression is true (nonzero).  There can then optionally be a line
208
     `else', followed by a series of commands that are only executed if
209
     the expression was false.  The end of the list is marked by a line
210
     containing `end'.
211
 
212
`while'
213
     The syntax is similar to `if': the command takes a single argument,
214
     which is an expression to evaluate, and must be followed by the
215
     commands to execute, one per line, terminated by an `end'.  The
216
     commands are executed repeatedly as long as the expression
217
     evaluates to true.
218
 
219
`document COMMANDNAME'
220
     Document the user-defined command COMMANDNAME, so that it can be
221
     accessed by `help'.  The command COMMANDNAME must already be
222
     defined.  This command reads lines of documentation just as
223
     `define' reads the lines of the command definition, ending with
224
     `end'.  After the `document' command is finished, `help' on command
225
     COMMANDNAME displays the documentation you have written.
226
 
227
     You may use the `document' command again to change the
228
     documentation of a command.  Redefining the command with `define'
229
     does not change the documentation.
230
 
231
`help user-defined'
232
     List all user-defined commands, with the first line of the
233
     documentation (if any) for each.
234
 
235
`show user'
236
`show user COMMANDNAME'
237
     Display the GDB commands used to define COMMANDNAME (but not its
238
     documentation).  If no COMMANDNAME is given, display the
239
     definitions for all user-defined commands.
240
 
241
   When user-defined commands are executed, the commands of the
242
definition are not printed.  An error in any command stops execution of
243
the user-defined command.
244
 
245
   If used interactively, commands that would ask for confirmation
246
proceed without asking when used inside a user-defined command.  Many
247
GDB commands that normally print messages to say what they are doing
248
omit the messages when used in a user-defined command.
249
 
250

251
File: gdb.info,  Node: Hooks,  Next: Command Files,  Prev: Define,  Up: Sequences
252
 
253
User-defined command hooks
254
==========================
255
 
256
   You may define _hooks_, which are a special kind of user-defined
257
command.  Whenever you run the command `foo', if the user-defined
258
command `hook-foo' exists, it is executed (with no arguments) before
259
that command.
260
 
261
   In addition, a pseudo-command, `stop' exists.  Defining
262
(`hook-stop') makes the associated commands execute every time
263
execution stops in your program: before breakpoint commands are run,
264
displays are printed, or the stack frame is printed.
265
 
266
   For example, to ignore `SIGALRM' signals while single-stepping, but
267
treat them normally during normal execution, you could define:
268
 
269
     define hook-stop
270
     handle SIGALRM nopass
271
     end
272
 
273
     define hook-run
274
     handle SIGALRM pass
275
     end
276
 
277
     define hook-continue
278
     handle SIGLARM pass
279
     end
280
 
281
   You can define a hook for any single-word command in GDB, but not
282
for command aliases; you should define a hook for the basic command
283
name, e.g.  `backtrace' rather than `bt'.  If an error occurs during
284
the execution of your hook, execution of GDB commands stops and GDB
285
issues a prompt (before the command that you actually typed had a
286
chance to run).
287
 
288
   If you try to define a hook which does not match any known command,
289
you get a warning from the `define' command.
290
 
291

292
File: gdb.info,  Node: Command Files,  Next: Output,  Prev: Hooks,  Up: Sequences
293
 
294
Command files
295
=============
296
 
297
   A command file for GDB is a file of lines that are GDB commands.
298
Comments (lines starting with `#') may also be included.  An empty line
299
in a command file does nothing; it does not mean to repeat the last
300
command, as it would from the terminal.
301
 
302
   When you start GDB, it automatically executes commands from its
303
"init files".  These are files named `.gdbinit' on Unix, or `gdb.ini'
304
on DOS/Windows.  GDB reads the init file (if any) in your home
305
directory(1), then processes command line options and operands, and then
306
reads the init file (if any) in the current working directory.  This is
307
so the init file in your home directory can set options (such as `set
308
complaints') which affect the processing of the command line options
309
and operands.  The init files are not executed if you use the `-nx'
310
option; *note Choosing modes: Mode Options..
311
 
312
   On some configurations of GDB, the init file is known by a different
313
name (these are typically environments where a specialized form of GDB
314
may need to coexist with other forms, hence a different name for the
315
specialized version's init file).  These are the environments with
316
special init file names:
317
 
318
   * VxWorks (Wind River Systems real-time OS): `.vxgdbinit'
319
 
320
   * OS68K (Enea Data Systems real-time OS): `.os68gdbinit'
321
 
322
   * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit'
323
 
324
   You can also request the execution of a command file with the
325
`source' command:
326
 
327
`source FILENAME'
328
     Execute the command file FILENAME.
329
 
330
   The lines in a command file are executed sequentially.  They are not
331
printed as they are executed.  An error in any command terminates
332
execution of the command file.
333
 
334
   Commands that would ask for confirmation if used interactively
335
proceed without asking when used in a command file.  Many GDB commands
336
that normally print messages to say what they are doing omit the
337
messages when called from command files.
338
 
339
   ---------- Footnotes ----------
340
 
341
   (1) On DOS/Windows systems, the home directory is the one pointed to
342
by the `HOME' environment variable.
343
 
344

345
File: gdb.info,  Node: Output,  Prev: Command Files,  Up: Sequences
346
 
347
Commands for controlled output
348
==============================
349
 
350
   During the execution of a command file or a user-defined command,
351
normal GDB output is suppressed; the only output that appears is what is
352
explicitly printed by the commands in the definition.  This section
353
describes three commands useful for generating exactly the output you
354
want.
355
 
356
`echo TEXT'
357
     Print TEXT.  Nonprinting characters can be included in TEXT using
358
     C escape sequences, such as `\n' to print a newline.  *No newline
359
     is printed unless you specify one.* In addition to the standard C
360
     escape sequences, a backslash followed by a space stands for a
361
     space.  This is useful for displaying a string with spaces at the
362
     beginning or the end, since leading and trailing spaces are
363
     otherwise trimmed from all arguments.  To print ` and foo = ', use
364
     the command `echo \ and foo = \ '.
365
 
366
     A backslash at the end of TEXT can be used, as in C, to continue
367
     the command onto subsequent lines.  For example,
368
 
369
          echo This is some text\n\
370
          which is continued\n\
371
          onto several lines.\n
372
 
373
     produces the same output as
374
 
375
          echo This is some text\n
376
          echo which is continued\n
377
          echo onto several lines.\n
378
 
379
`output EXPRESSION'
380
     Print the value of EXPRESSION and nothing but that value: no
381
     newlines, no `$NN = '.  The value is not entered in the value
382
     history either.  *Note Expressions: Expressions, for more
383
     information on expressions.
384
 
385
`output/FMT EXPRESSION'
386
     Print the value of EXPRESSION in format FMT.  You can use the same
387
     formats as for `print'.  *Note Output formats: Output Formats, for
388
     more information.
389
 
390
`printf STRING, EXPRESSIONS...'
391
     Print the values of the EXPRESSIONS under the control of STRING.
392
     The EXPRESSIONS are separated by commas and may be either numbers
393
     or pointers.  Their values are printed as specified by STRING,
394
     exactly as if your program were to execute the C subroutine
395
 
396
          printf (STRING, EXPRESSIONS...);
397
 
398
     For example, you can print two values in hex like this:
399
 
400
          printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
401
 
402
     The only backslash-escape sequences that you can use in the format
403
     string are the simple ones that consist of backslash followed by a
404
     letter.
405
 
406

407
File: gdb.info,  Node: Emacs,  Next: Annotations,  Prev: Sequences,  Up: Top
408
 
409
Using GDB under GNU Emacs
410
*************************
411
 
412
   A special interface allows you to use GNU Emacs to view (and edit)
413
the source files for the program you are debugging with GDB.
414
 
415
   To use this interface, use the command `M-x gdb' in Emacs.  Give the
416
executable file you want to debug as an argument.  This command starts
417
GDB as a subprocess of Emacs, with input and output through a newly
418
created Emacs buffer.
419
 
420
   Using GDB under Emacs is just like using GDB normally except for two
421
things:
422
 
423
   * All "terminal" input and output goes through the Emacs buffer.
424
 
425
   This applies both to GDB commands and their output, and to the input
426
and output done by the program you are debugging.
427
 
428
   This is useful because it means that you can copy the text of
429
previous commands and input them again; you can even use parts of the
430
output in this way.
431
 
432
   All the facilities of Emacs' Shell mode are available for interacting
433
with your program.  In particular, you can send signals the usual
434
way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop.
435
 
436
   * GDB displays source code through Emacs.
437
 
438
   Each time GDB displays a stack frame, Emacs automatically finds the
439
source file for that frame and puts an arrow (`=>') at the left margin
440
of the current line.  Emacs uses a separate buffer for source display,
441
and splits the screen to show both your GDB session and the source.
442
 
443
   Explicit GDB `list' or search commands still produce output as
444
usual, but you probably have no reason to use them from Emacs.
445
 
446
     _Warning:_ If the directory where your program resides is not your
447
     current directory, it can be easy to confuse Emacs about the
448
     location of the source files, in which case the auxiliary display
449
     buffer does not appear to show your source.  GDB can find programs
450
     by searching your environment's `PATH' variable, so the GDB input
451
     and output session proceeds normally; but Emacs does not get
452
     enough information back from GDB to locate the source files in
453
     this situation.  To avoid this problem, either start GDB mode from
454
     the directory where your program resides, or specify an absolute
455
     file name when prompted for the `M-x gdb' argument.
456
 
457
     A similar confusion can result if you use the GDB `file' command to
458
     switch to debugging a program in some other location, from an
459
     existing GDB buffer in Emacs.
460
 
461
   By default, `M-x gdb' calls the program called `gdb'.  If you need
462
to call GDB by a different name (for example, if you keep several
463
configurations around, with different names) you can set the Emacs
464
variable `gdb-command-name'; for example,
465
 
466
     (setq gdb-command-name "mygdb")
467
 
468
(preceded by `M-:' or `ESC :', or typed in the `*scratch*' buffer, or
469
in your `.emacs' file) makes Emacs call the program named "`mygdb'"
470
instead.
471
 
472
   In the GDB I/O buffer, you can use these special Emacs commands in
473
addition to the standard Shell mode commands:
474
 
475
`C-h m'
476
     Describe the features of Emacs' GDB Mode.
477
 
478
`M-s'
479
     Execute to another source line, like the GDB `step' command; also
480
     update the display window to show the current file and location.
481
 
482
`M-n'
483
     Execute to next source line in this function, skipping all function
484
     calls, like the GDB `next' command.  Then update the display window
485
     to show the current file and location.
486
 
487
`M-i'
488
     Execute one instruction, like the GDB `stepi' command; update
489
     display window accordingly.
490
 
491
`M-x gdb-nexti'
492
     Execute to next instruction, using the GDB `nexti' command; update
493
     display window accordingly.
494
 
495
`C-c C-f'
496
     Execute until exit from the selected stack frame, like the GDB
497
     `finish' command.
498
 
499
`M-c'
500
     Continue execution of your program, like the GDB `continue'
501
     command.
502
 
503
     _Warning:_ In Emacs v19, this command is `C-c C-p'.
504
 
505
`M-u'
506
     Go up the number of frames indicated by the numeric argument
507
     (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
508
     command.
509
 
510
     _Warning:_ In Emacs v19, this command is `C-c C-u'.
511
 
512
`M-d'
513
     Go down the number of frames indicated by the numeric argument,
514
     like the GDB `down' command.
515
 
516
     _Warning:_ In Emacs v19, this command is `C-c C-d'.
517
 
518
`C-x &'
519
     Read the number where the cursor is positioned, and insert it at
520
     the end of the GDB I/O buffer.  For example, if you wish to
521
     disassemble code around an address that was displayed earlier,
522
     type `disassemble'; then move the cursor to the address display,
523
     and pick up the argument for `disassemble' by typing `C-x &'.
524
 
525
     You can customize this further by defining elements of the list
526
     `gdb-print-command'; once it is defined, you can format or
527
     otherwise process numbers picked up by `C-x &' before they are
528
     inserted.  A numeric argument to `C-x &' indicates that you wish
529
     special formatting, and also acts as an index to pick an element
530
     of the list.  If the list element is a string, the number to be
531
     inserted is formatted using the Emacs function `format'; otherwise
532
     the number is passed as an argument to the corresponding list
533
     element.
534
 
535
   In any source file, the Emacs command `C-x SPC' (`gdb-break') tells
536
GDB to set a breakpoint on the source line point is on.
537
 
538
   If you accidentally delete the source-display buffer, an easy way to
539
get it back is to type the command `f' in the GDB buffer, to request a
540
frame display; when you run under Emacs, this recreates the source
541
buffer if necessary to show you the context of the current frame.
542
 
543
   The source files displayed in Emacs are in ordinary Emacs buffers
544
which are visiting the source files in the usual way.  You can edit the
545
files with these buffers if you wish; but keep in mind that GDB
546
communicates with Emacs in terms of line numbers.  If you add or delete
547
lines from the text, the line numbers that GDB knows cease to
548
correspond properly with the code.
549
 
550

551
File: gdb.info,  Node: Annotations,  Next: GDB/MI,  Prev: Emacs,  Up: Top
552
 
553
GDB Annotations
554
***************
555
 
556
   This chapter describes annotations in GDB.  Annotations are designed
557
to interface GDB to graphical user interfaces or other similar programs
558
which want to interact with GDB at a relatively high level.
559
 
560
* Menu:
561
 
562
* Annotations Overview::  What annotations are; the general syntax.
563
* Server Prefix::       Issuing a command without affecting user state.
564
* Value Annotations::   Values are marked as such.
565
* Frame Annotations::   Stack frames are annotated.
566
* Displays::            GDB can be told to display something periodically.
567
* Prompting::           Annotations marking GDB's need for input.
568
* Errors::              Annotations for error messages.
569
* Breakpoint Info::     Information on breakpoints.
570
* Invalidation::        Some annotations describe things now invalid.
571
* Annotations for Running::
572
                        Whether the program is running, how it stopped, etc.
573
* Source Annotations::  Annotations describing source code.
574
* TODO::                Annotations which might be added in the future.
575
 
576

577
File: gdb.info,  Node: Annotations Overview,  Next: Server Prefix,  Up: Annotations
578
 
579
What is an Annotation?
580
======================
581
 
582
   To produce annotations, start GDB with the `--annotate=2' option.
583
 
584
   Annotations start with a newline character, two `control-z'
585
characters, and the name of the annotation.  If there is no additional
586
information associated with this annotation, the name of the annotation
587
is followed immediately by a newline.  If there is additional
588
information, the name of the annotation is followed by a space, the
589
additional information, and a newline.  The additional information
590
cannot contain newline characters.
591
 
592
   Any output not beginning with a newline and two `control-z'
593
characters denotes literal output from GDB.  Currently there is no need
594
for GDB to output a newline followed by two `control-z' characters, but
595
if there was such a need, the annotations could be extended with an
596
`escape' annotation which means those three characters as output.
597
 
598
   A simple example of starting up GDB with annotations is:
599
 
600
     $ gdb --annotate=2
601
     GNU GDB 5.0
602
     Copyright 2000 Free Software Foundation, Inc.
603
     GDB is free software, covered by the GNU General Public License,
604
     and you are welcome to change it and/or distribute copies of it
605
     under certain conditions.
606
     Type "show copying" to see the conditions.
607
     There is absolutely no warranty for GDB.  Type "show warranty"
608
     for details.
609
     This GDB was configured as "sparc-sun-sunos4.1.3"
610
 
611
     ^Z^Zpre-prompt
612
     (gdb)
613
     ^Z^Zprompt
614
     quit
615
 
616
     ^Z^Zpost-prompt
617
     $
618
 
619
   Here `quit' is input to GDB; the rest is output from GDB.  The three
620
lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
621
annotations; the rest is output from GDB.
622
 
623

624
File: gdb.info,  Node: Server Prefix,  Next: Value Annotations,  Prev: Annotations Overview,  Up: Annotations
625
 
626
The Server Prefix
627
=================
628
 
629
   To issue a command to GDB without affecting certain aspects of the
630
state which is seen by users, prefix it with `server '.  This means
631
that this command will not affect the command history, nor will it
632
affect GDB's notion of which command to repeat if  is pressed on a
633
line by itself.
634
 
635
   The server prefix does not affect the recording of values into the
636
value history; to print a value without recording it into the value
637
history, use the `output' command instead of the `print' command.
638
 
639

640
File: gdb.info,  Node: Value Annotations,  Next: Frame Annotations,  Prev: Server Prefix,  Up: Annotations
641
 
642
Values
643
======
644
 
645
   When a value is printed in various contexts, GDB uses annotations to
646
delimit the value from the surrounding text.
647
 
648
   If a value is printed using `print' and added to the value history,
649
the annotation looks like
650
 
651
     ^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS
652
     HISTORY-STRING
653
     ^Z^Zvalue-history-value
654
     THE-VALUE
655
     ^Z^Zvalue-history-end
656
 
657
   where HISTORY-NUMBER is the number it is getting in the value
658
history, HISTORY-STRING is a string, such as `$5 = ', which introduces
659
the value to the user, THE-VALUE is the output corresponding to the
660
value itself, and VALUE-FLAGS is `*' for a value which can be
661
dereferenced and `-' for a value which cannot.
662
 
663
   If the value is not added to the value history (it is an invalid
664
float or it is printed with the `output' command), the annotation is
665
similar:
666
 
667
     ^Z^Zvalue-begin VALUE-FLAGS
668
     THE-VALUE
669
     ^Z^Zvalue-end
670
 
671
   When GDB prints an argument to a function (for example, in the output
672
from the `backtrace' command), it annotates it as follows:
673
 
674
     ^Z^Zarg-begin
675
     ARGUMENT-NAME
676
     ^Z^Zarg-name-end
677
     SEPARATOR-STRING
678
     ^Z^Zarg-value VALUE-FLAGS
679
     THE-VALUE
680
     ^Z^Zarg-end
681
 
682
   where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is
683
text which separates the name from the value for the user's benefit
684
(such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as
685
in a `value-history-begin' annotation.
686
 
687
   When printing a structure, GDB annotates it as follows:
688
 
689
     ^Z^Zfield-begin VALUE-FLAGS
690
     FIELD-NAME
691
     ^Z^Zfield-name-end
692
     SEPARATOR-STRING
693
     ^Z^Zfield-value
694
     THE-VALUE
695
     ^Z^Zfield-end
696
 
697
   where FIELD-NAME is the name of the field, SEPARATOR-STRING is text
698
which separates the name from the value for the user's benefit (such as
699
`='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a
700
`value-history-begin' annotation.
701
 
702
   When printing an array, GDB annotates it as follows:
703
 
704
     ^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS
705
 
706
   where ARRAY-INDEX is the index of the first element being annotated
707
and VALUE-FLAGS has the same meaning as in a `value-history-begin'
708
annotation.  This is followed by any number of elements, where is
709
element can be either a single element:
710
 
711
     `,' WHITESPACE         ; omitted for the first element
712
     THE-VALUE
713
     ^Z^Zelt
714
 
715
   or a repeated element
716
 
717
     `,' WHITESPACE         ; omitted for the first element
718
     THE-VALUE
719
     ^Z^Zelt-rep NUMBER-OF-REPITITIONS
720
     REPETITION-STRING
721
     ^Z^Zelt-rep-end
722
 
723
   In both cases, THE-VALUE is the output for the value of the element
724
and WHITESPACE can contain spaces, tabs, and newlines.  In the repeated
725
case, NUMBER-OF-REPITITONS is the number of consecutive array elements
726
which contain that value, and REPETITION-STRING is a string which is
727
designed to convey to the user that repitition is being depicted.
728
 
729
   Once all the array elements have been output, the array annotation is
730
ended with
731
 
732
     ^Z^Zarray-section-end
733
 
734

735
File: gdb.info,  Node: Frame Annotations,  Next: Displays,  Prev: Value Annotations,  Up: Annotations
736
 
737
Frames
738
======
739
 
740
   Whenever GDB prints a frame, it annotates it.  For example, this
741
applies to frames printed when GDB stops, output from commands such as
742
`backtrace' or `up', etc.
743
 
744
   The frame annotation begins with
745
 
746
     ^Z^Zframe-begin LEVEL ADDRESS
747
     LEVEL-STRING
748
 
749
   where LEVEL is the number of the frame (0 is the innermost frame,
750
and other frames have positive numbers), ADDRESS is the address of the
751
code executing in that frame, and LEVEL-STRING is a string designed to
752
convey the level to the user.  ADDRESS is in the form `0x' followed by
753
one or more lowercase hex digits (note that this does not depend on the
754
language).  The frame ends with
755
 
756
     ^Z^Zframe-end
757
 
758
   Between these annotations is the main body of the frame, which can
759
consist of
760
 
761
   *      ^Z^Zfunction-call
762
          FUNCTION-CALL-STRING
763
 
764
     where FUNCTION-CALL-STRING is text designed to convey to the user
765
     that this frame is associated with a function call made by GDB to a
766
     function in the program being debugged.
767
 
768
   *      ^Z^Zsignal-handler-caller
769
          SIGNAL-HANDLER-CALLER-STRING
770
 
771
     where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to
772
     the user that this frame is associated with whatever mechanism is
773
     used by this operating system to call a signal handler (it is the
774
     frame which calls the signal handler, not the frame for the signal
775
     handler itself).
776
 
777
   * A normal frame.
778
 
779
     This can optionally (depending on whether this is thought of as
780
     interesting information for the user to see) begin with
781
 
782
          ^Z^Zframe-address
783
          ADDRESS
784
          ^Z^Zframe-address-end
785
          SEPARATOR-STRING
786
 
787
     where ADDRESS is the address executing in the frame (the same
788
     address as in the `frame-begin' annotation, but printed in a form
789
     which is intended for user consumption--in particular, the syntax
790
     varies depending on the language), and SEPARATOR-STRING is a string
791
     intended to separate this address from what follows for the user's
792
     benefit.
793
 
794
     Then comes
795
 
796
          ^Z^Zframe-function-name
797
          FUNCTION-NAME
798
          ^Z^Zframe-args
799
          ARGUMENTS
800
 
801
     where FUNCTION-NAME is the name of the function executing in the
802
     frame, or `??' if not known, and ARGUMENTS are the arguments to
803
     the frame, with parentheses around them (each argument is annotated
804 362 markom
     individually as well, *note Value Annotations::).
805 106 markom
 
806
     If source information is available, a reference to it is then
807
     printed:
808
 
809
          ^Z^Zframe-source-begin
810
          SOURCE-INTRO-STRING
811
          ^Z^Zframe-source-file
812
          FILENAME
813
          ^Z^Zframe-source-file-end
814
          :
815
          ^Z^Zframe-source-line
816
          LINE-NUMBER
817
          ^Z^Zframe-source-end
818
 
819
     where SOURCE-INTRO-STRING separates for the user's benefit the
820
     reference from the text which precedes it, FILENAME is the name of
821
     the source file, and LINE-NUMBER is the line number within that
822
     file (the first line is line 1).
823
 
824
     If GDB prints some information about where the frame is from (which
825
     library, which load segment, etc.; currently only done on the
826
     RS/6000), it is annotated with
827
 
828
          ^Z^Zframe-where
829
          INFORMATION
830
 
831
     Then, if source is to actually be displayed for this frame (for
832
     example, this is not true for output from the `backtrace'
833 362 markom
     command), then a `source' annotation (*note Source Annotations::)
834 106 markom
     is displayed.  Unlike most annotations, this is output instead of
835
     the normal text which would be output, not in addition.
836
 
837

838
File: gdb.info,  Node: Displays,  Next: Prompting,  Prev: Frame Annotations,  Up: Annotations
839
 
840
Displays
841
========
842
 
843
   When GDB is told to display something using the `display' command,
844
the results of the display are annotated:
845
 
846
     ^Z^Zdisplay-begin
847
     NUMBER
848
     ^Z^Zdisplay-number-end
849
     NUMBER-SEPARATOR
850
     ^Z^Zdisplay-format
851
     FORMAT
852
     ^Z^Zdisplay-expression
853
     EXPRESSION
854
     ^Z^Zdisplay-expression-end
855
     EXPRESSION-SEPARATOR
856
     ^Z^Zdisplay-value
857
     VALUE
858
     ^Z^Zdisplay-end
859
 
860
   where NUMBER is the number of the display, NUMBER-SEPARATOR is
861
intended to separate the number from what follows for the user, FORMAT
862
includes information such as the size, format, or other information
863
about how the value is being displayed, EXPRESSION is the expression
864
being displayed, EXPRESSION-SEPARATOR is intended to separate the
865
expression from the text that follows for the user, and VALUE is the
866
actual value being displayed.
867
 
868

869
File: gdb.info,  Node: Prompting,  Next: Errors,  Prev: Displays,  Up: Annotations
870
 
871
Annotation for GDB Input
872
========================
873
 
874
   When GDB prompts for input, it annotates this fact so it is possible
875
to know when to send output, when the output from a given command is
876
over, etc.
877
 
878
   Different kinds of input each have a different "input type".  Each
879
input type has three annotations: a `pre-' annotation, which denotes
880
the beginning of any prompt which is being output, a plain annotation,
881
which denotes the end of the prompt, and then a `post-' annotation
882
which denotes the end of any echo which may (or may not) be associated
883
with the input.  For example, the `prompt' input type features the
884
following annotations:
885
 
886
     ^Z^Zpre-prompt
887
     ^Z^Zprompt
888
     ^Z^Zpost-prompt
889
 
890
   The input types are
891
 
892
`prompt'
893
     When GDB is prompting for a command (the main GDB prompt).
894
 
895
`commands'
896
     When GDB prompts for a set of commands, like in the `commands'
897
     command.  The annotations are repeated for each command which is
898
     input.
899
 
900
`overload-choice'
901
     When GDB wants the user to select between various overloaded
902
     functions.
903
 
904
`query'
905
     When GDB wants the user to confirm a potentially dangerous
906
     operation.
907
 
908
`prompt-for-continue'
909
     When GDB is asking the user to press return to continue.  Note:
910
     Don't expect this to work well; instead use `set height 0' to
911
     disable prompting.  This is because the counting of lines is buggy
912
     in the presence of annotations.
913
 
914

915
File: gdb.info,  Node: Errors,  Next: Breakpoint Info,  Prev: Prompting,  Up: Annotations
916
 
917
Errors
918
======
919
 
920
     ^Z^Zquit
921
 
922
   This annotation occurs right before GDB responds to an interrupt.
923
 
924
     ^Z^Zerror
925
 
926
   This annotation occurs right before GDB responds to an error.
927
 
928
   Quit and error annotations indicate that any annotations which GDB
929
was in the middle of may end abruptly.  For example, if a
930
`value-history-begin' annotation is followed by a `error', one cannot
931
expect to receive the matching `value-history-end'.  One cannot expect
932
not to receive it either, however; an error annotation does not
933
necessarily mean that GDB is immediately returning all the way to the
934
top level.
935
 
936
   A quit or error annotation may be preceded by
937
 
938
     ^Z^Zerror-begin
939
 
940
   Any output between that and the quit or error annotation is the error
941
message.
942
 
943
   Warning messages are not yet annotated.
944
 
945

946
File: gdb.info,  Node: Breakpoint Info,  Next: Invalidation,  Prev: Errors,  Up: Annotations
947
 
948
Information on Breakpoints
949
==========================
950
 
951
   The output from the `info breakpoints' command is annotated as
952
follows:
953
 
954
     ^Z^Zbreakpoints-headers
955
     HEADER-ENTRY
956
     ^Z^Zbreakpoints-table
957
 
958
   where HEADER-ENTRY has the same syntax as an entry (see below) but
959
instead of containing data, it contains strings which are intended to
960
convey the meaning of each field to the user.  This is followed by any
961
number of entries.  If a field does not apply for this entry, it is
962
omitted.  Fields may contain trailing whitespace.  Each entry consists
963
of:
964
 
965
     ^Z^Zrecord
966
     ^Z^Zfield 0
967
     NUMBER
968
     ^Z^Zfield 1
969
     TYPE
970
     ^Z^Zfield 2
971
     DISPOSITION
972
     ^Z^Zfield 3
973
     ENABLE
974
     ^Z^Zfield 4
975
     ADDRESS
976
     ^Z^Zfield 5
977
     WHAT
978
     ^Z^Zfield 6
979
     FRAME
980
     ^Z^Zfield 7
981
     CONDITION
982
     ^Z^Zfield 8
983
     IGNORE-COUNT
984
     ^Z^Zfield 9
985
     COMMANDS
986
 
987
   Note that ADDRESS is intended for user consumption--the syntax
988
varies depending on the language.
989
 
990
   The output ends with
991
 
992
     ^Z^Zbreakpoints-table-end
993
 
994

995
File: gdb.info,  Node: Invalidation,  Next: Annotations for Running,  Prev: Breakpoint Info,  Up: Annotations
996
 
997
Invalidation Notices
998
====================
999
 
1000
   The following annotations say that certain pieces of state may have
1001
changed.
1002
 
1003
`^Z^Zframes-invalid'
1004
     The frames (for example, output from the `backtrace' command) may
1005
     have changed.
1006
 
1007
`^Z^Zbreakpoints-invalid'
1008
     The breakpoints may have changed.  For example, the user just
1009
     added or deleted a breakpoint.
1010
 
1011

1012
File: gdb.info,  Node: Annotations for Running,  Next: Source Annotations,  Prev: Invalidation,  Up: Annotations
1013
 
1014
Running the Program
1015
===================
1016
 
1017
   When the program starts executing due to a GDB command such as
1018
`step' or `continue',
1019
 
1020
     ^Z^Zstarting
1021
 
1022
   is output.  When the program stops,
1023
 
1024
     ^Z^Zstopped
1025
 
1026
   is output.  Before the `stopped' annotation, a variety of
1027
annotations describe how the program stopped.
1028
 
1029
`^Z^Zexited EXIT-STATUS'
1030
     The program exited, and EXIT-STATUS is the exit status (zero for
1031
     successful exit, otherwise nonzero).
1032
 
1033
`^Z^Zsignalled'
1034
     The program exited with a signal.  After the `^Z^Zsignalled', the
1035
     annotation continues:
1036
 
1037
          INTRO-TEXT
1038
          ^Z^Zsignal-name
1039
          NAME
1040
          ^Z^Zsignal-name-end
1041
          MIDDLE-TEXT
1042
          ^Z^Zsignal-string
1043
          STRING
1044
          ^Z^Zsignal-string-end
1045
          END-TEXT
1046
 
1047
     where NAME is the name of the signal, such as `SIGILL' or
1048
     `SIGSEGV', and STRING is the explanation of the signal, such as
1049
     `Illegal Instruction' or `Segmentation fault'.  INTRO-TEXT,
1050
     MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
1051
     particular format.
1052
 
1053
`^Z^Zsignal'
1054
     The syntax of this annotation is just like `signalled', but GDB is
1055
     just saying that the program received the signal, not that it was
1056
     terminated with it.
1057
 
1058
`^Z^Zbreakpoint NUMBER'
1059
     The program hit breakpoint number NUMBER.
1060
 
1061
`^Z^Zwatchpoint NUMBER'
1062
     The program hit watchpoint number NUMBER.
1063
 
1064

1065
File: gdb.info,  Node: Source Annotations,  Next: TODO,  Prev: Annotations for Running,  Up: Annotations
1066
 
1067
Displaying Source
1068
=================
1069
 
1070
   The following annotation is used instead of displaying source code:
1071
 
1072
     ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
1073
 
1074
   where FILENAME is an absolute file name indicating which source
1075
file, LINE is the line number within that file (where 1 is the first
1076
line in the file), CHARACTER is the character position within the file
1077
(where 0 is the first character in the file) (for most debug formats
1078
this will necessarily point to the beginning of a line), MIDDLE is
1079
`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
1080
the beginning of the line, and ADDR is the address in the target
1081
program associated with the source which is being displayed.  ADDR is
1082
in the form `0x' followed by one or more lowercase hex digits (note
1083
that this does not depend on the language).
1084
 
1085

1086
File: gdb.info,  Node: TODO,  Prev: Source Annotations,  Up: Annotations
1087
 
1088
Annotations We Might Want in the Future
1089
=======================================
1090
 
1091
    - target-invalid
1092
      the target might have changed (registers, heap contents, or
1093
      execution status).  For performance, we might eventually want
1094
      to hit `registers-invalid' and `all-registers-invalid' with
1095
      greater precision
1096
 
1097
    - systematic annotation for set/show parameters (including
1098
      invalidation notices).
1099
 
1100
    - similarly, `info' returns a list of candidates for invalidation
1101
      notices.
1102
 
1103

1104
File: gdb.info,  Node: GDB/MI,  Next: GDB Bugs,  Prev: Annotations,  Up: Top
1105
 
1106
The GDB/MI Interface
1107
********************
1108
 
1109
Function and Purpose
1110
====================
1111
 
1112
   GDB/MI is a line based machine oriented text interface to GDB.  It is
1113
specifically intended to support the development of systems which use
1114
the debugger as just one small component of a larger system.
1115
 
1116
   This chapter is a specification of the GDB/MI interface.  It is
1117
written in the form of a reference manual.
1118
 
1119
   Note that GDB/MI is still under construction, so some of the
1120
features described below are incomplete and subject to change.
1121
 
1122
Notation and Terminology
1123
========================
1124
 
1125
   This chapter uses the following notation:
1126
 
1127
   * `|' separates two alternatives.
1128
 
1129
   * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
1130
     may not be given.
1131
 
1132
   * `( GROUP )*' means that GROUP inside the parentheses may repeat
1133
     zero or more times.
1134
 
1135
   * `( GROUP )+' means that GROUP inside the parentheses may repeat
1136
     one or more times.
1137
 
1138
   * `"STRING"' means a literal STRING.
1139
 
1140
Acknowledgments
1141
===============
1142
 
1143
   In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
1144
Elena Zannoni.
1145
 
1146
* Menu:
1147
 
1148
* GDB/MI Command Syntax::
1149
* GDB/MI Compatibility with CLI::
1150
* GDB/MI Output Records::
1151
* GDB/MI Command Description Format::
1152
* GDB/MI Breakpoint Table Commands::
1153
* GDB/MI Data Manipulation::
1154
* GDB/MI Program Control::
1155
* GDB/MI Miscellaneous Commands::
1156
* GDB/MI Stack Manipulation::
1157
* GDB/MI Symbol Query::
1158
* GDB/MI Target Manipulation::
1159
* GDB/MI Thread Commands::
1160
* GDB/MI Tracepoint Commands::
1161
* GDB/MI Variable Objects::
1162
* GDB/MI Draft Changes to Output Syntax::
1163
 
1164

1165
File: gdb.info,  Node: GDB/MI Command Syntax,  Next: GDB/MI Compatibility with CLI,  Up: GDB/MI
1166
 
1167
GDB/MI Command Syntax
1168
=====================
1169
 
1170
* Menu:
1171
 
1172
* GDB/MI Input Syntax::
1173
* GDB/MI Output Syntax::
1174
* GDB/MI Simple Examples::
1175
 
1176

1177
File: gdb.info,  Node: GDB/MI Input Syntax,  Next: GDB/MI Output Syntax,  Up: GDB/MI Command Syntax
1178
 
1179
GDB/MI Input Syntax
1180
-------------------
1181
 
1182
`COMMAND ==>'
1183
     `CLI-COMMAND | MI-COMMAND'
1184
 
1185
`CLI-COMMAND ==>'
1186
     `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
1187
     CLI command.
1188
 
1189
`MI-COMMAND ==>'
1190
     `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
1191
     PARAMETER )* NL'
1192
 
1193
`TOKEN ==>'
1194
     `"any sequence of digits"'
1195
 
1196
`OPTION ==>'
1197
     `"-" PARAMETER [ " " PARAMETER ]'
1198
 
1199
`PARAMETER ==>'
1200
     `NON-BLANK-SEQUENCE | C-STRING'
1201
 
1202
`OPERATION ==>'
1203
     _any of the operations described in this document_
1204
 
1205
`NON-BLANK-SEQUENCE ==>'
1206
     _anything, provided it doesn't contain special characters such as
1207
     "-", NL, """ and of course " "_
1208
 
1209
`C-STRING ==>'
1210
     `""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
1211
 
1212
`NL ==>'
1213
     `CR | CR-LF'
1214
 
1215
   Notes:
1216
 
1217
   * The CLI commands are still handled by the MI interpreter; their
1218
     output is described below.
1219
 
1220
   * The `TOKEN', when present, is passed back when the command
1221
     finishes.
1222
 
1223
   * Some MI commands accept optional arguments as part of the parameter
1224
     list. Each option is identified by a leading `-' (dash) and may be
1225
     followed by an optional argument parameter.  Options occur first
1226
     in the parameter list and can be delimited from normal parameters
1227
     using `--' (this is useful when some parameters begin with a dash).
1228
 
1229
   Pragmatics:
1230
 
1231
   * We want easy access to the existing CLI syntax (for debugging).
1232
 
1233
   * We want it to be easy to spot a MI operation.
1234
 
1235

1236
File: gdb.info,  Node: GDB/MI Output Syntax,  Next: GDB/MI Simple Examples,  Prev: GDB/MI Input Syntax,  Up: GDB/MI Command Syntax
1237
 
1238
GDB/MI Output Syntax
1239
--------------------
1240
 
1241
   The output from GDB/MI consists of zero or more out-of-band records
1242
followed, optionally, by a single result record.  This result record is
1243
for the most recent command.  The sequence of output records is
1244
terminated by `(gdb)'.
1245
 
1246
   If an input command was prefixed with a `TOKEN' then the
1247
corresponding output for that command will also be prefixed by that same
1248
TOKEN.
1249
 
1250
`OUTPUT ==>'
1251
     `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'
1252
 
1253
`RESULT-RECORD ==>'
1254
     ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'
1255
 
1256
`OUT-OF-BAND-RECORD ==>'
1257
     `ASYNC-RECORD | STREAM-RECORD'
1258
 
1259
`ASYNC-RECORD ==>'
1260
     `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'
1261
 
1262
`EXEC-ASYNC-OUTPUT ==>'
1263
     `[ TOKEN ] "*" ASYNC-OUTPUT'
1264
 
1265
`STATUS-ASYNC-OUTPUT ==>'
1266
     `[ TOKEN ] "+" ASYNC-OUTPUT'
1267
 
1268
`NOTIFY-ASYNC-OUTPUT ==>'
1269
     `[ TOKEN ] "=" ASYNC-OUTPUT'
1270
 
1271
`ASYNC-OUTPUT ==>'
1272
     `ASYNC-CLASS ( "," RESULT )* NL'
1273
 
1274
`RESULT-CLASS ==>'
1275
     `"done" | "running" | "connected" | "error" | "exit"'
1276
 
1277
`ASYNC-CLASS ==>'
1278
     `"stopped" | OTHERS' (where OTHERS will be added depending on the
1279
     needs--this is still in development).
1280
 
1281
`RESULT ==>'
1282
     `[ STRING "=" ] VALUE'
1283
 
1284
`VALUE ==>'
1285
     `CONST | "{" RESULT ( "," RESULT )* "}"'
1286
 
1287
`CONST ==>'
1288
     `C-STRING'
1289
 
1290
`STREAM-RECORD ==>'
1291
     `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'
1292
 
1293
`CONSOLE-STREAM-OUTPUT ==>'
1294
     `"~" C-STRING'
1295
 
1296
`TARGET-STREAM-OUTPUT ==>'
1297
     `"@" C-STRING'
1298
 
1299
`LOG-STREAM-OUTPUT ==>'
1300
     `"&" C-STRING'
1301
 
1302
`NL ==>'
1303
     `CR | CR-LF'
1304
 
1305
`TOKEN ==>'
1306
     _any sequence of digits_.
1307
 
1308
   In addition, the following are still being developed:
1309
 
1310
`QUERY'
1311
     This action is currently undefined.
1312
 
1313
   Notes:
1314
 
1315
   * All output sequences end in a single line containing a period.
1316
 
1317
   * The `TOKEN' is from the corresponding request.  If an execution
1318
     command is interrupted by the `-exec-interrupt' command, the TOKEN
1319
     associated with the `*stopped' message is the one of the original
1320
     execution command, not the one of the interrupt-command.
1321
 
1322
   * STATUS-ASYNC-OUTPUT contains on-going status information about the
1323
     progress of a slow operation.  It can be discarded.  All status
1324
     output is prefixed by `+'.
1325
 
1326
   * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
1327
     (stopped, started, disappeared).  All async output is prefixed by
1328
     `*'.
1329
 
1330
   * NOTIFY-ASYNC-OUTPUT contains supplementary information that the
1331
     client should handle (e.g., a new breakpoint information).  All
1332
     notify output is prefixed by `='.
1333
 
1334
   * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in
1335
     the console.  It is the textual response to a CLI command.  All
1336
     the console output is prefixed by `~'.
1337
 
1338
   * TARGET-STREAM-OUTPUT is the output produced by the target program.
1339
     All the target output is prefixed by `@'.
1340
 
1341
   * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
1342
     instance messages that should be displayed as part of an error
1343
     log.  All the log output is prefixed by `&'.
1344
 
1345
   *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
1346
about the various output records.
1347
 
1348
   *Note GDB/MI Draft Changes to Output Syntax: GDB/MI Draft Changes to
1349
Output Syntax, for proposed revisions to the current output syntax.
1350
 
1351

1352
File: gdb.info,  Node: GDB/MI Simple Examples,  Prev: GDB/MI Output Syntax,  Up: GDB/MI Command Syntax
1353
 
1354
Simple Examples of GDB/MI Interaction
1355
-------------------------------------
1356
 
1357
   This subsection presents several simple examples of interaction using
1358
the GDB/MI interface.  In these examples, `->' means that the following
1359
line is passed to GDB/MI as input, while `<-' means the output received
1360
from GDB/MI.
1361
 
1362
Target Stop
1363
...........
1364
 
1365
   Here's an example of stopping the inferior process:
1366
 
1367
     -> -stop
1368
     <- (gdb)
1369
 
1370
and later:
1371
 
1372
     <- *stop,reason="stop",address="0x123",source="a.c:123"
1373
     <- (gdb)
1374
 
1375
Simple CLI Command
1376
..................
1377
 
1378
   Here's an example of a simple CLI command being passed through
1379
GDB/MI and on to the CLI.
1380
 
1381
     -> print 1+2
1382
     <- ~3\n
1383
     <- (gdb)
1384
 
1385
Command With Side Effects
1386
.........................
1387
 
1388
     -> -symbol-file xyz.exe
1389
     <- *breakpoint,nr="3",address="0x123",source="a.c:123"
1390
     <- (gdb)
1391
 
1392
A Bad Command
1393
.............
1394
 
1395
   Here's what happens if you pass a non-existent command:
1396
 
1397
     -> -rubbish
1398
     <- error,"Rubbish not found"
1399
     <- (gdb)
1400
 
1401

1402
File: gdb.info,  Node: GDB/MI Compatibility with CLI,  Next: GDB/MI Output Records,  Prev: GDB/MI Command Syntax,  Up: GDB/MI
1403
 
1404
GDB/MI Compatibility with CLI
1405
=============================
1406
 
1407
   To help users familiar with GDB's existing CLI interface, GDB/MI
1408
accepts existing CLI commands.  As specified by the syntax, such
1409
commands can be directly entered into the GDB/MI interface and GDB will
1410
respond.
1411
 
1412
   This mechanism is provided as an aid to developers of GDB/MI clients
1413
and not as a reliable interface into the CLI.  Since the command is
1414
being interpreteted in an environment that assumes GDB/MI behaviour,
1415
the exact output of such commands is likely to end up being an
1416
un-supported hybrid of GDB/MI and CLI output.
1417
 
1418

1419
File: gdb.info,  Node: GDB/MI Output Records,  Next: GDB/MI Command Description Format,  Prev: GDB/MI Compatibility with CLI,  Up: GDB/MI
1420
 
1421
GDB/MI Output Records
1422
=====================
1423
 
1424
* Menu:
1425
 
1426
* GDB/MI Result Records::
1427
* GDB/MI Stream Records::
1428
* GDB/MI Out-of-band Records::
1429
 
1430 362 markom

1431
File: gdb.info,  Node: GDB/MI Result Records,  Next: GDB/MI Stream Records,  Up: GDB/MI Output Records
1432
 
1433
GDB/MI Result Records
1434
---------------------
1435
 
1436
   In addition to a number of out-of-band notifications, the response
1437
to a GDB/MI command includes one of the following result indications:
1438
 
1439
`"^done" [ "," RESULTS ]'
1440
     The synchronous operation was successful, `RESULTS' is the return
1441
     value.
1442
 
1443
`"^running"'
1444
     The asynchronous operation was successfully started.  The target is
1445
     running.
1446
 
1447
`"^error" "," C-STRING'
1448
     The operation failed.  The `C-STRING' contains the corresponding
1449
     error message.
1450
 
1451

1452
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
1453
 
1454
GDB/MI Stream Records
1455
---------------------
1456
 
1457
   GDB internally maintains a number of output streams: the console, the
1458
target, and the log.  The output intended for each of these streams is
1459
funneled through the GDB/MI interface using "stream records".
1460
 
1461
   Each stream record begins with a unique "prefix character" which
1462
identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
1463
Syntax.). In addition to the prefix, each stream record contains a
1464
`STRING-OUTPUT'.  This is either raw text (with an implicit new line)
1465
or a quoted C string (which does not contain an implicit newline).
1466
 
1467
`"~" STRING-OUTPUT'
1468
     The console output stream contains text that should be displayed
1469
     in the CLI console window.  It contains the textual responses to
1470
     CLI commands.
1471
 
1472
`"@" STRING-OUTPUT'
1473
     The target output stream contains any textual output from the
1474
     running target.
1475
 
1476
`"&" STRING-OUTPUT'
1477
     The LOG stream contains debugging messages being produced by GDB's
1478
     internals.
1479
 
1480

1481
File: gdb.info,  Node: GDB/MI Out-of-band Records,  Prev: GDB/MI Stream Records,  Up: GDB/MI Output Records
1482
 
1483
GDB/MI Out-of-band Records
1484
--------------------------
1485
 
1486
   "Out-of-band" records are used to notify the GDB/MI client of
1487
additional changes that have occurred.  Those changes can either be a
1488
consequence of GDB/MI (e.g., a breakpoint modified) or a result of
1489
target activity (e.g., target stopped).
1490
 
1491
   The following is a preliminary list of possible out-of-band records.
1492
 
1493
`"*" "stop"'

powered by: WebSVN 2.1.0

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