1 This is gdb.info, produced by makeinfo version 4.6 from ./gdb.texinfo.
3 INFO-DIR-SECTION Software development
5 * Gdb: (gdb). The GNU debugger.
8 This file documents the GNU debugger GDB.
10 This is the Ninth Edition, of `Debugging with GDB: the GNU
11 Source-Level Debugger' for GDB Version 6.1.1.
13 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
15 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
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 "Free Software" and "Free Software Needs Free
21 Documentation", with the Front-Cover Texts being "A GNU Manual," and
22 with the Back-Cover Texts as in (a) below.
24 (a) The Free Software Foundation's Back-Cover Text is: "You have
25 freedom to copy and modify this GNU Manual, like GNU software. Copies
26 published by the Free Software Foundation raise funds for GNU
30 File: gdb.info, Node: M2 Constants, Next: M2 Defaults, Prev: Built-In Func/Proc, Up: Modula-2
35 GDB allows you to express the constants of Modula-2 in the following
38 * Integer constants are simply a sequence of digits. When used in an
39 expression, a constant is interpreted to be type-compatible with
40 the rest of the expression. Hexadecimal integers are specified by
41 a trailing `H', and octal integers by a trailing `B'.
43 * Floating point constants appear as a sequence of digits, followed
44 by a decimal point and another sequence of digits. An optional
45 exponent can then be specified, in the form `E[+|-]NNN', where
46 `[+|-]NNN' is the desired exponent. All of the digits of the
47 floating point constant must be valid decimal (base 10) digits.
49 * Character constants consist of a single character enclosed by a
50 pair of like quotes, either single (`'') or double (`"'). They may
51 also be expressed by their ordinal value (their ASCII value,
52 usually) followed by a `C'.
54 * String constants consist of a sequence of characters enclosed by a
55 pair of like quotes, either single (`'') or double (`"'). Escape
56 sequences in the style of C are also allowed. *Note C and C++
57 constants: C Constants, for a brief explanation of escape
60 * Enumerated constants consist of an enumerated identifier.
62 * Boolean constants consist of the identifiers `TRUE' and `FALSE'.
64 * Pointer constants consist of integral values only.
66 * Set constants are not yet supported.
69 File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Constants, Up: Modula-2
74 If type and range checking are set automatically by GDB, they both
75 default to `on' whenever the working language changes to Modula-2.
76 This happens regardless of whether you or GDB selected the working
79 If you allow GDB to set the language automatically, then entering
80 code compiled from a file whose name ends with `.mod' sets the working
81 language to Modula-2. *Note Having GDB set the language automatically:
82 Automatically, for further details.
85 File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2
87 Deviations from standard Modula-2
88 .................................
90 A few changes have been made to make Modula-2 programs easier to debug.
91 This is done primarily via loosening its type strictness:
93 * Unlike in standard Modula-2, pointer constants can be formed by
94 integers. This allows you to modify pointer variables during
95 debugging. (In standard Modula-2, the actual address contained in
96 a pointer variable is hidden from you; it can only be modified
97 through direct assignment to another pointer variable or
98 expression that returned a pointer.)
100 * C escape sequences can be used in strings and characters to
101 represent non-printable characters. GDB prints out strings with
102 these escape sequences embedded. Single non-printable characters
103 are printed using the `CHR(NNN)' format.
105 * The assignment operator (`:=') returns the value of its right-hand
108 * All built-in procedures both modify _and_ return their argument.
111 File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2
113 Modula-2 type and range checks
114 ..............................
116 _Warning:_ in this release, GDB does not yet perform type or range
119 GDB considers two Modula-2 variables type equivalent if:
121 * They are of types that have been declared equivalent via a `TYPE
124 * They have been declared on the same line. (Note: This is true of
125 the GNU Modula-2 compiler, but it may not be true of other
128 As long as type checking is enabled, any attempt to combine variables
129 whose types are not equivalent is an error.
131 Range checking is done on all mathematical operations, assignment,
132 array index bounds, and all built-in functions and procedures.
135 File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2
137 The scope operators `::' and `.'
138 ................................
140 There are a few subtle differences between the Modula-2 scope operator
141 (`.') and the GDB scope operator (`::'). The two have similar syntax:
147 where SCOPE is the name of a module or a procedure, MODULE the name of
148 a module, and ID is any declared identifier within your program, except
151 Using the `::' operator makes GDB search the scope specified by
152 SCOPE for the identifier ID. If it is not found in the specified
153 scope, then GDB searches all scopes enclosing the one specified by
156 Using the `.' operator makes GDB search the current scope for the
157 identifier specified by ID that was imported from the definition module
158 specified by MODULE. With this operator, it is an error if the
159 identifier ID was not imported from definition module MODULE, or if ID
160 is not an identifier in MODULE.
163 File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2
168 Some GDB commands have little use when debugging Modula-2 programs.
169 Five subcommands of `set print' and `show print' apply specifically to
170 C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'.
171 The first four apply to C++, and the last to the C `union' type, which
172 has no direct analogue in Modula-2.
174 The `@' operator (*note Expressions: Expressions.), while available
175 with any language, is not useful with Modula-2. Its intent is to aid
176 the debugging of "dynamic arrays", which cannot be created in Modula-2
177 as they can in C or C++. However, because an address can be specified
178 by an integral constant, the construct `{TYPE}ADREXP' is still useful.
180 In GDB scripts, the Modula-2 inequality operator `#' is interpreted
181 as the beginning of a comment. Use `<>' instead.
184 File: gdb.info, Node: Unsupported languages, Prev: Support, Up: Languages
186 Unsupported languages
187 =====================
189 In addition to the other fully-supported programming languages, GDB
190 also provides a pseudo-language, called `minimal'. It does not
191 represent a real programming language, but provides a set of
192 capabilities close to what the C or assembly languages provide. This
193 should allow most simple operations to be performed while debugging an
194 application that uses a language currently not supported by GDB.
196 If the language is set to `auto', GDB will automatically select this
197 language if the current frame corresponds to an unsupported language.
200 File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top
202 Examining the Symbol Table
203 **************************
205 The commands described in this chapter allow you to inquire about the
206 symbols (names of variables, functions and types) defined in your
207 program. This information is inherent in the text of your program and
208 does not change as your program executes. GDB finds it in your
209 program's symbol table, in the file indicated when you started GDB
210 (*note Choosing files: File Options.), or by one of the file-management
211 commands (*note Commands to specify files: Files.).
213 Occasionally, you may need to refer to symbols that contain unusual
214 characters, which GDB ordinarily treats as word delimiters. The most
215 frequent case is in referring to static variables in other source files
216 (*note Program variables: Variables.). File names are recorded in
217 object files as debugging symbols, but GDB would ordinarily parse a
218 typical file name, like `foo.c', as the three words `foo' `.' `c'. To
219 allow GDB to recognize `foo.c' as a single symbol, enclose it in single
224 looks up the value of `x' in the scope of the file `foo.c'.
226 `info address SYMBOL'
227 Describe where the data for SYMBOL is stored. For a register
228 variable, this says which register it is kept in. For a
229 non-register local variable, this prints the stack-frame offset at
230 which the variable is always stored.
232 Note the contrast with `print &SYMBOL', which does not work at all
233 for a register variable, and for a stack local variable prints the
234 exact address of the current instantiation of the variable.
237 Print the name of a symbol which is stored at the address ADDR.
238 If no symbol is stored exactly at ADDR, GDB prints the nearest
239 symbol and an offset from it:
241 (gdb) info symbol 0x54320
242 _initialize_vx + 396 in section .text
244 This is the opposite of the `info address' command. You can use
245 it to find out the name of a variable or a function given its
249 Print the data type of expression EXPR. EXPR is not actually
250 evaluated, and any side-effecting operations (such as assignments
251 or function calls) inside it do not take place. *Note
252 Expressions: Expressions.
255 Print the data type of `$', the last value in the value history.
258 Print a description of data type TYPENAME. TYPENAME may be the
259 name of a type, or for C code it may have the form `class
260 CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum
265 Print a description of the type of expression EXPR. `ptype'
266 differs from `whatis' by printing a detailed description, instead
267 of just the name of the type.
269 For example, for this variable declaration:
271 struct complex {double real; double imag;} v;
273 the two commands give this output:
276 type = struct complex
278 type = struct complex {
283 As with `whatis', using `ptype' without an argument refers to the
284 type of `$', the last value in the value history.
288 Print a brief description of all types whose names match REGEXP
289 (or all types in your program, if you supply no argument). Each
290 complete typename is matched as though it were a complete line;
291 thus, `i type value' gives information on all types in your
292 program whose names include the string `value', but `i type
293 ^value$' gives information only on types whose complete name is
296 This command differs from `ptype' in two ways: first, like
297 `whatis', it does not print a detailed description; second, it
298 lists all source files where a type is defined.
301 List all the variables local to a particular scope. This command
302 accepts a location--a function name, a source line, or an address
303 preceded by a `*', and prints all the variables local to the scope
304 defined by that location. For example:
306 (gdb) info scope command_line_handler
307 Scope for command_line_handler:
308 Symbol rl is an argument at stack/frame offset 8, length 4.
309 Symbol linebuffer is in static storage at address 0x150a18, length 4.
310 Symbol linelength is in static storage at address 0x150a1c, length 4.
311 Symbol p is a local variable in register $esi, length 4.
312 Symbol p1 is a local variable in register $ebx, length 4.
313 Symbol nline is a local variable in register $edx, length 4.
314 Symbol repeat is a local variable at frame offset -8, length 4.
316 This command is especially useful for determining what data to
317 collect during a "trace experiment", see *Note collect: Tracepoint
321 Show information about the current source file--that is, the
322 source file for the function containing the current point of
324 * the name of the source file, and the directory containing it,
326 * the directory it was compiled in,
328 * its length, in lines,
330 * which programming language it is written in,
332 * whether the executable includes debugging information for
333 that file, and if so, what format the information is in
334 (e.g., STABS, Dwarf 2, etc.), and
336 * whether the debugging information includes information about
340 Print the names of all source files in your program for which
341 there is debugging information, organized into two lists: files
342 whose symbols have already been read, and files whose symbols will
346 Print the names and data types of all defined functions.
348 `info functions REGEXP'
349 Print the names and data types of all defined functions whose
350 names contain a match for regular expression REGEXP. Thus, `info
351 fun step' finds all functions whose names include `step'; `info
352 fun ^step' finds those whose names start with `step'. If a
353 function name contains characters that conflict with the regular
354 expression language (eg. `operator*()'), they may be quoted with
358 Print the names and data types of all variables that are declared
359 outside of functions (i.e. excluding local variables).
361 `info variables REGEXP'
362 Print the names and data types of all variables (except for local
363 variables) whose names contain a match for regular expression
367 `info classes REGEXP'
368 Display all Objective-C classes in your program, or (with the
369 REGEXP argument) all those matching a particular regular
373 `info selectors REGEXP'
374 Display all Objective-C selectors in your program, or (with the
375 REGEXP argument) all those matching a particular regular
378 Some systems allow individual object files that make up your
379 program to be replaced without stopping and restarting your
380 program. For example, in VxWorks you can simply recompile a
381 defective object file and keep on running. If you are running on
382 one of these systems, you can allow GDB to reload the symbols for
383 automatically relinked modules:
385 `set symbol-reloading on'
386 Replace symbol definitions for the corresponding source file
387 when an object file with a particular name is seen again.
389 `set symbol-reloading off'
390 Do not replace symbol definitions when encountering object
391 files of the same name more than once. This is the default
392 state; if you are not running on a system that permits
393 automatic relinking of modules, you should leave
394 `symbol-reloading' off, since otherwise GDB may discard
395 symbols when linking large programs, that may contain several
396 modules (from different directories or libraries) with the
399 `show symbol-reloading'
400 Show the current `on' or `off' setting.
402 `set opaque-type-resolution on'
403 Tell GDB to resolve opaque types. An opaque type is a type
404 declared as a pointer to a `struct', `class', or `union'--for
405 example, `struct MyType *'--that is used in one source file
406 although the full declaration of `struct MyType' is in another
407 source file. The default is on.
409 A change in the setting of this subcommand will not take effect
410 until the next time symbols for a file are loaded.
412 `set opaque-type-resolution off'
413 Tell GDB not to resolve opaque types. In this case, the type is
417 `show opaque-type-resolution'
418 Show whether opaque types are resolved or not.
420 `maint print symbols FILENAME'
421 `maint print psymbols FILENAME'
422 `maint print msymbols FILENAME'
423 Write a dump of debugging symbol data into the file FILENAME.
424 These commands are used to debug the GDB symbol-reading code. Only
425 symbols with debugging data are included. If you use `maint print
426 symbols', GDB includes all the symbols for which it has already
427 collected full details: that is, FILENAME reflects symbols for
428 only those files whose symbols GDB has read. You can use the
429 command `info sources' to find out which files these are. If you
430 use `maint print psymbols' instead, the dump shows information
431 about symbols that GDB only knows partially--that is, symbols
432 defined in files that GDB has skimmed, but not yet read
433 completely. Finally, `maint print msymbols' dumps just the
434 minimal symbol information required for each object file from
435 which GDB has read some symbols. *Note Commands to specify files:
436 Files, for a discussion of how GDB reads symbols (in the
437 description of `symbol-file').
439 `maint info symtabs [ REGEXP ]'
440 `maint info psymtabs [ REGEXP ]'
441 List the `struct symtab' or `struct partial_symtab' structures
442 whose names match REGEXP. If REGEXP is not given, list them all.
443 The output includes expressions which you can copy into a GDB
444 debugging this one to examine a particular structure in more
447 (gdb) maint info psymtabs dwarf2read
448 { objfile /home/gnu/build/gdb/gdb
449 ((struct objfile *) 0x82e69d0)
450 { psymtab /home/gnu/src/gdb/dwarf2read.c
451 ((struct partial_symtab *) 0x8474b10)
454 text addresses 0x814d3c8 -- 0x8158074
455 globals (* (struct partial_symbol **) 0x8507a08 @ 9)
456 statics (* (struct partial_symbol **) 0x40e95b78 @ 2882)
460 (gdb) maint info symtabs
463 We see that there is one partial symbol table whose filename
464 contains the string `dwarf2read', belonging to the `gdb'
465 executable; and we see that GDB has not read in any symtabs yet at
466 all. If we set a breakpoint on a function, that will cause GDB to
467 read the symtab for the compilation unit containing that function:
469 (gdb) break dwarf2_psymtab_to_symtab
470 Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
472 (gdb) maint info symtabs
473 { objfile /home/gnu/build/gdb/gdb
474 ((struct objfile *) 0x82e69d0)
475 { symtab /home/gnu/src/gdb/dwarf2read.c
476 ((struct symtab *) 0x86c1f38)
479 blockvector ((struct blockvector *) 0x86c1bd0) (primary)
486 File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top
491 Once you think you have found an error in your program, you might want
492 to find out for certain whether correcting the apparent error would
493 lead to correct results in the rest of the run. You can find the
494 answer by experiment, using the GDB features for altering execution of
497 For example, you can store new values into variables or memory
498 locations, give your program a signal, restart it at a different
499 address, or even return prematurely from a function.
503 * Assignment:: Assignment to variables
504 * Jumping:: Continuing at a different address
505 * Signaling:: Giving your program a signal
506 * Returning:: Returning from a function
507 * Calling:: Calling your program's functions
508 * Patching:: Patching your program
511 File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering
513 Assignment to variables
514 =======================
516 To alter the value of a variable, evaluate an assignment expression.
517 *Note Expressions: Expressions. For example,
521 stores the value 4 into the variable `x', and then prints the value of
522 the assignment expression (which is 4). *Note Using GDB with Different
523 Languages: Languages, for more information on operators in supported
526 If you are not interested in seeing the value of the assignment, use
527 the `set' command instead of the `print' command. `set' is really the
528 same as `print' except that the expression's value is not printed and
529 is not put in the value history (*note Value history: Value History.).
530 The expression is evaluated only for its effects.
532 If the beginning of the argument string of the `set' command appears
533 identical to a `set' subcommand, use the `set variable' command instead
534 of just `set'. This command is identical to `set' except for its lack
535 of subcommands. For example, if your program has a variable `width',
536 you get an error if you try to set a new value with just `set
537 width=13', because GDB has the command `set width':
544 Invalid syntax in expression.
546 The invalid expression, of course, is `=47'. In order to actually set
547 the program's variable `width', use
549 (gdb) set var width=47
551 Because the `set' command has many subcommands that can conflict
552 with the names of program variables, it is a good idea to use the `set
553 variable' command instead of just `set'. For example, if your program
554 has a variable `g', you run into problems if you try to set a new value
555 with just `set g=4', because GDB has the command `set gnutarget',
566 The program being debugged has been started already.
567 Start it from the beginning? (y or n) y
568 Starting program: /home/smith/cc_progs/a.out
569 "/home/smith/cc_progs/a.out": can't open to read symbols:
572 The current BFD target is "=4".
574 The program variable `g' did not change, and you silently set the
575 `gnutarget' to an invalid value. In order to set the variable `g', use
579 GDB allows more implicit conversions in assignments than C; you can
580 freely store an integer value into a pointer variable or vice versa,
581 and you can convert any structure to any other structure that is the
582 same length or shorter.
584 To store values into arbitrary places in memory, use the `{...}'
585 construct to generate a value of specified type at a specified address
586 (*note Expressions: Expressions.). For example, `{int}0x83040' refers
587 to memory location `0x83040' as an integer (which implies a certain size
588 and representation in memory), and
592 stores the value 4 into that memory location.
595 File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering
597 Continuing at a different address
598 =================================
600 Ordinarily, when you continue your program, you do so at the place where
601 it stopped, with the `continue' command. You can instead continue at
602 an address of your own choosing, with the following commands:
605 Resume execution at line LINESPEC. Execution stops again
606 immediately if there is a breakpoint there. *Note Printing source
607 lines: List, for a description of the different forms of LINESPEC.
608 It is common practice to use the `tbreak' command in conjunction
609 with `jump'. *Note Setting breakpoints: Set Breaks.
611 The `jump' command does not change the current stack frame, or the
612 stack pointer, or the contents of any memory location or any
613 register other than the program counter. If line LINESPEC is in a
614 different function from the one currently executing, the results
615 may be bizarre if the two functions expect different patterns of
616 arguments or of local variables. For this reason, the `jump'
617 command requests confirmation if the specified line is not in the
618 function currently executing. However, even bizarre results are
619 predictable if you are well acquainted with the machine-language
620 code of your program.
623 Resume execution at the instruction at address ADDRESS.
625 On many systems, you can get much the same effect as the `jump'
626 command by storing a new value into the register `$pc'. The difference
627 is that this does not start your program running; it only changes the
628 address of where it _will_ run when you continue. For example,
632 makes the next `continue' command or stepping command execute at
633 address `0x485', rather than at the address where your program stopped.
634 *Note Continuing and stepping: Continuing and Stepping.
636 The most common occasion to use the `jump' command is to back
637 up--perhaps with more breakpoints set--over a portion of a program that
638 has already executed, in order to examine its execution in more detail.
641 File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering
643 Giving your program a signal
644 ============================
647 Resume execution where your program stopped, but immediately give
648 it the signal SIGNAL. SIGNAL can be the name or the number of a
649 signal. For example, on many systems `signal 2' and `signal
650 SIGINT' are both ways of sending an interrupt signal.
652 Alternatively, if SIGNAL is zero, continue execution without
653 giving a signal. This is useful when your program stopped on
654 account of a signal and would ordinary see the signal when resumed
655 with the `continue' command; `signal 0' causes it to resume
658 `signal' does not repeat when you press <RET> a second time after
659 executing the command.
661 Invoking the `signal' command is not the same as invoking the `kill'
662 utility from the shell. Sending a signal with `kill' causes GDB to
663 decide what to do with the signal depending on the signal handling
664 tables (*note Signals::). The `signal' command passes the signal
665 directly to your program.
668 File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering
670 Returning from a function
671 =========================
675 You can cancel execution of a function call with the `return'
676 command. If you give an EXPRESSION argument, its value is used as
677 the function's return value.
679 When you use `return', GDB discards the selected stack frame (and
680 all frames within it). You can think of this as making the discarded
681 frame return prematurely. If you wish to specify a value to be
682 returned, give that value as the argument to `return'.
684 This pops the selected stack frame (*note Selecting a frame:
685 Selection.), and any other frames inside of it, leaving its caller as
686 the innermost remaining frame. That frame becomes selected. The
687 specified value is stored in the registers used for returning values of
690 The `return' command does not resume execution; it leaves the
691 program stopped in the state that would exist if the function had just
692 returned. In contrast, the `finish' command (*note Continuing and
693 stepping: Continuing and Stepping.) resumes execution until the
694 selected stack frame returns naturally.
697 File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering
699 Calling program functions
700 =========================
703 Evaluate the expression EXPR without displaying `void' returned
706 You can use this variant of the `print' command if you want to
707 execute a function from your program, but without cluttering the output
708 with `void' returned values. If the result is not void, it is printed
709 and saved in the value history.
712 File: gdb.info, Node: Patching, Prev: Calling, Up: Altering
717 By default, GDB opens the file containing your program's executable
718 code (or the corefile) read-only. This prevents accidental alterations
719 to machine code; but it also prevents you from intentionally patching
720 your program's binary.
722 If you'd like to be able to patch the binary, you can specify that
723 explicitly with the `set write' command. For example, you might want
724 to turn on internal debugging flags, or even to make emergency repairs.
728 If you specify `set write on', GDB opens executable and core files
729 for both reading and writing; if you specify `set write off' (the
730 default), GDB opens them read-only.
732 If you have already loaded a file, you must load it again (using
733 the `exec-file' or `core-file' command) after changing `set
734 write', for your new setting to take effect.
737 Display whether executable files and core files are opened for
738 writing as well as reading.
741 File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top
746 GDB needs to know the file name of the program to be debugged, both in
747 order to read its symbol table and in order to start your program. To
748 debug a core dump of a previous run, you must also tell GDB the name of
753 * Files:: Commands to specify files
754 * Separate Debug Files:: Debugging information in separate files
755 * Symbol Errors:: Errors reading symbol files
758 File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files
760 Commands to specify files
761 =========================
763 You may want to specify executable and core dump file names. The usual
764 way to do this is at start-up time, using the arguments to GDB's
765 start-up commands (*note Getting In and Out of GDB: Invocation.).
767 Occasionally it is necessary to change to a different file during a
768 GDB session. Or you may run GDB and forget to specify a file you want
769 to use. In these situations the GDB commands to specify new files are
773 Use FILENAME as the program to be debugged. It is read for its
774 symbols and for the contents of pure memory. It is also the
775 program executed when you use the `run' command. If you do not
776 specify a directory and the file is not found in the GDB working
777 directory, GDB uses the environment variable `PATH' as a list of
778 directories to search, just as the shell does when looking for a
779 program to run. You can change the value of this variable, for
780 both GDB and your program, using the `path' command.
782 On systems with memory-mapped files, an auxiliary file named
783 `FILENAME.syms' may hold symbol table information for FILENAME.
784 If so, GDB maps in the symbol table from `FILENAME.syms', starting
785 up more quickly. See the descriptions of the file options
786 `-mapped' and `-readnow' (available on the command line, and with
787 the commands `file', `symbol-file', or `add-symbol-file',
788 described below), for more information.
791 `file' with no argument makes GDB discard any information it has
792 on both executable file and the symbol table.
794 `exec-file [ FILENAME ]'
795 Specify that the program to be run (but not the symbol table) is
796 found in FILENAME. GDB searches the environment variable `PATH'
797 if necessary to locate your program. Omitting FILENAME means to
798 discard information on the executable file.
800 `symbol-file [ FILENAME ]'
801 Read symbol table information from file FILENAME. `PATH' is
802 searched when necessary. Use the `file' command to get both symbol
803 table and program to run from the same file.
805 `symbol-file' with no argument clears out GDB information on your
806 program's symbol table.
808 The `symbol-file' command causes GDB to forget the contents of its
809 convenience variables, the value history, and all breakpoints and
810 auto-display expressions. This is because they may contain
811 pointers to the internal data recording symbols and data types,
812 which are part of the old symbol table data being discarded inside
815 `symbol-file' does not repeat if you press <RET> again after
818 When GDB is configured for a particular environment, it
819 understands debugging information in whatever format is the
820 standard generated for that environment; you may use either a GNU
821 compiler, or other compilers that adhere to the local conventions.
822 Best results are usually obtained from GNU compilers; for example,
823 using `gcc' you can generate debugging information for optimized
826 For most kinds of object files, with the exception of old SVR3
827 systems using COFF, the `symbol-file' command does not normally
828 read the symbol table in full right away. Instead, it scans the
829 symbol table quickly to find which source files and which symbols
830 are present. The details are read later, one source file at a
831 time, as they are needed.
833 The purpose of this two-stage reading strategy is to make GDB
834 start up faster. For the most part, it is invisible except for
835 occasional pauses while the symbol table details for a particular
836 source file are being read. (The `set verbose' command can turn
837 these pauses into messages if desired. *Note Optional warnings
838 and messages: Messages/Warnings.)
840 We have not implemented the two-stage strategy for COFF yet. When
841 the symbol table is stored in COFF format, `symbol-file' reads the
842 symbol table data in full right away. Note that "stabs-in-COFF"
843 still does the two-stage strategy, since the debug info is actually
846 `symbol-file FILENAME [ -readnow ] [ -mapped ]'
847 `file FILENAME [ -readnow ] [ -mapped ]'
848 You can override the GDB two-stage strategy for reading symbol
849 tables by using the `-readnow' option with any of the commands that
850 load symbol table information, if you want to be sure GDB has the
851 entire symbol table available.
853 If memory-mapped files are available on your system through the
854 `mmap' system call, you can use another option, `-mapped', to
855 cause GDB to write the symbols for your program into a reusable
856 file. Future GDB debugging sessions map in symbol information
857 from this auxiliary symbol file (if the program has not changed),
858 rather than spending time reading the symbol table from the
859 executable program. Using the `-mapped' option has the same
860 effect as starting GDB with the `-mapped' command-line option.
862 You can use both options together, to make sure the auxiliary
863 symbol file has all the symbol information for your program.
865 The auxiliary symbol file for a program called MYPROG is called
866 `MYPROG.syms'. Once this file exists (so long as it is newer than
867 the corresponding executable), GDB always attempts to use it when
868 you debug MYPROG; no special options or commands are needed.
870 The `.syms' file is specific to the host machine where you run
871 GDB. It holds an exact image of the internal GDB symbol table.
872 It cannot be shared across multiple host platforms.
874 `core-file [ FILENAME ]'
875 Specify the whereabouts of a core dump file to be used as the
876 "contents of memory". Traditionally, core files contain only some
877 parts of the address space of the process that generated them; GDB
878 can access the executable file itself for other parts.
880 `core-file' with no argument specifies that no core file is to be
883 Note that the core file is ignored when your program is actually
884 running under GDB. So, if you have been running your program and
885 you wish to debug a core file instead, you must kill the
886 subprocess in which the program is running. To do this, use the
887 `kill' command (*note Killing the child process: Kill Process.).
889 `add-symbol-file FILENAME ADDRESS'
890 `add-symbol-file FILENAME ADDRESS [ -readnow ] [ -mapped ]'
891 `add-symbol-file FILENAME -sSECTION ADDRESS ...'
892 The `add-symbol-file' command reads additional symbol table
893 information from the file FILENAME. You would use this command
894 when FILENAME has been dynamically loaded (by some other means)
895 into the program that is running. ADDRESS should be the memory
896 address at which the file has been loaded; GDB cannot figure this
897 out for itself. You can additionally specify an arbitrary number
898 of `-sSECTION ADDRESS' pairs, to give an explicit section name and
899 base address for that section. You can specify any ADDRESS as an
902 The symbol table of the file FILENAME is added to the symbol table
903 originally read with the `symbol-file' command. You can use the
904 `add-symbol-file' command any number of times; the new symbol data
905 thus read keeps adding to the old. To discard all old symbol data
906 instead, use the `symbol-file' command without any arguments.
908 Although FILENAME is typically a shared library file, an
909 executable file, or some other object file which has been fully
910 relocated for loading into a process, you can also load symbolic
911 information from relocatable `.o' files, as long as:
913 * the file's symbolic information refers only to linker symbols
914 defined in that file, not to symbols defined by other object
917 * every section the file's symbolic information refers to has
918 actually been loaded into the inferior, as it appears in the
921 * you can determine the address at which every section was
922 loaded, and provide these to the `add-symbol-file' command.
924 Some embedded operating systems, like Sun Chorus and VxWorks, can
925 load relocatable files into an already running program; such
926 systems typically make the requirements above easy to meet.
927 However, it's important to recognize that many native systems use
928 complex link procedures (`.linkonce' section factoring and C++
929 constructor table assembly, for example) that make the
930 requirements difficult to meet. In general, one cannot assume
931 that using `add-symbol-file' to read a relocatable object file's
932 symbolic information will have the same effect as linking the
933 relocatable object file into the program in the normal way.
935 `add-symbol-file' does not repeat if you press <RET> after using
938 You can use the `-mapped' and `-readnow' options just as with the
939 `symbol-file' command, to change how GDB manages the symbol table
940 information for FILENAME.
942 `add-shared-symbol-file'
943 The `add-shared-symbol-file' command can be used only under
944 Harris' CXUX operating system for the Motorola 88k. GDB
945 automatically looks for shared libraries, however if GDB does not
946 find yours, you can run `add-shared-symbol-file'. It takes no
950 The `section' command changes the base address of section SECTION
951 of the exec file to ADDR. This can be used if the exec file does
952 not contain section addresses, (such as in the a.out format), or
953 when the addresses specified in the file itself are wrong. Each
954 section must be changed separately. The `info files' command,
955 described below, lists all the sections and their addresses.
959 `info files' and `info target' are synonymous; both print the
960 current target (*note Specifying a Debugging Target: Targets.),
961 including the names of the executable and core dump files
962 currently in use by GDB, and the files from which symbols were
963 loaded. The command `help target' lists all possible targets
964 rather than current ones.
966 `maint info sections'
967 Another command that can give you extra information about program
968 sections is `maint info sections'. In addition to the section
969 information displayed by `info files', this command displays the
970 flags and file offset of each section in the executable and core
971 dump files. In addition, `maint info sections' provides the
972 following command options (which may be arbitrarily combined):
975 Display sections for all loaded object files, including
979 Display info only for named SECTIONS.
982 Display info only for sections for which SECTION-FLAGS are
983 true. The section flags that GDB currently knows about are:
985 Section will have space allocated in the process when
986 loaded. Set for all sections except those containing
990 Section will be loaded from the file into the child
991 process memory. Set for pre-initialized code and data,
992 clear for `.bss' sections.
995 Section needs to be relocated before loading.
998 Section cannot be modified by the child process.
1001 Section contains executable code only.
1004 Section contains data only (no executable code).
1007 Section will reside in ROM.
1010 Section contains data for constructor/destructor lists.
1013 Section is not empty.
1016 An instruction to the linker to not output the section.
1018 `COFF_SHARED_LIBRARY'
1019 A notification to the linker that the section contains
1020 COFF shared library information.
1023 Section contains common symbols.
1025 `set trust-readonly-sections on'
1026 Tell GDB that readonly sections in your object file really are
1027 read-only (i.e. that their contents will not change). In that
1028 case, GDB can fetch values from these sections out of the object
1029 file, rather than from the target program. For some targets
1030 (notably embedded ones), this can be a significant enhancement to
1031 debugging performance.
1035 `set trust-readonly-sections off'
1036 Tell GDB not to trust readonly sections. This means that the
1037 contents of the section might change while the program is running,
1038 and must therefore be fetched from the target when needed.
1040 All file-specifying commands allow both absolute and relative file
1041 names as arguments. GDB always converts the file name to an absolute
1042 file name and remembers it that way.
1044 GDB supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
1047 GDB automatically loads symbol definitions from shared libraries
1048 when you use the `run' command, or when you examine a core file.
1049 (Before you issue the `run' command, GDB does not understand references
1050 to a function in a shared library, however--unless you are debugging a
1053 On HP-UX, if the program loads a library explicitly, GDB
1054 automatically loads the symbols at the time of the `shl_load' call.
1056 There are times, however, when you may wish to not automatically load
1057 symbol definitions from shared libraries, such as when they are
1058 particularly large or there are many of them.
1060 To control the automatic loading of shared library symbols, use the
1063 `set auto-solib-add MODE'
1064 If MODE is `on', symbols from all shared object libraries will be
1065 loaded automatically when the inferior begins execution, you
1066 attach to an independently started inferior, or when the dynamic
1067 linker informs GDB that a new library has been loaded. If MODE is
1068 `off', symbols must be loaded manually, using the `sharedlibrary'
1069 command. The default value is `on'.
1071 `show auto-solib-add'
1072 Display the current autoloading mode.
1074 To explicitly load shared library symbols, use the `sharedlibrary'
1078 `info sharedlibrary'
1079 Print the names of the shared libraries which are currently loaded.
1081 `sharedlibrary REGEX'
1083 Load shared object library symbols for files matching a Unix
1084 regular expression. As with files loaded automatically, it only
1085 loads shared libraries required by your program for a core file or
1086 after typing `run'. If REGEX is omitted all shared libraries
1087 required by your program are loaded.
1089 On some systems, such as HP-UX systems, GDB supports autoloading
1090 shared library symbols until a limiting threshold size is reached.
1091 This provides the benefit of allowing autoloading to remain on by
1092 default, but avoids autoloading excessively large shared libraries, up
1093 to a threshold that is initially set, but which you can modify if you
1096 Beyond that threshold, symbols from shared libraries must be
1097 explicitly loaded. To load these symbols, use the command
1098 `sharedlibrary FILENAME'. The base address of the shared library is
1099 determined automatically by GDB and need not be specified.
1101 To display or set the threshold, use the commands:
1103 `set auto-solib-limit THRESHOLD'
1104 Set the autoloading size threshold, in an integral number of
1105 megabytes. If THRESHOLD is nonzero and shared library autoloading
1106 is enabled, symbols from all shared object libraries will be
1107 loaded until the total size of the loaded shared library symbols
1108 exceeds this threshold. Otherwise, symbols must be loaded
1109 manually, using the `sharedlibrary' command. The default
1110 threshold is 100 (i.e. 100 Mb).
1112 `show auto-solib-limit'
1113 Display the current autoloading size threshold, in megabytes.
1115 Shared libraries are also supported in many cross or remote debugging
1116 configurations. A copy of the target's libraries need to be present on
1117 the host system; they need to be the same as the target libraries,
1118 although the copies on the target can be stripped as long as the copies
1119 on the host are not.
1121 You need to tell GDB where the target libraries are, so that it can
1122 load the correct copies--otherwise, it may try to load the host's
1123 libraries. GDB has two variables to specify the search directories for
1126 `set solib-absolute-prefix PATH'
1127 If this variable is set, PATH will be used as a prefix for any
1128 absolute shared library paths; many runtime loaders store the
1129 absolute paths to the shared library in the target program's
1130 memory. If you use `solib-absolute-prefix' to find shared
1131 libraries, they need to be laid out in the same way that they are
1132 on the target, with e.g. a `/usr/lib' hierarchy under PATH.
1134 You can set the default value of `solib-absolute-prefix' by using
1135 the configure-time `--with-sysroot' option.
1137 `show solib-absolute-prefix'
1138 Display the current shared library prefix.
1140 `set solib-search-path PATH'
1141 If this variable is set, PATH is a colon-separated list of
1142 directories to search for shared libraries. `solib-search-path'
1143 is used after `solib-absolute-prefix' fails to locate the library,
1144 or if the path to the library is relative instead of absolute. If
1145 you want to use `solib-search-path' instead of
1146 `solib-absolute-prefix', be sure to set `solib-absolute-prefix' to
1147 a nonexistant directory to prevent GDB from finding your host's
1150 `show solib-search-path'
1151 Display the current shared library search path.
1154 File: gdb.info, Node: Separate Debug Files, Next: Symbol Errors, Prev: Files, Up: GDB Files
1156 Debugging Information in Separate Files
1157 =======================================
1159 GDB allows you to put a program's debugging information in a file
1160 separate from the executable itself, in a way that allows GDB to find
1161 and load the debugging information automatically. Since debugging
1162 information can be very large -- sometimes larger than the executable
1163 code itself -- some systems distribute debugging information for their
1164 executables in separate files, which users can install only when they
1165 need to debug a problem.
1167 If an executable's debugging information has been extracted to a
1168 separate file, the executable should contain a "debug link" giving the
1169 name of the debugging information file (with no directory components),
1170 and a checksum of its contents. (The exact form of a debug link is
1171 described below.) If the full name of the directory containing the
1172 executable is EXECDIR, and the executable has a debug link that
1173 specifies the name DEBUGFILE, then GDB will automatically search for
1174 the debugging information file in three places:
1176 * the directory containing the executable file (that is, it will look
1177 for a file named `EXECDIR/DEBUGFILE',
1179 * a subdirectory of that directory named `.debug' (that is, the file
1180 `EXECDIR/.debug/DEBUGFILE', and
1182 * a subdirectory of the global debug file directory that includes the
1183 executable's full path, and the name from the link (that is, the
1184 file `GLOBALDEBUGDIR/EXECDIR/DEBUGFILE', where GLOBALDEBUGDIR is
1185 the global debug file directory, and EXECDIR has been turned into
1188 GDB checks under each of these names for a debugging information file
1189 whose checksum matches that given in the link, and reads the debugging
1190 information from the first one it finds.
1192 So, for example, if you ask GDB to debug `/usr/bin/ls', which has a
1193 link containing the name `ls.debug', and the global debug directory is
1194 `/usr/lib/debug', then GDB will look for debug information in
1195 `/usr/bin/ls.debug', `/usr/bin/.debug/ls.debug', and
1196 `/usr/lib/debug/usr/bin/ls.debug'.
1198 You can set the global debugging info directory's name, and view the
1199 name GDB is currently using.
1201 `set debug-file-directory DIRECTORY'
1202 Set the directory which GDB searches for separate debugging
1203 information files to DIRECTORY.
1205 `show debug-file-directory'
1206 Show the directory GDB searches for separate debugging information
1210 A debug link is a special section of the executable file named
1211 `.gnu_debuglink'. The section must contain:
1213 * A filename, with any leading directory components removed,
1214 followed by a zero byte,
1216 * zero to three bytes of padding, as needed to reach the next
1217 four-byte boundary within the section, and
1219 * a four-byte CRC checksum, stored in the same endianness used for
1220 the executable file itself. The checksum is computed on the
1221 debugging information file's full contents by the function given
1222 below, passing zero as the CRC argument.
1224 Any executable file format can carry a debug link, as long as it can
1225 contain a section named `.gnu_debuglink' with the contents described
1228 The debugging information file itself should be an ordinary
1229 executable, containing a full set of linker symbols, sections, and
1230 debugging information. The sections of the debugging information file
1231 should have the same names, addresses and sizes as the original file,
1232 but they need not contain any data -- much like a `.bss' section in an
1233 ordinary executable.
1235 As of December 2002, there is no standard GNU utility to produce
1236 separated executable / debugging information file pairs. Ulrich
1237 Drepper's `elfutils' package, starting with version 0.53, contains a
1238 version of the `strip' command such that the command `strip foo -f
1239 foo.debug' removes the debugging information from the executable file
1240 `foo', places it in the file `foo.debug', and leaves behind a debug
1243 Since there are many different ways to compute CRC's (different
1244 polynomials, reversals, byte ordering, etc.), the simplest way to
1245 describe the CRC used in `.gnu_debuglink' sections is to give the
1246 complete code for a function that computes it:
1249 gnu_debuglink_crc32 (unsigned long crc,
1250 unsigned char *buf, size_t len)
1252 static const unsigned long crc32_table[256] =
1254 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
1255 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
1256 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
1257 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
1258 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
1259 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
1260 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
1261 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
1262 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
1263 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
1264 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
1265 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
1266 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
1267 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
1268 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
1269 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
1270 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
1271 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
1272 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
1273 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
1274 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
1275 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
1276 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
1277 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
1278 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
1279 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
1280 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
1281 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
1282 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
1283 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
1284 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
1285 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
1286 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
1287 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
1288 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
1289 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
1290 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
1291 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
1292 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
1293 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
1294 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
1295 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
1296 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
1297 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
1298 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
1299 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
1300 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
1301 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
1302 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
1303 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
1304 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
1309 crc = ~crc & 0xffffffff;
1310 for (end = buf + len; buf < end; ++buf)
1311 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
1312 return ~crc & 0xffffffff;
1316 File: gdb.info, Node: Symbol Errors, Prev: Separate Debug Files, Up: GDB Files
1318 Errors reading symbol files
1319 ===========================
1321 While reading a symbol file, GDB occasionally encounters problems, such
1322 as symbol types it does not recognize, or known bugs in compiler
1323 output. By default, GDB does not notify you of such problems, since
1324 they are relatively common and primarily of interest to people
1325 debugging compilers. If you are interested in seeing information about
1326 ill-constructed symbol tables, you can either ask GDB to print only one
1327 message about each such type of problem, no matter how many times the
1328 problem occurs; or you can ask GDB to print more messages, to see how
1329 many times the problems occur, with the `set complaints' command (*note
1330 Optional warnings and messages: Messages/Warnings.).
1332 The messages currently printed, and their meanings, include:
1334 `inner block not inside outer block in SYMBOL'
1335 The symbol information shows where symbol scopes begin and end
1336 (such as at the start of a function or a block of statements).
1337 This error indicates that an inner scope block is not fully
1338 contained in its outer scope blocks.
1340 GDB circumvents the problem by treating the inner block as if it
1341 had the same scope as the outer block. In the error message,
1342 SYMBOL may be shown as "`(don't know)'" if the outer block is not a
1345 `block at ADDRESS out of order'
1346 The symbol information for symbol scope blocks should occur in
1347 order of increasing addresses. This error indicates that it does
1350 GDB does not circumvent this problem, and has trouble locating
1351 symbols in the source file whose symbols it is reading. (You can
1352 often determine what source file is affected by specifying `set
1353 verbose on'. *Note Optional warnings and messages:
1356 `bad block start address patched'
1357 The symbol information for a symbol scope block has a start address
1358 smaller than the address of the preceding source line. This is
1359 known to occur in the SunOS 4.1.1 (and earlier) C compiler.
1361 GDB circumvents the problem by treating the symbol scope block as
1362 starting on the previous source line.
1364 `bad string table offset in symbol N'
1365 Symbol number N contains a pointer into the string table which is
1366 larger than the size of the string table.
1368 GDB circumvents the problem by considering the symbol to have the
1369 name `foo', which may cause other problems if many symbols end up
1372 `unknown symbol type `0xNN''
1373 The symbol information contains new data types that GDB does not
1374 yet know how to read. `0xNN' is the symbol type of the
1375 uncomprehended information, in hexadecimal.
1377 GDB circumvents the error by ignoring this symbol information.
1378 This usually allows you to debug your program, though certain
1379 symbols are not accessible. If you encounter such a problem and
1380 feel like debugging it, you can debug `gdb' with itself, breakpoint
1381 on `complain', then go up to the function `read_dbx_symtab' and
1382 examine `*bufp' to see the symbol.
1384 `stub type has NULL name'
1385 GDB could not find the full definition for a struct or class.
1387 `const/volatile indicator missing (ok if using g++ v1.x), got...'
1388 The symbol information for a C++ member function is missing some
1389 information that recent versions of the compiler should have
1392 `info mismatch between compiler and debugger'
1393 GDB could not parse a type specification output by the compiler.
1397 File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top
1399 Specifying a Debugging Target
1400 *****************************
1402 A "target" is the execution environment occupied by your program.
1404 Often, GDB runs in the same host environment as your program; in
1405 that case, the debugging target is specified as a side effect when you
1406 use the `file' or `core' commands. When you need more flexibility--for
1407 example, running GDB on a physically separate host, or controlling a
1408 standalone system over a serial port or a realtime system over a TCP/IP
1409 connection--you can use the `target' command to specify one of the
1410 target types configured for GDB (*note Commands for managing targets:
1415 * Active Targets:: Active targets
1416 * Target Commands:: Commands for managing targets
1417 * Byte Order:: Choosing target byte order
1418 * Remote:: Remote debugging
1419 * KOD:: Kernel Object Display
1422 File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets
1427 There are three classes of targets: processes, core files, and
1428 executable files. GDB can work concurrently on up to three active
1429 targets, one in each class. This allows you to (for example) start a
1430 process and inspect its activity without abandoning your work on a core
1433 For example, if you execute `gdb a.out', then the executable file
1434 `a.out' is the only active target. If you designate a core file as
1435 well--presumably from a prior run that crashed and coredumped--then GDB
1436 has two active targets and uses them in tandem, looking first in the
1437 corefile target, then in the executable file, to satisfy requests for
1438 memory addresses. (Typically, these two classes of target are
1439 complementary, since core files contain only a program's read-write
1440 memory--variables and so on--plus machine status, while executable
1441 files contain only the program text and initialized data.)
1443 When you type `run', your executable file becomes an active process
1444 target as well. When a process target is active, all GDB commands
1445 requesting memory addresses refer to that target; addresses in an
1446 active core file or executable file target are obscured while the
1447 process target is active.
1449 Use the `core-file' and `exec-file' commands to select a new core
1450 file or executable target (*note Commands to specify files: Files.).
1451 To specify as a target a process that is already running, use the
1452 `attach' command (*note Debugging an already-running process: Attach.).
1455 File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets
1457 Commands for managing targets
1458 =============================
1460 `target TYPE PARAMETERS'
1461 Connects the GDB host environment to a target machine or process.
1462 A target is typically a protocol for talking to debugging
1463 facilities. You use the argument TYPE to specify the type or
1464 protocol of the target machine.
1466 Further PARAMETERS are interpreted by the target protocol, but
1467 typically include things like device names or host names to connect
1468 with, process numbers, and baud rates.
1470 The `target' command does not repeat if you press <RET> again
1471 after executing the command.
1474 Displays the names of all targets available. To display targets
1475 currently selected, use either `info target' or `info files'
1476 (*note Commands to specify files: Files.).
1479 Describe a particular target, including any parameters necessary to
1482 `set gnutarget ARGS'
1483 GDB uses its own library BFD to read your files. GDB knows
1484 whether it is reading an "executable", a "core", or a ".o" file;
1485 however, you can specify the file format with the `set gnutarget'
1486 command. Unlike most `target' commands, with `gnutarget' the
1487 `target' refers to a program, not a machine.
1489 _Warning:_ To specify a file format with `set gnutarget', you
1490 must know the actual BFD name.
1492 *Note Commands to specify files: Files.
1495 Use the `show gnutarget' command to display what file format
1496 `gnutarget' is set to read. If you have not set `gnutarget', GDB
1497 will determine the file format for each file automatically, and
1498 `show gnutarget' displays `The current BDF target is "auto"'.
1500 Here are some common targets (available, or not, depending on the GDB
1503 `target exec PROGRAM'
1504 An executable file. `target exec PROGRAM' is the same as
1505 `exec-file PROGRAM'.
1507 `target core FILENAME'
1508 A core dump file. `target core FILENAME' is the same as
1509 `core-file FILENAME'.
1512 Remote serial target in GDB-specific protocol. The argument DEV
1513 specifies what serial device to use for the connection (e.g.
1514 `/dev/ttya'). *Note Remote debugging: Remote. `target remote'
1515 supports the `load' command. This is only useful if you have some
1516 other way of getting the stub to the target system, and you can put
1517 it somewhere in memory where it won't get clobbered by the
1521 Builtin CPU simulator. GDB includes simulators for most
1522 architectures. In general,
1527 works; however, you cannot assume that a specific memory map,
1528 device drivers, or even basic I/O is available, although some
1529 simulators do provide these. For info about any
1530 processor-specific simulator details, see the appropriate section
1531 in *Note Embedded Processors: Embedded Processors.
1534 Some configurations may include these targets as well:
1537 NetROM ROM emulator. This target only supports downloading.
1540 Different targets are available on different configurations of GDB;
1541 your configuration may have more or fewer targets.
1543 Many remote targets require you to download the executable's code
1544 once you've successfully established a connection.
1547 Depending on what remote debugging facilities are configured into
1548 GDB, the `load' command may be available. Where it exists, it is
1549 meant to make FILENAME (an executable) available for debugging on
1550 the remote system--by downloading, or dynamic linking, for example.
1551 `load' also records the FILENAME symbol table in GDB, like the
1552 `add-symbol-file' command.
1554 If your GDB does not have a `load' command, attempting to execute
1555 it gets the error message "`You can't do that when your target is
1558 The file is loaded at whatever address is specified in the
1559 executable. For some object file formats, you can specify the
1560 load address when you link the program; for other formats, like
1561 a.out, the object file format specifies a fixed address.
1563 `load' does not repeat if you press <RET> again after using it.
1566 File: gdb.info, Node: Byte Order, Next: Remote, Prev: Target Commands, Up: Targets
1568 Choosing target byte order
1569 ==========================
1571 Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
1572 offer the ability to run either big-endian or little-endian byte
1573 orders. Usually the executable or symbol will include a bit to
1574 designate the endian-ness, and you will not need to worry about which
1575 to use. However, you may still find it useful to adjust GDB's idea of
1576 processor endian-ness manually.
1579 Instruct GDB to assume the target is big-endian.
1582 Instruct GDB to assume the target is little-endian.
1585 Instruct GDB to use the byte order associated with the executable.
1588 Display GDB's current idea of the target byte order.
1591 Note that these commands merely adjust interpretation of symbolic
1592 data on the host, and that they have absolutely no effect on the target
1596 File: gdb.info, Node: Remote, Next: KOD, Prev: Byte Order, Up: Targets
1601 If you are trying to debug a program running on a machine that cannot
1602 run GDB in the usual way, it is often useful to use remote debugging.
1603 For example, you might use remote debugging on an operating system
1604 kernel, or on a small system which does not have a general purpose
1605 operating system powerful enough to run a full-featured debugger.
1607 Some configurations of GDB have special serial or TCP/IP interfaces
1608 to make this work with particular debugging targets. In addition, GDB
1609 comes with a generic serial protocol (specific to GDB, but not specific
1610 to any particular target system) which you can use if you write the
1611 remote stubs--the code that runs on the remote system to communicate
1614 Other remote targets may be available in your configuration of GDB;
1615 use `help target' to list them.
1618 File: gdb.info, Node: KOD, Prev: Remote, Up: Targets
1620 Kernel Object Display
1621 =====================
1623 Some targets support kernel object display. Using this facility, GDB
1624 communicates specially with the underlying operating system and can
1625 display information about operating system-level objects such as
1626 mutexes and other synchronization objects. Exactly which objects can be
1627 displayed is determined on a per-OS basis.
1629 Use the `set os' command to set the operating system. This tells
1630 GDB which kernel object display module to initialize:
1634 The associated command `show os' displays the operating system set
1635 with the `set os' command; if no operating system has been set, `show
1636 os' will display an empty string `""'.
1638 If `set os' succeeds, GDB will display some information about the
1639 operating system, and will create a new `info' command which can be
1640 used to query the target. The `info' command is named after the
1644 List of Cisco Kernel Objects
1646 any Any and all objects
1648 Further subcommands can be used to query about particular objects
1649 known by the kernel.
1651 There is currently no way to determine whether a given operating
1652 system is supported other than to try setting it with `set os NAME',
1653 where NAME is the name of the operating system you want to try.
1656 File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top
1658 Debugging remote programs
1659 *************************
1663 * Connecting:: Connecting to a remote target
1664 * Server:: Using the gdbserver program
1665 * NetWare:: Using the gdbserve.nlm program
1666 * Remote configuration:: Remote configuration
1667 * remote stub:: Implementing a remote stub
1670 File: gdb.info, Node: Connecting, Next: Server, Up: Remote Debugging
1672 Connecting to a remote target
1673 =============================
1675 On the GDB host machine, you will need an unstripped copy of your
1676 program, since GDB needs symobl and debugging information. Start up
1677 GDB as usual, using the name of the local copy of your program as the
1680 If you're using a serial line, you may want to give GDB the `--baud'
1681 option, or use the `set remotebaud' command before the `target' command.
1683 After that, use `target remote' to establish communications with the
1684 target machine. Its argument specifies how to communicate--either via
1685 a devicename attached to a direct serial line, or a TCP or UDP port
1686 (possibly to a terminal server which in turn has a serial line to the
1687 target). For example, to use a serial line connected to the device
1690 target remote /dev/ttyb
1692 To use a TCP connection, use an argument of the form `HOST:PORT' or
1693 `tcp:HOST:PORT'. For example, to connect to port 2828 on a terminal
1694 server named `manyfarms':
1696 target remote manyfarms:2828
1698 If your remote target is actually running on the same machine as
1699 your debugger session (e.g. a simulator of your target running on the
1700 same host), you can omit the hostname. For example, to connect to port
1701 1234 on your local machine:
1705 Note that the colon is still required here.
1707 To use a UDP connection, use an argument of the form
1708 `udp:HOST:PORT'. For example, to connect to UDP port 2828 on a
1709 terminal server named `manyfarms':
1711 target remote udp:manyfarms:2828
1713 When using a UDP connection for remote debugging, you should keep in
1714 mind that the `U' stands for "Unreliable". UDP can silently drop
1715 packets on busy or unreliable networks, which will cause havoc with
1716 your debugging session.
1718 Now you can use all the usual commands to examine and change data
1719 and to step and continue the remote program.
1721 Whenever GDB is waiting for the remote program, if you type the
1722 interrupt character (often <C-C>), GDB attempts to stop the program.
1723 This may or may not succeed, depending in part on the hardware and the
1724 serial drivers the remote system uses. If you type the interrupt
1725 character once again, GDB displays this prompt:
1727 Interrupted while waiting for the program.
1728 Give up (and stop debugging it)? (y or n)
1730 If you type `y', GDB abandons the remote debugging session. (If you
1731 decide you want to try again later, you can use `target remote' again
1732 to connect once more.) If you type `n', GDB goes back to waiting.
1735 When you have finished debugging the remote program, you can use
1736 the `detach' command to release it from GDB control. Detaching
1737 from the target normally resumes its execution, but the results
1738 will depend on your particular remote stub. After the `detach'
1739 command, GDB is free to connect to another target.
1742 The `disconnect' command behaves like `detach', except that the
1743 target is generally not resumed. It will wait for GDB (this
1744 instance or another one) to connect and continue debugging. After
1745 the `disconnect' command, GDB is again free to connect to another
1749 File: gdb.info, Node: Server, Next: NetWare, Prev: Connecting, Up: Remote Debugging
1751 Using the `gdbserver' program
1752 =============================
1754 `gdbserver' is a control program for Unix-like systems, which allows
1755 you to connect your program with a remote GDB via `target remote'--but
1756 without linking in the usual debugging stub.
1758 `gdbserver' is not a complete replacement for the debugging stubs,
1759 because it requires essentially the same operating-system facilities
1760 that GDB itself does. In fact, a system that can run `gdbserver' to
1761 connect to a remote GDB could also run GDB locally! `gdbserver' is
1762 sometimes useful nevertheless, because it is a much smaller program
1763 than GDB itself. It is also easier to port than all of GDB, so you may
1764 be able to get started more quickly on a new system by using
1765 `gdbserver'. Finally, if you develop code for real-time systems, you
1766 may find that the tradeoffs involved in real-time operation make it
1767 more convenient to do as much development work as possible on another
1768 system, for example by cross-compiling. You can use `gdbserver' to
1769 make a similar choice for debugging.
1771 GDB and `gdbserver' communicate via either a serial line or a TCP
1772 connection, using the standard GDB remote serial protocol.
1774 _On the target machine,_
1775 you need to have a copy of the program you want to debug.
1776 `gdbserver' does not need your program's symbol table, so you can
1777 strip the program if necessary to save space. GDB on the host
1778 system does all the symbol handling.
1780 To use the server, you must tell it how to communicate with GDB;
1781 the name of your program; and the arguments for your program. The
1784 target> gdbserver COMM PROGRAM [ ARGS ... ]
1786 COMM is either a device name (to use a serial line) or a TCP
1787 hostname and portnumber. For example, to debug Emacs with the
1788 argument `foo.txt' and communicate with GDB over the serial port
1791 target> gdbserver /dev/com1 emacs foo.txt
1793 `gdbserver' waits passively for the host GDB to communicate with
1796 To use a TCP connection instead of a serial line:
1798 target> gdbserver host:2345 emacs foo.txt
1800 The only difference from the previous example is the first
1801 argument, specifying that you are communicating with the host GDB
1802 via TCP. The `host:2345' argument means that `gdbserver' is to
1803 expect a TCP connection from machine `host' to local TCP port 2345.
1804 (Currently, the `host' part is ignored.) You can choose any number
1805 you want for the port number as long as it does not conflict with
1806 any TCP ports already in use on the target system (for example,
1807 `23' is reserved for `telnet').(1) You must use the same port
1808 number with the host GDB `target remote' command.
1810 On some targets, `gdbserver' can also attach to running programs.
1811 This is accomplished via the `--attach' argument. The syntax is:
1813 target> gdbserver COMM --attach PID
1815 PID is the process ID of a currently running process. It isn't
1816 necessary to point `gdbserver' at a binary for the running process.
1818 You can debug processes by name instead of process ID if your
1819 target has the `pidof' utility:
1821 target> gdbserver COMM --attach `pidof PROGRAM`
1823 In case more than one copy of PROGRAM is running, or PROGRAM has
1824 multiple threads, most versions of `pidof' support the `-s' option
1825 to only return the first process ID.
1827 _On the host machine,_
1828 connect to your target (*note Connecting to a remote target:
1829 Connecting.). For TCP connections, you must start up `gdbserver'
1830 prior to using the `target remote' command. Otherwise you may get
1831 an error whose text depends on the host system, but which usually
1832 looks something like `Connection refused'. You don't need to use
1833 the `load' command in GDB when using gdbserver, since the program
1834 is already on the target.
1837 ---------- Footnotes ----------
1839 (1) If you choose a port number that conflicts with another service,
1840 `gdbserver' prints an error message and exits.
1843 File: gdb.info, Node: NetWare, Next: Remote configuration, Prev: Server, Up: Remote Debugging
1845 Using the `gdbserve.nlm' program
1846 ================================
1848 `gdbserve.nlm' is a control program for NetWare systems, which allows
1849 you to connect your program with a remote GDB via `target remote'.
1851 GDB and `gdbserve.nlm' communicate via a serial line, using the
1852 standard GDB remote serial protocol.
1854 _On the target machine,_
1855 you need to have a copy of the program you want to debug.
1856 `gdbserve.nlm' does not need your program's symbol table, so you
1857 can strip the program if necessary to save space. GDB on the host
1858 system does all the symbol handling.
1860 To use the server, you must tell it how to communicate with GDB;
1861 the name of your program; and the arguments for your program. The
1864 load gdbserve [ BOARD=BOARD ] [ PORT=PORT ]
1865 [ BAUD=BAUD ] PROGRAM [ ARGS ... ]
1867 BOARD and PORT specify the serial line; BAUD specifies the baud
1868 rate used by the connection. PORT and NODE default to 0, BAUD
1869 defaults to 9600bps.
1871 For example, to debug Emacs with the argument `foo.txt'and
1872 communicate with GDB over serial port number 2 or board 1 using a
1873 19200bps connection:
1875 load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
1878 On the GDB host machine, connect to your target (*note Connecting
1879 to a remote target: Connecting.).
1883 File: gdb.info, Node: Remote configuration, Next: remote stub, Prev: NetWare, Up: Remote Debugging
1885 Remote configuration
1886 ====================
1888 The following configuration options are available when debugging remote
1891 `set remote hardware-watchpoint-limit LIMIT'
1892 `set remote hardware-breakpoint-limit LIMIT'
1893 Restrict GDB to using LIMIT remote hardware breakpoint or
1894 watchpoints. A limit of -1, the default, is treated as unlimited.
1897 File: gdb.info, Node: remote stub, Prev: Remote configuration, Up: Remote Debugging
1899 Implementing a remote stub
1900 ==========================
1902 The stub files provided with GDB implement the target side of the
1903 communication protocol, and the GDB side is implemented in the GDB
1904 source file `remote.c'. Normally, you can simply allow these
1905 subroutines to communicate, and ignore the details. (If you're
1906 implementing your own stub file, you can still ignore the details: start
1907 with one of the existing stub files. `sparc-stub.c' is the best
1908 organized, and therefore the easiest to read.)
1910 To debug a program running on another machine (the debugging
1911 "target" machine), you must first arrange for all the usual
1912 prerequisites for the program to run by itself. For example, for a C
1915 1. A startup routine to set up the C runtime environment; these
1916 usually have a name like `crt0'. The startup routine may be
1917 supplied by your hardware supplier, or you may have to write your
1920 2. A C subroutine library to support your program's subroutine calls,
1921 notably managing input and output.
1923 3. A way of getting your program to the other machine--for example, a
1924 download program. These are often supplied by the hardware
1925 manufacturer, but you may have to write your own from hardware
1928 The next step is to arrange for your program to use a serial port to
1929 communicate with the machine where GDB is running (the "host" machine).
1930 In general terms, the scheme looks like this:
1933 GDB already understands how to use this protocol; when everything
1934 else is set up, you can simply use the `target remote' command
1935 (*note Specifying a Debugging Target: Targets.).
1938 you must link with your program a few special-purpose subroutines
1939 that implement the GDB remote serial protocol. The file
1940 containing these subroutines is called a "debugging stub".
1942 On certain remote targets, you can use an auxiliary program
1943 `gdbserver' instead of linking a stub into your program. *Note
1944 Using the `gdbserver' program: Server, for details.
1946 The debugging stub is specific to the architecture of the remote
1947 machine; for example, use `sparc-stub.c' to debug programs on SPARC
1950 These working remote stubs are distributed with GDB:
1953 For Intel 386 and compatible architectures.
1956 For Motorola 680x0 architectures.
1959 For Renesas SH architectures.
1962 For SPARC architectures.
1965 For Fujitsu SPARCLITE architectures.
1968 The `README' file in the GDB distribution may list other recently
1973 * Stub Contents:: What the stub can do for you
1974 * Bootstrapping:: What you must do for the stub
1975 * Debug Session:: Putting it all together
1978 File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: remote stub
1980 What the stub can do for you
1981 ----------------------------
1983 The debugging stub for your architecture supplies these three
1987 This routine arranges for `handle_exception' to run when your
1988 program stops. You must call this subroutine explicitly near the
1989 beginning of your program.
1992 This is the central workhorse, but your program never calls it
1993 explicitly--the setup code arranges for `handle_exception' to run
1994 when a trap is triggered.
1996 `handle_exception' takes control when your program stops during
1997 execution (for example, on a breakpoint), and mediates
1998 communications with GDB on the host machine. This is where the
1999 communications protocol is implemented; `handle_exception' acts as
2000 the GDB representative on the target machine. It begins by
2001 sending summary information on the state of your program, then
2002 continues to execute, retrieving and transmitting any information
2003 GDB needs, until you execute a GDB command that makes your program
2004 resume; at that point, `handle_exception' returns control to your
2005 own code on the target machine.
2008 Use this auxiliary subroutine to make your program contain a
2009 breakpoint. Depending on the particular situation, this may be
2010 the only way for GDB to get control. For instance, if your target
2011 machine has some sort of interrupt button, you won't need to call
2012 this; pressing the interrupt button transfers control to
2013 `handle_exception'--in effect, to GDB. On some machines, simply
2014 receiving characters on the serial port may also trigger a trap;
2015 again, in that situation, you don't need to call `breakpoint' from
2016 your own program--simply running `target remote' from the host GDB
2017 session gets control.
2019 Call `breakpoint' if none of these is true, or if you simply want
2020 to make certain your program stops at a predetermined point for the
2021 start of your debugging session.
2024 File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: remote stub
2026 What you must do for the stub
2027 -----------------------------
2029 The debugging stubs that come with GDB are set up for a particular chip
2030 architecture, but they have no information about the rest of your
2031 debugging target machine.
2033 First of all you need to tell the stub how to communicate with the
2036 `int getDebugChar()'
2037 Write this subroutine to read a single character from the serial
2038 port. It may be identical to `getchar' for your target system; a
2039 different name is used to allow you to distinguish the two if you
2042 `void putDebugChar(int)'
2043 Write this subroutine to write a single character to the serial
2044 port. It may be identical to `putchar' for your target system; a
2045 different name is used to allow you to distinguish the two if you
2048 If you want GDB to be able to stop your program while it is running,
2049 you need to use an interrupt-driven serial driver, and arrange for it
2050 to stop when it receives a `^C' (`\003', the control-C character).
2051 That is the character which GDB uses to tell the remote system to stop.
2053 Getting the debugging target to return the proper status to GDB
2054 probably requires changes to the standard stub; one quick and dirty way
2055 is to just execute a breakpoint instruction (the "dirty" part is that
2056 GDB reports a `SIGTRAP' instead of a `SIGINT').
2058 Other routines you need to supply are:
2060 `void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)'
2061 Write this function to install EXCEPTION_ADDRESS in the exception
2062 handling tables. You need to do this because the stub does not
2063 have any way of knowing what the exception handling tables on your
2064 target system are like (for example, the processor's table might
2065 be in ROM, containing entries which point to a table in RAM).
2066 EXCEPTION_NUMBER is the exception number which should be changed;
2067 its meaning is architecture-dependent (for example, different
2068 numbers might represent divide by zero, misaligned access, etc).
2069 When this exception occurs, control should be transferred directly
2070 to EXCEPTION_ADDRESS, and the processor state (stack, registers,
2071 and so on) should be just as it is when a processor exception
2072 occurs. So if you want to use a jump instruction to reach
2073 EXCEPTION_ADDRESS, it should be a simple jump, not a jump to
2076 For the 386, EXCEPTION_ADDRESS should be installed as an interrupt
2077 gate so that interrupts are masked while the handler runs. The
2078 gate should be at privilege level 0 (the most privileged level).
2079 The SPARC and 68k stubs are able to mask interrupts themselves
2080 without help from `exceptionHandler'.
2082 `void flush_i_cache()'
2083 On SPARC and SPARCLITE only, write this subroutine to flush the
2084 instruction cache, if any, on your target machine. If there is no
2085 instruction cache, this subroutine may be a no-op.
2087 On target machines that have instruction caches, GDB requires this
2088 function to make certain that the state of your program is stable.
2090 You must also make sure this library routine is available:
2092 `void *memset(void *, int, int)'
2093 This is the standard library function `memset' that sets an area of
2094 memory to a known value. If you have one of the free versions of
2095 `libc.a', `memset' can be found there; otherwise, you must either
2096 obtain it from your hardware manufacturer, or write your own.
2098 If you do not use the GNU C compiler, you may need other standard
2099 library subroutines as well; this varies from one stub to another, but
2100 in general the stubs are likely to use any of the common library
2101 subroutines which `gcc' generates as inline code.
2104 File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: remote stub
2106 Putting it all together
2107 -----------------------
2109 In summary, when your program is ready to debug, you must follow these
2112 1. Make sure you have defined the supporting low-level routines
2113 (*note What you must do for the stub: Bootstrapping.):
2114 `getDebugChar', `putDebugChar',
2115 `flush_i_cache', `memset', `exceptionHandler'.
2117 2. Insert these lines near the top of your program:
2122 3. For the 680x0 stub only, you need to provide a variable called
2123 `exceptionHook'. Normally you just use:
2125 void (*exceptionHook)() = 0;
2127 but if before calling `set_debug_traps', you set it to point to a
2128 function in your program, that function is called when `GDB'
2129 continues after stopping on a trap (for example, bus error). The
2130 function indicated by `exceptionHook' is called with one
2131 parameter: an `int' which is the exception number.
2133 4. Compile and link together: your program, the GDB debugging stub for
2134 your target architecture, and the supporting subroutines.
2136 5. Make sure you have a serial connection between your target machine
2137 and the GDB host, and identify the serial port on the host.
2139 6. Download your program to your target machine (or get it there by
2140 whatever means the manufacturer provides), and start it.
2142 7. Start GDB on the host, and connect to the target (*note Connecting
2143 to a remote target: Connecting.).
2147 File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top
2149 Configuration-Specific Information
2150 **********************************
2152 While nearly all GDB commands are available for all native and cross
2153 versions of the debugger, there are some exceptions. This chapter
2154 describes things that are only available in certain configurations.
2156 There are three major categories of configurations: native
2157 configurations, where the host and target are the same, embedded
2158 operating system configurations, which are usually the same for several
2159 different processor architectures, and bare embedded processors, which
2160 are quite different from each other.
2166 * Embedded Processors::
2170 File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations
2175 This section describes details specific to particular native
2181 * SVR4 Process Information:: SVR4 process information
2182 * DJGPP Native:: Features specific to the DJGPP port
2183 * Cygwin Native:: Features specific to the Cygwin port
2186 File: gdb.info, Node: HP-UX, Next: SVR4 Process Information, Up: Native
2191 On HP-UX systems, if you refer to a function or variable name that
2192 begins with a dollar sign, GDB searches for a user or system name
2193 first, before it searches for a convenience variable.
2196 File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: HP-UX, Up: Native
2198 SVR4 process information
2199 ------------------------
2201 Many versions of SVR4 provide a facility called `/proc' that can be
2202 used to examine the image of a running process using file-system
2203 subroutines. If GDB is configured for an operating system with this
2204 facility, the command `info proc' is available to report on several
2205 kinds of information about the process running your program. `info
2206 proc' works only on SVR4 systems that include the `procfs' code. This
2207 includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not
2208 HP-UX or GNU/Linux, for example.
2211 Summarize available information about the process.
2213 `info proc mappings'
2214 Report on the address ranges accessible in the program, with
2215 information on whether your program may read, write, or execute
2219 File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native
2221 Features for Debugging DJGPP Programs
2222 -------------------------------------
2224 DJGPP is the port of GNU development tools to MS-DOS and MS-Windows.
2225 DJGPP programs are 32-bit protected-mode programs that use the "DPMI"
2226 (DOS Protected-Mode Interface) API to run on top of real-mode DOS
2227 systems and their emulations.
2229 GDB supports native debugging of DJGPP programs, and defines a few
2230 commands specific to the DJGPP port. This subsection describes those
2234 This is a prefix of DJGPP-specific commands which print
2235 information about the target system and important OS structures.
2238 This command displays assorted information about the underlying
2239 platform: the CPU type and features, the OS version and flavor, the
2240 DPMI version, and the available conventional and DPMI memory.
2245 These 3 commands display entries from, respectively, Global, Local,
2246 and Interrupt Descriptor Tables (GDT, LDT, and IDT). The
2247 descriptor tables are data structures which store a descriptor for
2248 each segment that is currently in use. The segment's selector is
2249 an index into a descriptor table; the table entry for that index
2250 holds the descriptor's base address and limit, and its attributes
2253 A typical DJGPP program uses 3 segments: a code segment, a data
2254 segment (used for both data and the stack), and a DOS segment
2255 (which allows access to DOS/BIOS data structures and absolute
2256 addresses in conventional memory). However, the DPMI host will
2257 usually define additional segments in order to support the DPMI
2260 These commands allow to display entries from the descriptor tables.
2261 Without an argument, all entries from the specified table are
2262 displayed. An argument, which should be an integer expression,
2263 means display a single entry whose index is given by the argument.
2264 For example, here's a convenient way to display information about
2265 the debugged program's data segment:
2267 `(gdb) info dos ldt $ds'
2268 `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)'
2271 This comes in handy when you want to see whether a pointer is
2272 outside the data segment's limit (i.e. "garbled").
2276 These two commands display entries from, respectively, the Page
2277 Directory and the Page Tables. Page Directories and Page Tables
2278 are data structures which control how virtual memory addresses are
2279 mapped into physical addresses. A Page Table includes an entry
2280 for every page of memory that is mapped into the program's address
2281 space; there may be several Page Tables, each one holding up to
2282 4096 entries. A Page Directory has up to 4096 entries, one each
2283 for every Page Table that is currently in use.
2285 Without an argument, `info dos pde' displays the entire Page
2286 Directory, and `info dos pte' displays all the entries in all of
2287 the Page Tables. An argument, an integer expression, given to the
2288 `info dos pde' command means display only that entry from the Page
2289 Directory table. An argument given to the `info dos pte' command
2290 means display entries from a single Page Table, the one pointed to
2291 by the specified entry in the Page Directory.
2293 These commands are useful when your program uses "DMA" (Direct
2294 Memory Access), which needs physical addresses to program the DMA
2297 These commands are supported only with some DPMI servers.
2299 `info dos address-pte ADDR'
2300 This command displays the Page Table entry for a specified linear
2301 address. The argument linear address ADDR should already have the
2302 appropriate segment's base address added to it, because this
2303 command accepts addresses which may belong to _any_ segment. For
2304 example, here's how to display the Page Table entry for the page
2305 where the variable `i' is stored:
2307 `(gdb) info dos address-pte __djgpp_base_address + (char *)&i'
2308 `Page Table entry for address 0x11a00d30:'
2309 `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30'
2312 This says that `i' is stored at offset `0xd30' from the page whose
2313 physical base address is `0x02698000', and prints all the
2314 attributes of that page.
2316 Note that you must cast the addresses of variables to a `char *',
2317 since otherwise the value of `__djgpp_base_address', the base
2318 address of all variables and functions in a DJGPP program, will be
2319 added using the rules of C pointer arithmetics: if `i' is declared
2320 an `int', GDB will add 4 times the value of `__djgpp_base_address'
2321 to the address of `i'.
2323 Here's another example, it displays the Page Table entry for the
2326 `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)'
2327 `Page Table entry for address 0x29110:'
2328 `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110'
2331 (The `+ 3' offset is because the transfer buffer's address is the
2332 3rd member of the `_go32_info_block' structure.) The output of
2333 this command clearly shows that addresses in conventional memory
2334 are mapped 1:1, i.e. the physical and linear addresses are
2337 This command is supported only with some DPMI servers.
2340 File: gdb.info, Node: Cygwin Native, Prev: DJGPP Native, Up: Native
2342 Features for Debugging MS Windows PE executables
2343 ------------------------------------------------
2345 GDB supports native debugging of MS Windows programs, including DLLs
2346 with and without symbolic debugging information. There are various
2347 additional Cygwin-specific commands, described in this subsection. The
2348 subsubsection *note Non-debug DLL symbols:: describes working with DLLs
2349 that have no debugging symbols.
2352 This is a prefix of MS Windows specific commands which print
2353 information about the target system and important OS structures.
2356 This command displays information returned by the Win32 API
2357 `GetThreadSelectorEntry' function. It takes an optional argument
2358 that is evaluated to a long value to give the information about
2359 this given selector. Without argument, this command displays
2360 information about the the six segment registers.
2363 This is a Cygwin specific alias of info shared.
2366 This command loads symbols from a dll similarly to add-sym command
2367 but without the need to specify a base address.
2369 `set new-console MODE'
2370 If MODE is `on' the debuggee will be started in a new console on
2371 next start. If MODE is `off'i, the debuggee will be started in
2372 the same console as the debugger.
2375 Displays whether a new console is used when the debuggee is
2378 `set new-group MODE'
2379 This boolean value controls whether the debuggee should start a
2380 new group or stay in the same group as the debugger. This affects
2381 the way the Windows OS handles Ctrl-C.
2384 Displays current value of new-group boolean.
2387 This boolean value adds debug output concerning events seen by the
2391 This boolean value adds debug output concerning execute events
2392 seen by the debugger.
2394 `set debugexceptions'
2395 This boolean value adds debug ouptut concerning exception events
2396 seen by the debugger.
2399 This boolean value adds debug ouptut concerning memory events seen
2403 This boolean values specifies whether the debuggee is called via a
2404 shell or directly (default value is on).
2407 Displays if the debuggee will be started with a shell.
2412 * Non-debug DLL symbols:: Support for DLLs without debugging symbols
2415 File: gdb.info, Node: Non-debug DLL symbols, Up: Cygwin Native
2417 Support for DLLs without debugging symbols
2418 ..........................................
2420 Very often on windows, some of the DLLs that your program relies on do
2421 not include symbolic debugging information (for example,
2422 `kernel32.dll'). When GDB doesn't recognize any debugging symbols in a
2423 DLL, it relies on the minimal amount of symbolic information contained
2424 in the DLL's export table. This subsubsection describes working with
2425 such symbols, known internally to GDB as "minimal symbols".
2427 Note that before the debugged program has started execution, no DLLs
2428 will have been loaded. The easiest way around this problem is simply to
2429 start the program -- either by setting a breakpoint or letting the
2430 program run once to completion. It is also possible to force GDB to
2431 load a particular DLL before starting the executable -- see the shared
2432 library information in *note Files:: or the `dll-symbols' command in
2433 *note Cygwin Native::. Currently, explicitly loading symbols from a DLL
2434 with no debugging information will cause the symbol names to be
2435 duplicated in GDB's lookup table, which may adversely affect symbol
2441 In keeping with the naming conventions used by the Microsoft debugging
2442 tools, DLL export symbols are made available with a prefix based on the
2443 DLL name, for instance `KERNEL32!CreateFileA'. The plain name is also
2444 entered into the symbol table, so `CreateFileA' is often sufficient. In
2445 some cases there will be name clashes within a program (particularly if
2446 the executable itself includes full debugging symbols) necessitating
2447 the use of the fully qualified name when referring to the contents of
2448 the DLL. Use single-quotes around the name to avoid the exclamation
2449 mark ("!") being interpreted as a language operator.
2451 Note that the internal name of the DLL may be all upper-case, even
2452 though the file name of the DLL is lower-case, or vice-versa. Since
2453 symbols within GDB are _case-sensitive_ this may cause some confusion.
2454 If in doubt, try the `info functions' and `info variables' commands or
2455 even `maint print msymbols' (see *note Symbols::). Here's an example:
2457 (gdb) info function CreateFileA
2458 All functions matching regular expression "CreateFileA":
2460 Non-debugging symbols:
2461 0x77e885f4 CreateFileA
2462 0x77e885f4 KERNEL32!CreateFileA
2464 (gdb) info function !
2465 All functions matching regular expression "!":
2467 Non-debugging symbols:
2468 0x6100114c cygwin1!__assert
2469 0x61004034 cygwin1!_dll_crt0@0
2470 0x61004240 cygwin1!dll_crt0(per_process *)
2473 Working with minimal symbols
2474 ............................
2476 Symbols extracted from a DLL's export table do not contain very much
2477 type information. All that GDB can do is guess whether a symbol refers
2478 to a function or variable depending on the linker section that contains
2479 the symbol. Also note that the actual contents of the memory contained
2480 in a DLL are not available unless the program is running. This means
2481 that you cannot examine the contents of a variable or disassemble a
2482 function within a DLL without a running program.
2484 Variables are generally treated as pointers and dereferenced
2485 automatically. For this reason, it is often necessary to prefix a
2486 variable name with the address-of operator ("&") and provide explicit
2487 type information in the command. Here's an example of the type of
2490 (gdb) print 'cygwin1!__argv'
2493 (gdb) x 'cygwin1!__argv'
2494 0x10021610: "\230y\""
2496 And two possible solutions:
2498 (gdb) print ((char **)'cygwin1!__argv')[0]
2499 $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
2501 (gdb) x/2x &'cygwin1!__argv'
2502 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000
2503 (gdb) x/x 0x10021608
2504 0x10021608: 0x0022fd98
2505 (gdb) x/s 0x0022fd98
2506 0x22fd98: "/cygdrive/c/mydirectory/myprogram"
2508 Setting a break point within a DLL is possible even before the
2509 program starts execution. However, under these circumstances, GDB can't
2510 examine the initial instructions of the function in order to skip the
2511 function's frame set-up code. You can work around this by using "*&" to
2512 set the breakpoint at a raw memory address:
2514 (gdb) break *&'python22!PyOS_Readline'
2515 Breakpoint 1 at 0x1e04eff0
2517 The author of these extensions is not entirely convinced that
2518 setting a break point within a shared DLL like `kernel32.dll' is
2522 File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations
2524 Embedded Operating Systems
2525 ==========================
2527 This section describes configurations involving the debugging of
2528 embedded operating systems that are available for several different
2533 * VxWorks:: Using GDB with VxWorks
2535 GDB includes the ability to debug programs running on various
2536 real-time operating systems.
2539 File: gdb.info, Node: VxWorks, Up: Embedded OS
2541 Using GDB with VxWorks
2542 ----------------------
2544 `target vxworks MACHINENAME'
2545 A VxWorks system, attached via TCP/IP. The argument MACHINENAME
2546 is the target system's machine name or IP address.
2549 On VxWorks, `load' links FILENAME dynamically on the current target
2550 system as well as adding its symbols in GDB.
2552 GDB enables developers to spawn and debug tasks running on networked
2553 VxWorks targets from a Unix host. Already-running tasks spawned from
2554 the VxWorks shell can also be debugged. GDB uses code that runs on
2555 both the Unix host and on the VxWorks target. The program `gdb' is
2556 installed and executed on the Unix host. (It may be installed with the
2557 name `vxgdb', to distinguish it from a GDB for debugging programs on
2560 `VxWorks-timeout ARGS'
2561 All VxWorks-based targets now support the option `vxworks-timeout'.
2562 This option is set by the user, and ARGS represents the number of
2563 seconds GDB waits for responses to rpc's. You might use this if
2564 your VxWorks target is a slow software simulator or is on the far
2565 side of a thin network line.
2567 The following information on connecting to VxWorks was current when
2568 this manual was produced; newer releases of VxWorks may use revised
2571 To use GDB with VxWorks, you must rebuild your VxWorks kernel to
2572 include the remote debugging interface routines in the VxWorks library
2573 `rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration
2574 file `configAll.h' and rebuild your VxWorks kernel. The resulting
2575 kernel contains `rdb.a', and spawns the source debugging task
2576 `tRdbTask' when VxWorks is booted. For more information on configuring
2577 and remaking VxWorks, see the manufacturer's manual.
2579 Once you have included `rdb.a' in your VxWorks system image and set
2580 your Unix execution search path to find GDB, you are ready to run GDB.
2581 From your Unix host, run `gdb' (or `vxgdb', depending on your
2584 GDB comes up showing the prompt:
2590 * VxWorks Connection:: Connecting to VxWorks
2591 * VxWorks Download:: VxWorks download
2592 * VxWorks Attach:: Running tasks
2595 File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks
2597 Connecting to VxWorks
2598 .....................
2600 The GDB command `target' lets you connect to a VxWorks target on the
2601 network. To connect to a target whose host name is "`tt'", type:
2603 (vxgdb) target vxworks tt
2605 GDB displays messages like these:
2607 Attaching remote machine across net...
2610 GDB then attempts to read the symbol tables of any object modules
2611 loaded into the VxWorks target since it was last booted. GDB locates
2612 these files by searching the directories listed in the command search
2613 path (*note Your program's environment: Environment.); if it fails to
2614 find an object file, it displays a message such as:
2616 prog.o: No such file or directory.
2618 When this happens, add the appropriate directory to the search path
2619 with the GDB command `path', and execute the `target' command again.
2622 File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks
2627 If you have connected to the VxWorks target and you want to debug an
2628 object that has not yet been loaded, you can use the GDB `load' command
2629 to download a file from Unix to VxWorks incrementally. The object file
2630 given as an argument to the `load' command is actually opened twice:
2631 first by the VxWorks target in order to download the code, then by GDB
2632 in order to read the symbol table. This can lead to problems if the
2633 current working directories on the two systems differ. If both systems
2634 have NFS mounted the same filesystems, you can avoid these problems by
2635 using absolute paths. Otherwise, it is simplest to set the working
2636 directory on both systems to the directory in which the object file
2637 resides, and then to reference the file by its name, without any path.
2638 For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in
2639 VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this
2640 program, type this on VxWorks:
2642 -> cd "VXPATH/vw/demo/rdb"
2646 (vxgdb) cd HOSTPATH/vw/demo/rdb
2649 GDB displays a response similar to this:
2651 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
2653 You can also use the `load' command to reload an object module after
2654 editing and recompiling the corresponding source file. Note that this
2655 makes GDB delete all currently-defined breakpoints, auto-displays, and
2656 convenience variables, and to clear the value history. (This is
2657 necessary in order to preserve the integrity of debugger's data
2658 structures that reference the target system's symbol table.)
2661 File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks
2666 You can also attach to an existing task using the `attach' command as
2671 where TASK is the VxWorks hexadecimal task ID. The task can be running
2672 or suspended when you attach to it. Running tasks are suspended at the
2676 File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations
2681 This section goes into details specific to particular embedded
2687 * H8/300:: Renesas H8/300
2688 * H8/500:: Renesas H8/500
2689 * M32R/D:: Renesas M32R/D
2690 * M68K:: Motorola M68K
2691 * MIPS Embedded:: MIPS Embedded
2692 * OpenRISC 1000:: OpenRisc 1000
2693 * PA:: HP PA Embedded
2696 * Sparclet:: Tsqware Sparclet
2697 * Sparclite:: Fujitsu Sparclite
2698 * ST2000:: Tandem ST2000
2699 * Z8000:: Zilog Z8000
2702 File: gdb.info, Node: ARM, Next: H8/300, Up: Embedded Processors
2708 ARM Angel monitor, via RDI library interface to ADP protocol. You
2709 may use this target to communicate with both boards running the
2710 Angel monitor, or with the EmbeddedICE JTAG debug device.
2717 File: gdb.info, Node: H8/300, Next: H8/500, Prev: ARM, Up: Embedded Processors
2723 A Renesas SH, H8/300, or H8/500 board, attached via serial line to
2724 your host. Use special commands `device' and `speed' to control
2725 the serial line and the communications speed used.
2728 E7000 emulator for Renesas H8 and SH.
2732 Renesas SH-3 and SH-3E target systems.
2735 When you select remote debugging to a Renesas SH, H8/300, or H8/500
2736 board, the `load' command downloads your program to the Renesas board
2737 and also opens it as the current executable target for GDB on your host
2738 (like the `file' command).
2740 GDB needs to know these things to talk to your Renesas SH, H8/300,
2743 1. that you want to use `target hms', the remote debugging interface
2744 for Renesas microprocessors, or `target e7000', the in-circuit
2745 emulator for the Renesas SH and the Renesas 300H. (`target hms' is
2746 the default when GDB is configured specifically for the Renesas SH,
2749 2. what serial device connects your host to your Renesas board (the
2750 first serial device available on your host is the default).
2752 3. what speed to use over the serial device.
2756 * Renesas Boards:: Connecting to Renesas boards.
2757 * Renesas ICE:: Using the E7000 In-Circuit Emulator.
2758 * Renesas Special:: Special GDB commands for Renesas micros.
2761 File: gdb.info, Node: Renesas Boards, Next: Renesas ICE, Up: H8/300
2763 Connecting to Renesas boards
2764 ............................
2766 Use the special `GDB' command `device PORT' if you need to explicitly
2767 set the serial device. The default PORT is the first available port on
2768 your host. This is only necessary on Unix hosts, where it is typically
2769 something like `/dev/ttya'.
2771 `GDB' has another special command to set the communications speed:
2772 `speed BPS'. This command also is only used from Unix hosts; on DOS
2773 hosts, set the line speed as usual from outside GDB with the DOS `mode'
2774 command (for instance, `mode com2:9600,n,8,1,p' for a 9600bps
2777 The `device' and `speed' commands are available only when you use a
2778 Unix host to debug your Renesas microprocessor programs. If you use a
2779 DOS host, GDB depends on an auxiliary terminate-and-stay-resident
2780 program called `asynctsr' to communicate with the development board
2781 through a PC serial port. You must also use the DOS `mode' command to
2782 set up the serial port on the DOS side.
2784 The following sample session illustrates the steps needed to start a
2785 program under GDB control on an H8/300. The example uses a sample
2786 H8/300 program called `t.x'. The procedure is the same for the Renesas
2789 First hook up your development board. In this example, we use a
2790 board attached to serial port `COM2'; if you use a different serial
2791 port, substitute its name in the argument of the `mode' command. When
2792 you call `asynctsr', the auxiliary comms program used by the debugger,
2793 you give it just the numeric part of the serial port's name; for
2794 example, `asyncstr 2' below runs `asyncstr' on `COM2'.
2796 C:\H8300\TEST> asynctsr 2
2797 C:\H8300\TEST> mode com2:9600,n,8,1,p
2799 Resident portion of MODE loaded
2801 COM2: 9600, n, 8, 1, p
2803 _Warning:_ We have noticed a bug in PC-NFS that conflicts with
2804 `asynctsr'. If you also run PC-NFS on your DOS host, you may need
2805 to disable it, or even boot without it, to use `asynctsr' to
2806 control your development board.
2808 Now that serial communications are set up, and the development board
2809 is connected, you can start up GDB. Call `gdb' with the name of your
2810 program as the argument. `GDB' prompts you, as usual, with the prompt
2811 `(gdb)'. Use two special commands to begin your debugging session:
2812 `target hms' to specify cross-debugging to the Renesas board, and the
2813 `load' command to download your program to the board. `load' displays
2814 the names of the program's sections, and a `*' for each 2K of data
2815 downloaded. (If you want to refresh GDB data on symbols or on the
2816 executable file without downloading, use the GDB commands `file' or
2817 `symbol-file'. These commands, and `load' itself, are described in
2818 *Note Commands to specify files: Files.)
2820 (eg-C:\H8300\TEST) gdb t.x
2821 GDB is free software and you are welcome to distribute copies
2822 of it under certain conditions; type "show copying" to see
2824 There is absolutely no warranty for GDB; type "show warranty"
2826 GDB 6.1.1, Copyright 1992 Free Software Foundation, Inc...
2828 Connected to remote H8/300 HMS system.
2830 .text : 0x8000 .. 0xabde ***********
2831 .data : 0xabde .. 0xad30 *
2832 .stack : 0xf000 .. 0xf014 *
2834 At this point, you're ready to run or debug your program. From here
2835 on, you can use all the usual GDB commands. The `break' command sets
2836 breakpoints; the `run' command starts your program; `print' or `x'
2837 display data; the `continue' command resumes execution after stopping
2838 at a breakpoint. You can use the `help' command at any time to find
2839 out more about GDB commands.
2841 Remember, however, that _operating system_ facilities aren't
2842 available on your development board; for example, if your program hangs,
2843 you can't send an interrupt--but you can press the RESET switch!
2845 Use the RESET button on the development board
2846 * to interrupt your program (don't use `ctl-C' on the DOS host--it
2847 has no way to pass an interrupt signal to the development board);
2850 * to return to the GDB command prompt after your program finishes
2851 normally. The communications protocol provides no other way for
2852 GDB to detect program completion.
2854 In either case, GDB sees the effect of a RESET on the development
2855 board as a "normal exit" of your program.
2858 File: gdb.info, Node: Renesas ICE, Next: Renesas Special, Prev: Renesas Boards, Up: H8/300
2860 Using the E7000 in-circuit emulator
2861 ...................................
2863 You can use the E7000 in-circuit emulator to develop code for either the
2864 Renesas SH or the H8/300H. Use one of these forms of the `target
2865 e7000' command to connect GDB to your E7000:
2867 `target e7000 PORT SPEED'
2868 Use this form if your E7000 is connected to a serial port. The
2869 PORT argument identifies what serial port to use (for example,
2870 `com2'). The third argument is the line speed in bits per second
2871 (for example, `9600').
2873 `target e7000 HOSTNAME'
2874 If your E7000 is installed as a host on a TCP/IP network, you can
2875 just specify its hostname; GDB uses `telnet' to connect.
2878 File: gdb.info, Node: Renesas Special, Prev: Renesas ICE, Up: H8/300
2880 Special GDB commands for Renesas micros
2881 .......................................
2883 Some GDB commands are available only for the H8/300:
2886 `set machine h8300h'
2887 Condition GDB for one of the two variants of the H8/300
2888 architecture with `set machine'. You can use `show machine' to
2889 check which variant is currently in effect.
2893 File: gdb.info, Node: H8/500, Next: M32R/D, Prev: H8/300, Up: Embedded Processors
2900 Specify which H8/500 memory model (MOD) you are using with `set
2901 memory'; check which memory model is in effect with `show memory'.
2902 The accepted values for MOD are `small', `big', `medium', and
2907 File: gdb.info, Node: M32R/D, Next: M68K, Prev: H8/500, Up: Embedded Processors
2913 Renesas M32R/D ROM monitor.
2915 `target m32rsdi DEV'
2916 Renesas M32R SDI server, connected via parallel port to the board.
2920 File: gdb.info, Node: M68K, Next: MIPS Embedded, Prev: M32R/D, Up: Embedded Processors
2925 The Motorola m68k configuration includes ColdFire support, and target
2926 command for the following ROM monitors.
2929 ABug ROM monitor for M68K.
2931 `target cpu32bug DEV'
2932 CPU32BUG monitor, running on a CPU32 (M68K) board.
2935 dBUG ROM monitor for Motorola ColdFire.
2938 EST-300 ICE monitor, running on a CPU32 (M68K) board.
2941 ROM 68K monitor, running on an M68K IDP board.
2945 ROMBUG ROM monitor for OS/9000.
2949 File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: M68K, Up: Embedded Processors
2954 GDB can use the MIPS remote debugging protocol to talk to a MIPS board
2955 attached to a serial line. This is available when you configure GDB
2956 with `--target=mips-idt-ecoff'.
2958 Use these GDB commands to specify the connection to your target
2962 To run a program on the board, start up `gdb' with the name of
2963 your program as the argument. To connect to the board, use the
2964 command `target mips PORT', where PORT is the name of the serial
2965 port connected to the board. If the program has not already been
2966 downloaded to the board, you may use the `load' command to
2967 download it. You can then use all the usual GDB commands.
2969 For example, this sequence connects to the target board through a
2970 serial port, and loads and runs a program called PROG through the
2974 GDB is free software and ...
2975 (gdb) target mips /dev/ttyb
2979 `target mips HOSTNAME:PORTNUMBER'
2980 On some GDB host configurations, you can specify a TCP connection
2981 (for instance, to a serial line managed by a terminal
2982 concentrator) instead of a serial port, using the syntax
2983 `HOSTNAME:PORTNUMBER'.
2989 NEC's DDB variant of PMON for Vr4300.
2992 LSI variant of PMON.
2995 Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
2998 Array Tech LSI33K RAID controller board.
3001 GDB also supports these special commands for MIPS targets:
3003 `set processor ARGS'
3005 Use the `set processor' command to set the type of MIPS processor
3006 when you want to access processor-type-specific registers. For
3007 example, `set processor R3041' tells GDB to use the CPU registers
3008 appropriate for the 3041 chip. Use the `show processor' command
3009 to see what MIPS processor GDB is using. Use the `info reg'
3010 command to see what registers GDB is using.
3012 `set mipsfpu double'
3013 `set mipsfpu single'
3016 If your target board does not support the MIPS floating point
3017 coprocessor, you should use the command `set mipsfpu none' (if you
3018 need this, you may wish to put the command in your GDB init file).
3019 This tells GDB how to find the return value of functions which
3020 return floating point values. It also allows GDB to avoid saving
3021 the floating point registers when calling functions on the board.
3022 If you are using a floating point coprocessor with only single
3023 precision floating point support, as on the R4650 processor, use
3024 the command `set mipsfpu single'. The default double precision
3025 floating point coprocessor may be selected using `set mipsfpu
3028 In previous versions the only choices were double precision or no
3029 floating point, so `set mipsfpu on' will select double precision
3030 and `set mipsfpu off' will select no floating point.
3032 As usual, you can inquire about the `mipsfpu' variable with `show
3037 You can see some debugging information about communications with
3038 the board by setting the `remotedebug' variable. If you set it to
3039 `1' using `set remotedebug 1', every packet is displayed. If you
3040 set it to `2', every character is displayed. You can check the
3041 current value at any time with the command `show remotedebug'.
3043 `set timeout SECONDS'
3044 `set retransmit-timeout SECONDS'
3046 `show retransmit-timeout'
3047 You can control the timeout used while waiting for a packet, in
3048 the MIPS remote protocol, with the `set timeout SECONDS' command.
3049 The default is 5 seconds. Similarly, you can control the timeout
3050 used while waiting for an acknowledgement of a packet with the `set
3051 retransmit-timeout SECONDS' command. The default is 3 seconds.
3052 You can inspect both values with `show timeout' and `show
3053 retransmit-timeout'. (These commands are _only_ available when
3054 GDB is configured for `--target=mips-idt-ecoff'.)
3056 The timeout set by `set timeout' does not apply when GDB is
3057 waiting for your program to stop. In that case, GDB waits forever
3058 because it has no way of knowing how long the program is going to
3059 run before stopping.
3062 File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors
3067 See OR1k Architecture document (`www.opencores.org') for more
3068 information about platform and commands.
3070 `target jtag jtag://HOST:PORT'
3071 Connects to remote JTAG server. JTAG remote server can be either
3072 an or1ksim or JTAG server, connected via parallel port to the
3075 Example: `target jtag jtag://localhost:9999'
3078 If connected to `or1ksim' OpenRISC 1000 Architectural Simulator,
3079 proprietary commands can be executed.
3082 Displays spr groups.
3084 `info or1k spr GROUP'
3085 `info or1k spr GROUPNO'
3086 Displays register names in selected group.
3088 `info or1k spr GROUP REGISTER'
3089 `info or1k spr REGISTER'
3090 `info or1k spr GROUPNO REGISTERNO'
3091 `info or1k spr REGISTERNO'
3092 Shows information about specified spr register.
3094 `spr GROUP REGISTER VALUE'
3095 `spr REGISTER VALUE'
3096 `spr GROUPNO REGISTERNO VALUE'
3097 `spr REGISTERNO VALUE'
3098 Writes VALUE to specified spr register.
3100 Some implementations of OpenRISC 1000 Architecture also have
3101 hardware trace. It is very similar to GDB trace, except it does not
3102 interfere with normal program execution and is thus much faster.
3103 Hardware breakpoints/watchpoint triggers can be set using:
3105 Load effective address/data
3108 Store effective address/data
3111 Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA)
3116 When triggered, it can capture low level data, like: `PC', `LSEA',
3117 `LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'.
3120 `hwatch CONDITIONAL'
3121 Set hardware watchpoint on combination of Load/Store Effecive
3122 Address(es) or Data. For example:
3124 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) &&
3127 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) &&
3131 Display information about current HW trace configuration.
3133 `htrace trigger CONDITIONAL'
3134 Set starting criteria for HW trace.
3136 `htrace qualifier CONDITIONAL'
3137 Set acquisition qualifier for HW trace.
3139 `htrace stop CONDITIONAL'
3140 Set HW trace stopping criteria.
3142 `htrace record [DATA]*'
3143 Selects the data to be recorded, when qualifier is met and HW
3144 trace was triggered.
3148 Enables/disables the HW trace.
3150 `htrace rewind [FILENAME]'
3151 Clears currently recorded trace data.
3153 If filename is specified, new trace file is made and any newly
3154 collected data will be written there.
3156 `htrace print [START [LEN]]'
3157 Prints trace buffer, using current record configuration.
3159 `htrace mode continuous'
3160 Set continuous trace mode.
3162 `htrace mode suspend'
3163 Set suspend trace mode.
3167 File: gdb.info, Node: PowerPC, Next: SH, Prev: PA, Up: Embedded Processors
3177 `target ppcbug1 DEV'
3178 PPCBUG ROM monitor for PowerPC.
3181 SDS monitor, running on a PowerPC board (such as Motorola's ADS).
3185 File: gdb.info, Node: PA, Next: PowerPC, Prev: OpenRISC 1000, Up: Embedded Processors
3191 OP50N monitor, running on an OKI HPPA board.
3194 W89K monitor, running on a Winbond HPPA board.
3198 File: gdb.info, Node: SH, Next: Sparclet, Prev: PowerPC, Up: Embedded Processors
3204 A Renesas SH board attached via serial line to your host. Use
3205 special commands `device' and `speed' to control the serial line
3206 and the communications speed used.
3209 E7000 emulator for Renesas SH.
3214 Renesas SH-3 and SH-3E target systems.
3218 File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: SH, Up: Embedded Processors
3223 GDB enables developers to debug tasks running on Sparclet targets from
3224 a Unix host. GDB uses code that runs on both the Unix host and on the
3225 Sparclet target. The program `gdb' is installed and executed on the
3228 `remotetimeout ARGS'
3229 GDB supports the option `remotetimeout'. This option is set by
3230 the user, and ARGS represents the number of seconds GDB waits for
3233 When compiling for debugging, include the options `-g' to get debug
3234 information and `-Ttext' to relocate the program to where you wish to
3235 load it on the target. You may also want to add the options `-n' or
3236 `-N' in order to reduce the size of the sections. Example:
3238 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
3240 You can use `objdump' to verify that the addresses are what you
3243 sparclet-aout-objdump --headers --syms prog
3245 Once you have set your Unix execution search path to find GDB, you
3246 are ready to run GDB. From your Unix host, run `gdb' (or
3247 `sparclet-aout-gdb', depending on your installation).
3249 GDB comes up showing the prompt:
3255 * Sparclet File:: Setting the file to debug
3256 * Sparclet Connection:: Connecting to Sparclet
3257 * Sparclet Download:: Sparclet download
3258 * Sparclet Execution:: Running and debugging
3261 File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet
3263 Setting file to debug
3264 .....................
3266 The GDB command `file' lets you choose with program to debug.
3270 GDB then attempts to read the symbol table of `prog'. GDB locates
3271 the file by searching the directories listed in the command search path.
3272 If the file was compiled with debug information (option "-g"), source
3273 files will be searched as well. GDB locates the source files by
3274 searching the directories listed in the directory search path (*note
3275 Your program's environment: Environment.). If it fails to find a file,
3276 it displays a message such as:
3278 prog: No such file or directory.
3280 When this happens, add the appropriate directories to the search
3281 paths with the GDB commands `path' and `dir', and execute the `target'
3285 File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet
3287 Connecting to Sparclet
3288 ......................
3290 The GDB command `target' lets you connect to a Sparclet target. To
3291 connect to a target on serial port "`ttya'", type:
3293 (gdbslet) target sparclet /dev/ttya
3294 Remote target sparclet connected to /dev/ttya
3295 main () at ../prog.c:3
3297 GDB displays messages like these:
3302 File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet
3307 Once connected to the Sparclet target, you can use the GDB `load'
3308 command to download the file from the host to the target. The file
3309 name and load offset should be given as arguments to the `load' command.
3310 Since the file format is aout, the program must be loaded to the
3311 starting address. You can use `objdump' to find out what this value
3312 is. The load offset is an offset which is added to the VMA (virtual
3313 memory address) of each of the file's sections. For instance, if the
3314 program `prog' was linked to text address 0x1201000, with data at
3315 0x12010160 and bss at 0x12010170, in GDB, type:
3317 (gdbslet) load prog 0x12010000
3318 Loading section .text, size 0xdb0 vma 0x12010000
3320 If the code is loaded at a different address then what the program
3321 was linked to, you may need to use the `section' and `add-symbol-file'
3322 commands to tell GDB where to map the symbol table.
3325 File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet
3327 Running and debugging
3328 .....................
3330 You can now begin debugging the task using GDB's execution control
3331 commands, `b', `step', `run', etc. See the GDB manual for the list of
3335 Breakpoint 1 at 0x12010000: file prog.c, line 3.
3337 Starting program: prog
3338 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
3341 4 char *execarg = "hello!";
3345 File: gdb.info, Node: Sparclite, Next: ST2000, Prev: Sparclet, Up: Embedded Processors
3350 `target sparclite DEV'
3351 Fujitsu sparclite boards, used only for the purpose of loading.
3352 You must use an additional command to debug the program. For
3353 example: target remote DEV using GDB standard remote protocol.
3357 File: gdb.info, Node: ST2000, Next: Z8000, Prev: Sparclite, Up: Embedded Processors
3362 GDB may be used with a Tandem ST2000 phone switch, running Tandem's
3365 To connect your ST2000 to the host system, see the manufacturer's
3366 manual. Once the ST2000 is physically attached, you can run:
3368 target st2000 DEV SPEED
3370 to establish it as your debugging environment. DEV is normally the
3371 name of a serial device, such as `/dev/ttya', connected to the ST2000
3372 via a serial line. You can instead specify DEV as a TCP connection
3373 (for example, to a serial line attached via a terminal concentrator)
3374 using the syntax `HOSTNAME:PORTNUMBER'.
3376 The `load' and `attach' commands are _not_ defined for this target;
3377 you must load your program into the ST2000 as you normally would for
3378 standalone operation. GDB reads debugging information (such as
3379 symbols) from a separate, debugging version of the program available on
3382 These auxiliary GDB commands are available to help you with the
3386 Send a COMMAND to the STDBUG monitor. See the manufacturer's
3387 manual for available commands.
3390 Connect the controlling terminal to the STDBUG command monitor.
3391 When you are done interacting with STDBUG, typing either of two
3392 character sequences gets you back to the GDB command prompt:
3393 `<RET>~.' (Return, followed by tilde and period) or `<RET>~<C-d>'
3394 (Return, followed by tilde and control-D).
3397 File: gdb.info, Node: Z8000, Prev: ST2000, Up: Embedded Processors
3402 When configured for debugging Zilog Z8000 targets, GDB includes a Z8000
3405 For the Z8000 family, `target sim' simulates either the Z8002 (the
3406 unsegmented variant of the Z8000 architecture) or the Z8001 (the
3407 segmented variant). The simulator recognizes which architecture is
3408 appropriate by inspecting the object code.
3411 Debug programs on a simulated CPU. If the simulator supports setup
3412 options, specify them via ARGS.
3414 After specifying this target, you can debug programs for the simulated
3415 CPU in the same style as programs for your host computer; use the
3416 `file' command to load a new program image, the `run' command to run
3417 your program, and so on.
3419 As well as making available all the usual machine registers (*note
3420 Registers: Registers.), the Z8000 simulator provides three additional
3421 items of information as specially named registers:
3424 Counts clock-ticks in the simulator.
3427 Counts instructions run in the simulator.
3430 Execution time in 60ths of a second.
3433 You can refer to these values in GDB expressions with the usual
3434 conventions; for example, `b fputc if $cycles>5000' sets a conditional
3435 breakpoint that suspends only after at least 5000 simulated clock ticks.
3438 File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations
3443 This section describes characteristics of architectures that affect all
3444 uses of GDB with the architecture, both native and cross.
3453 File: gdb.info, Node: A29K, Next: Alpha, Up: Architectures
3458 `set rstack_high_address ADDRESS'
3459 On AMD 29000 family processors, registers are saved in a separate
3460 "register stack". There is no way for GDB to determine the extent
3461 of this stack. Normally, GDB just assumes that the stack is
3462 "large enough". This may result in GDB referencing memory
3463 locations that do not exist. If necessary, you can get around
3464 this problem by specifying the ending address of the register
3465 stack with the `set rstack_high_address' command. The argument
3466 should be an address, which you probably want to precede with `0x'
3467 to specify in hexadecimal.
3469 `show rstack_high_address'
3470 Display the current limit of the register stack, on AMD 29000
3475 File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures
3480 See the following section.
3483 File: gdb.info, Node: MIPS, Prev: Alpha, Up: Architectures
3488 Alpha- and MIPS-based computers use an unusual stack frame, which
3489 sometimes requires GDB to search backward in the object code to find
3490 the beginning of a function.
3492 To improve response time (especially for embedded applications, where
3493 GDB may be restricted to a slow serial line for this search) you may
3494 want to limit the size of this search, using one of these commands:
3496 `set heuristic-fence-post LIMIT'
3497 Restrict GDB to examining at most LIMIT bytes in its search for
3498 the beginning of a function. A value of 0 (the default) means
3499 there is no limit. However, except for 0, the larger the limit
3500 the more bytes `heuristic-fence-post' must search and therefore
3501 the longer it takes to run.
3503 `show heuristic-fence-post'
3504 Display the current limit.
3506 These commands are available _only_ when GDB is configured for
3507 debugging programs on Alpha or MIPS processors.
3510 File: gdb.info, Node: Controlling GDB, Next: Sequences, Prev: Configurations, Up: Top
3515 You can alter the way GDB interacts with you by using the `set'
3516 command. For commands controlling how GDB displays data, see *Note
3517 Print settings: Print Settings. Other settings are described here.
3522 * Editing:: Command editing
3523 * History:: Command history
3524 * Screen Size:: Screen size
3526 * ABI:: Configuring the current ABI
3527 * Messages/Warnings:: Optional warnings and messages
3528 * Debugging Output:: Optional messages about internal happenings
3531 File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB
3536 GDB indicates its readiness to read a command by printing a string
3537 called the "prompt". This string is normally `(gdb)'. You can change
3538 the prompt string with the `set prompt' command. For instance, when
3539 debugging GDB with GDB, it is useful to change the prompt in one of the
3540 GDB sessions so that you can always tell which one you are talking to.
3542 _Note:_ `set prompt' does not add a space for you after the prompt
3543 you set. This allows you to set a prompt which ends in a space or a
3544 prompt that does not.
3546 `set prompt NEWPROMPT'
3547 Directs GDB to use NEWPROMPT as its prompt string henceforth.
3550 Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT'
3553 File: gdb.info, Node: Editing, Next: History, Prev: Prompt, Up: Controlling GDB
3558 GDB reads its input commands via the "readline" interface. This GNU
3559 library provides consistent behavior for programs which provide a
3560 command line interface to the user. Advantages are GNU Emacs-style or
3561 "vi"-style inline editing of commands, `csh'-like history substitution,
3562 and a storage and recall of command history across debugging sessions.
3564 You may control the behavior of command line editing in GDB with the
3569 Enable command line editing (enabled by default).
3572 Disable command line editing.
3575 Show whether command line editing is enabled.
3578 File: gdb.info, Node: History, Next: Screen Size, Prev: Editing, Up: Controlling GDB
3583 GDB can keep track of the commands you type during your debugging
3584 sessions, so that you can be certain of precisely what happened. Use
3585 these commands to manage the GDB command history facility.
3587 `set history filename FNAME'
3588 Set the name of the GDB command history file to FNAME. This is
3589 the file where GDB reads an initial command history list, and
3590 where it writes the command history from this session when it
3591 exits. You can access this list through history expansion or
3592 through the history command editing characters listed below. This
3593 file defaults to the value of the environment variable
3594 `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS)
3595 if this variable is not set.
3598 `set history save on'
3599 Record command history in a file, whose name may be specified with
3600 the `set history filename' command. By default, this option is
3603 `set history save off'
3604 Stop recording command history in a file.
3606 `set history size SIZE'
3607 Set the number of commands which GDB keeps in its history list.
3608 This defaults to the value of the environment variable `HISTSIZE',
3609 or to 256 if this variable is not set.
3611 History expansion assigns special meaning to the character `!'.
3613 Since `!' is also the logical not operator in C, history expansion
3614 is off by default. If you decide to enable history expansion with the
3615 `set history expansion on' command, you may sometimes need to follow
3616 `!' (when it is used as logical not, in an expression) with a space or
3617 a tab to prevent it from being expanded. The readline history
3618 facilities do not attempt substitution on the strings `!=' and `!(',
3619 even when history expansion is enabled.
3621 The commands to control history expansion are:
3623 `set history expansion on'
3624 `set history expansion'
3625 Enable history expansion. History expansion is off by default.
3627 `set history expansion off'
3628 Disable history expansion.
3630 The readline code comes with more complete documentation of
3631 editing and history expansion features. Users unfamiliar with GNU
3632 Emacs or `vi' may wish to read it.
3635 `show history filename'
3638 `show history expansion'
3639 These commands display the state of the GDB history parameters.
3640 `show history' by itself displays all four states.
3643 Display the last ten commands in the command history.
3646 Print ten commands centered on command number N.
3649 Print ten commands just after the commands last printed.
3652 File: gdb.info, Node: Screen Size, Next: Numbers, Prev: History, Up: Controlling GDB
3657 Certain commands to GDB may produce large amounts of information output
3658 to the screen. To help you read all of it, GDB pauses and asks you for
3659 input at the end of each page of output. Type <RET> when you want to
3660 continue the output, or `q' to discard the remaining output. Also, the
3661 screen width setting determines when to wrap lines of output.
3662 Depending on what is being printed, GDB tries to break the line at a
3663 readable place, rather than simply letting it overflow onto the
3666 Normally GDB knows the size of the screen from the terminal driver
3667 software. For example, on Unix GDB uses the termcap data base together
3668 with the value of the `TERM' environment variable and the `stty rows'
3669 and `stty cols' settings. If this is not correct, you can override it
3670 with the `set height' and `set width' commands:
3676 These `set' commands specify a screen height of LPP lines and a
3677 screen width of CPL characters. The associated `show' commands
3678 display the current settings.
3680 If you specify a height of zero lines, GDB does not pause during
3681 output no matter how long the output is. This is useful if output
3682 is to a file or to an editor buffer.
3684 Likewise, you can specify `set width 0' to prevent GDB from
3685 wrapping its output.
3688 File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB
3693 You can always enter numbers in octal, decimal, or hexadecimal in GDB
3694 by the usual conventions: octal numbers begin with `0', decimal numbers
3695 end with `.', and hexadecimal numbers begin with `0x'. Numbers that
3696 begin with none of these are, by default, entered in base 10; likewise,
3697 the default display for numbers--when no particular format is
3698 specified--is base 10. You can change the default base for both input
3699 and output with the `set radix' command.
3701 `set input-radix BASE'
3702 Set the default base for numeric input. Supported choices for
3703 BASE are decimal 8, 10, or 16. BASE must itself be specified
3704 either unambiguously or using the current default radix; for
3711 sets the base to decimal. On the other hand, `set radix 10'
3712 leaves the radix unchanged no matter what it was.
3714 `set output-radix BASE'
3715 Set the default base for numeric display. Supported choices for
3716 BASE are decimal 8, 10, or 16. BASE must itself be specified
3717 either unambiguously or using the current default radix.
3720 Display the current default base for numeric input.
3723 Display the current default base for numeric display.
3726 File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Controlling GDB
3728 Configuring the current ABI
3729 ===========================
3731 GDB can determine the "ABI" (Application Binary Interface) of your
3732 application automatically. However, sometimes you need to override its
3733 conclusions. Use these commands to manage GDB's view of the current
3736 One GDB configuration can debug binaries for multiple operating
3737 system targets, either via remote debugging or native emulation. GDB
3738 will autodetect the "OS ABI" (Operating System ABI) in use, but you can
3739 override its conclusion using the `set osabi' command. One example
3740 where this is useful is in debugging of binaries which use an alternate
3741 C library (e.g. UCLIBC for GNU/Linux) which does not have the same
3742 identifying marks that the standard C library for your platform
3746 Show the OS ABI currently in use.
3749 With no argument, show the list of registered available OS ABI's.
3752 Set the current OS ABI to ABI.
3754 Generally, the way that an argument of type `float' is passed to a
3755 function depends on whether the function is prototyped. For a
3756 prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed
3757 unchanged, according to the architecture's convention for `float'. For
3758 unprototyped (i.e. K&R style) functions, `float' arguments are first
3759 promoted to type `double' and then passed.
3761 Unfortunately, some forms of debug information do not reliably
3762 indicate whether a function is prototyped. If GDB calls a function
3763 that is not marked as prototyped, it consults `set
3764 coerce-float-to-double'.
3766 `set coerce-float-to-double'
3767 `set coerce-float-to-double on'
3768 Arguments of type `float' will be promoted to `double' when passed
3769 to an unprototyped function. This is the default setting.
3771 `set coerce-float-to-double off'
3772 Arguments of type `float' will be passed directly to unprototyped
3775 GDB needs to know the ABI used for your program's C++ objects. The
3776 correct C++ ABI depends on which C++ compiler was used to build your
3777 application. GDB only fully supports programs with a single C++ ABI;
3778 if your program contains code using multiple C++ ABI's or if GDB can
3779 not identify your program's ABI correctly, you can tell GDB which ABI
3780 to use. Currently supported ABI's include "gnu-v2", for `g++' versions
3781 before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for
3782 the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or
3783 "gnu-v3" ABI's as well. The default setting is "auto".
3786 Show the C++ ABI currently in use.
3789 With no argument, show the list of supported C++ ABI's.
3793 Set the current C++ ABI to ABI, or return to automatic detection.
3796 File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI, Up: Controlling GDB
3798 Optional warnings and messages
3799 ==============================
3801 By default, GDB is silent about its inner workings. If you are running
3802 on a slow machine, you may want to use the `set verbose' command. This
3803 makes GDB tell you when it does a lengthy internal operation, so you
3804 will not think it has crashed.
3806 Currently, the messages controlled by `set verbose' are those which
3807 announce that the symbol table for a source file is being read; see
3808 `symbol-file' in *Note Commands to specify files: Files.
3811 Enables GDB output of certain informational messages.
3814 Disables GDB output of certain informational messages.
3817 Displays whether `set verbose' is on or off.
3819 By default, if GDB encounters bugs in the symbol table of an object
3820 file, it is silent; but if you are debugging a compiler, you may find
3821 this information useful (*note Errors reading symbol files: Symbol
3824 `set complaints LIMIT'
3825 Permits GDB to output LIMIT complaints about each type of unusual
3826 symbols before becoming silent about the problem. Set LIMIT to
3827 zero to suppress all complaints; set it to a large number to
3828 prevent complaints from being suppressed.
3831 Displays how many symbol complaints GDB is permitted to produce.
3834 By default, GDB is cautious, and asks what sometimes seems to be a
3835 lot of stupid questions to confirm certain commands. For example, if
3836 you try to run a program which is already running:
3839 The program being debugged has been started already.
3840 Start it from the beginning? (y or n)
3842 If you are willing to unflinchingly face the consequences of your own
3843 commands, you can disable this "feature":
3846 Disables confirmation requests.
3849 Enables confirmation requests (the default).
3852 Displays state of confirmation requests.
3856 File: gdb.info, Node: Debugging Output, Prev: Messages/Warnings, Up: Controlling GDB
3858 Optional messages about internal happenings
3859 ===========================================
3862 Turns on or off display of gdbarch debugging info. The default is
3866 Displays the current state of displaying gdbarch debugging info.
3869 Turns on or off display of GDB event debugging info. The default
3873 Displays the current state of displaying GDB event debugging info.
3875 `set debug expression'
3876 Turns on or off display of GDB expression debugging info. The
3879 `show debug expression'
3880 Displays the current state of displaying GDB expression debugging
3884 Turns on or off display of GDB frame debugging info. The default
3888 Displays the current state of displaying GDB frame debugging info.
3890 `set debug overload'
3891 Turns on or off display of GDB C++ overload debugging info. This
3892 includes info such as ranking of functions, etc. The default is
3895 `show debug overload'
3896 Displays the current state of displaying GDB C++ overload
3900 Turns on or off display of reports on all packets sent back and
3901 forth across the serial line to the remote machine. The info is
3902 printed on the GDB standard output stream. The default is off.
3905 Displays the state of display of remote packets.
3908 Turns on or off display of GDB serial debugging info. The default
3912 Displays the current state of displaying GDB serial debugging info.
3915 Turns on or off display of GDB target debugging info. This info
3916 includes what is going on at the target level of GDB, as it
3917 happens. The default is off.
3920 Displays the current state of displaying GDB target debugging info.
3923 Turns on or off display of GDB variable object debugging info. The
3927 Displays the current state of displaying GDB variable object
3931 File: gdb.info, Node: Sequences, Next: TUI, Prev: Controlling GDB, Up: Top
3933 Canned Sequences of Commands
3934 ****************************
3936 Aside from breakpoint commands (*note Breakpoint command lists: Break
3937 Commands.), GDB provides two ways to store sequences of commands for
3938 execution as a unit: user-defined commands and command files.
3942 * Define:: User-defined commands
3943 * Hooks:: User-defined command hooks
3944 * Command Files:: Command files
3945 * Output:: Commands for controlled output
3948 File: gdb.info, Node: Define, Next: Hooks, Up: Sequences
3950 User-defined commands
3951 =====================
3953 A "user-defined command" is a sequence of GDB commands to which you
3954 assign a new name as a command. This is done with the `define'
3955 command. User commands may accept up to 10 arguments separated by
3956 whitespace. Arguments are accessed within the user command via
3957 $ARG0...$ARG9. A trivial example:
3960 print $arg0 + $arg1 + $arg2
3962 To execute the command use:
3966 This defines the command `adder', which prints the sum of its three
3967 arguments. Note the arguments are text substitutions, so they may
3968 reference variables, use complex expressions, or even perform inferior
3971 `define COMMANDNAME'
3972 Define a command named COMMANDNAME. If there is already a command
3973 by that name, you are asked to confirm that you want to redefine
3976 The definition of the command is made up of other GDB command
3977 lines, which are given following the `define' command. The end of
3978 these commands is marked by a line containing `end'.
3981 Takes a single argument, which is an expression to evaluate. It
3982 is followed by a series of commands that are executed only if the
3983 expression is true (nonzero). There can then optionally be a line
3984 `else', followed by a series of commands that are only executed if
3985 the expression was false. The end of the list is marked by a line
3989 The syntax is similar to `if': the command takes a single argument,
3990 which is an expression to evaluate, and must be followed by the
3991 commands to execute, one per line, terminated by an `end'. The
3992 commands are executed repeatedly as long as the expression
3995 `document COMMANDNAME'
3996 Document the user-defined command COMMANDNAME, so that it can be
3997 accessed by `help'. The command COMMANDNAME must already be
3998 defined. This command reads lines of documentation just as
3999 `define' reads the lines of the command definition, ending with
4000 `end'. After the `document' command is finished, `help' on command
4001 COMMANDNAME displays the documentation you have written.
4003 You may use the `document' command again to change the
4004 documentation of a command. Redefining the command with `define'
4005 does not change the documentation.
4008 List all user-defined commands, with the first line of the
4009 documentation (if any) for each.
4012 `show user COMMANDNAME'
4013 Display the GDB commands used to define COMMANDNAME (but not its
4014 documentation). If no COMMANDNAME is given, display the
4015 definitions for all user-defined commands.
4017 `show max-user-call-depth'
4018 `set max-user-call-depth'
4019 The value of `max-user-call-depth' controls how many recursion
4020 levels are allowed in user-defined commands before GDB suspects an
4021 infinite recursion and aborts the command.
4024 When user-defined commands are executed, the commands of the
4025 definition are not printed. An error in any command stops execution of
4026 the user-defined command.
4028 If used interactively, commands that would ask for confirmation
4029 proceed without asking when used inside a user-defined command. Many
4030 GDB commands that normally print messages to say what they are doing
4031 omit the messages when used in a user-defined command.
4034 File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences
4036 User-defined command hooks
4037 ==========================
4039 You may define "hooks", which are a special kind of user-defined
4040 command. Whenever you run the command `foo', if the user-defined
4041 command `hook-foo' exists, it is executed (with no arguments) before
4044 A hook may also be defined which is run after the command you
4045 executed. Whenever you run the command `foo', if the user-defined
4046 command `hookpost-foo' exists, it is executed (with no arguments) after
4047 that command. Post-execution hooks may exist simultaneously with
4048 pre-execution hooks, for the same command.
4050 It is valid for a hook to call the command which it hooks. If this
4051 occurs, the hook is not re-executed, thereby avoiding infinte recursion.
4053 In addition, a pseudo-command, `stop' exists. Defining
4054 (`hook-stop') makes the associated commands execute every time
4055 execution stops in your program: before breakpoint commands are run,
4056 displays are printed, or the stack frame is printed.
4058 For example, to ignore `SIGALRM' signals while single-stepping, but
4059 treat them normally during normal execution, you could define:
4062 handle SIGALRM nopass
4069 define hook-continue
4073 As a further example, to hook at the begining and end of the `echo'
4074 command, and to add extra text to the beginning and end of the message,
4081 define hookpost-echo
4085 (gdb) echo Hello World
4086 <<<---Hello World--->>>
4089 You can define a hook for any single-word command in GDB, but not
4090 for command aliases; you should define a hook for the basic command
4091 name, e.g. `backtrace' rather than `bt'. If an error occurs during
4092 the execution of your hook, execution of GDB commands stops and GDB
4093 issues a prompt (before the command that you actually typed had a
4096 If you try to define a hook which does not match any known command,
4097 you get a warning from the `define' command.
4100 File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences
4105 A command file for GDB is a file of lines that are GDB commands.
4106 Comments (lines starting with `#') may also be included. An empty line
4107 in a command file does nothing; it does not mean to repeat the last
4108 command, as it would from the terminal.
4110 When you start GDB, it automatically executes commands from its
4111 "init files", normally called `.gdbinit'(1). During startup, GDB does
4114 1. Reads the init file (if any) in your home directory(2).
4116 2. Processes command line options and operands.
4118 3. Reads the init file (if any) in the current working directory.
4120 4. Reads command files specified by the `-x' option.
4122 The init file in your home directory can set options (such as `set
4123 complaints') that affect subsequent processing of command line options
4124 and operands. Init files are not executed if you use the `-nx' option
4125 (*note Choosing modes: Mode Options.).
4127 On some configurations of GDB, the init file is known by a different
4128 name (these are typically environments where a specialized form of GDB
4129 may need to coexist with other forms, hence a different name for the
4130 specialized version's init file). These are the environments with
4131 special init file names:
4133 * VxWorks (Wind River Systems real-time OS): `.vxgdbinit'
4135 * OS68K (Enea Data Systems real-time OS): `.os68gdbinit'
4137 * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit'
4139 You can also request the execution of a command file with the
4143 Execute the command file FILENAME.
4145 The lines in a command file are executed sequentially. They are not
4146 printed as they are executed. An error in any command terminates
4147 execution of the command file and control is returned to the console.
4149 Commands that would ask for confirmation if used interactively
4150 proceed without asking when used in a command file. Many GDB commands
4151 that normally print messages to say what they are doing omit the
4152 messages when called from command files.
4154 GDB also accepts command input from standard input. In this mode,
4155 normal output goes to standard output and error output goes to standard
4156 error. Errors in a command file supplied on standard input do not
4157 terminate execution of the command file -- execution continues with the
4160 gdb < cmds > log 2>&1
4162 (The syntax above will vary depending on the shell used.) This
4163 example will execute commands from the file `cmds'. All output and
4164 errors would be directed to `log'.
4166 ---------- Footnotes ----------
4168 (1) The DJGPP port of GDB uses the name `gdb.ini' instead, due to the
4169 limitations of file names imposed by DOS filesystems.
4171 (2) On DOS/Windows systems, the home directory is the one pointed to
4172 by the `HOME' environment variable.
4175 File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences
4177 Commands for controlled output
4178 ==============================
4180 During the execution of a command file or a user-defined command, normal
4181 GDB output is suppressed; the only output that appears is what is
4182 explicitly printed by the commands in the definition. This section
4183 describes three commands useful for generating exactly the output you
4187 Print TEXT. Nonprinting characters can be included in TEXT using
4188 C escape sequences, such as `\n' to print a newline. *No newline
4189 is printed unless you specify one.* In addition to the standard C
4190 escape sequences, a backslash followed by a space stands for a
4191 space. This is useful for displaying a string with spaces at the
4192 beginning or the end, since leading and trailing spaces are
4193 otherwise trimmed from all arguments. To print ` and foo = ', use
4194 the command `echo \ and foo = \ '.
4196 A backslash at the end of TEXT can be used, as in C, to continue
4197 the command onto subsequent lines. For example,
4199 echo This is some text\n\
4200 which is continued\n\
4201 onto several lines.\n
4203 produces the same output as
4205 echo This is some text\n
4206 echo which is continued\n
4207 echo onto several lines.\n
4210 Print the value of EXPRESSION and nothing but that value: no
4211 newlines, no `$NN = '. The value is not entered in the value
4212 history either. *Note Expressions: Expressions, for more
4213 information on expressions.
4215 `output/FMT EXPRESSION'
4216 Print the value of EXPRESSION in format FMT. You can use the same
4217 formats as for `print'. *Note Output formats: Output Formats, for
4220 `printf STRING, EXPRESSIONS...'
4221 Print the values of the EXPRESSIONS under the control of STRING.
4222 The EXPRESSIONS are separated by commas and may be either numbers
4223 or pointers. Their values are printed as specified by STRING,
4224 exactly as if your program were to execute the C subroutine
4226 printf (STRING, EXPRESSIONS...);
4228 For example, you can print two values in hex like this:
4230 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
4232 The only backslash-escape sequences that you can use in the format
4233 string are the simple ones that consist of backslash followed by a
4237 File: gdb.info, Node: Interpreters, Next: Emacs, Prev: TUI, Up: Top
4239 Command Interpreters
4240 ********************
4242 GDB supports multiple command interpreters, and some command
4243 infrastructure to allow users or user interface writers to switch
4244 between interpreters or run commands in other interpreters.
4246 GDB currently supports two command interpreters, the console
4247 interpreter (sometimes called the command-line interpreter or CLI) and
4248 the machine interface interpreter (or GDB/MI). This manual describes
4249 both of these interfaces in great detail.
4251 By default, GDB will start with the console interpreter. However,
4252 the user may choose to start GDB with another interpreter by specifying
4253 the `-i' or `--interpreter' startup options. Defined interpreters
4257 The traditional console or command-line interpreter. This is the
4258 most often used interpreter with GDB. With no interpreter
4259 specified at runtime, GDB will use this interpreter.
4262 The newest GDB/MI interface (currently `mi2'). Used primarily by
4263 programs wishing to use GDB as a backend for a debugger GUI or an
4264 IDE. For more information, see *Note The GDB/MI Interface: GDB/MI.
4267 The current GDB/MI interface.
4270 The GDB/MI interface included in GDB 5.1, 5.2, and 5.3.
4273 The interpreter being used by GDB may not be dynamically switched at
4274 runtime. Although possible, this could lead to a very precarious
4275 situation. Consider an IDE using GDB/MI. If a user enters the command
4276 "interpreter-set console" in a console view, GDB would switch to using
4277 the console interpreter, rendering the IDE inoperable!
4279 Although you may only choose a single interpreter at startup, you
4280 may execute commands in any interpreter from the current interpreter
4281 using the appropriate command. If you are running the console
4282 interpreter, simply use the `interpreter-exec' command:
4284 interpreter-exec mi "-data-list-register-names"
4286 GDB/MI has a similar command, although it is only available in
4287 versions of GDB which support GDB/MI version 2 (or greater).
4290 File: gdb.info, Node: TUI, Next: Interpreters, Prev: Sequences, Up: Top
4292 GDB Text User Interface
4293 ***********************
4297 * TUI Overview:: TUI overview
4298 * TUI Keys:: TUI key bindings
4299 * TUI Single Key Mode:: TUI single key mode
4300 * TUI Commands:: TUI specific commands
4301 * TUI Configuration:: TUI configuration variables
4303 The GDB Text User Interface, TUI in short, is a terminal interface
4304 which uses the `curses' library to show the source file, the assembly
4305 output, the program registers and GDB commands in separate text windows.
4307 The TUI is enabled by invoking GDB using either `gdbtui' or `gdb
4311 File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI
4316 The TUI has two display modes that can be switched while GDB runs:
4318 * A curses (or TUI) mode in which it displays several text windows
4321 * A standard mode which corresponds to the GDB configured without
4324 In the TUI mode, GDB can display several text window on the terminal:
4327 This window is the GDB command window with the GDB prompt and the
4328 GDB outputs. The GDB input is still managed using readline but
4329 through the TUI. The _command_ window is always visible.
4332 The source window shows the source file of the program. The
4333 current line as well as active breakpoints are displayed in this
4337 The assembly window shows the disassembly output of the program.
4340 This window shows the processor registers. It detects when a
4341 register is changed and when this is the case, registers that have
4342 changed are highlighted.
4345 The source and assembly windows show the current program position by
4346 highlighting the current line and marking them with the `>' marker.
4347 Breakpoints are also indicated with two markers. A first one indicates
4348 the breakpoint type:
4351 Breakpoint which was hit at least once.
4354 Breakpoint which was never hit.
4357 Hardware breakpoint which was hit at least once.
4360 Hardware breakpoint which was never hit.
4363 The second marker indicates whether the breakpoint is enabled or not:
4366 Breakpoint is enabled.
4369 Breakpoint is disabled.
4372 The source, assembly and register windows are attached to the thread
4373 and the frame position. They are updated when the current thread
4374 changes, when the frame changes or when the program counter changes.
4375 These three windows are arranged by the TUI according to several
4376 layouts. The layout defines which of these three windows are visible.
4377 The following layouts are available:
4383 * source and assembly
4385 * source and registers
4387 * assembly and registers
4390 On top of the command window a status line gives various information
4391 concerning the current process begin debugged. The status line is
4392 updated when the information it shows changes. The following fields
4396 Indicates the current gdb target (*note Specifying a Debugging
4400 Gives information about the current process or thread number.
4401 When no process is being debugged, this field is set to `No
4405 Gives the current function name for the selected frame. The name
4406 is demangled if demangling is turned on (*note Print Settings::).
4407 When there is no symbol corresponding to the current program
4408 counter the string `??' is displayed.
4411 Indicates the current line number for the selected frame. When
4412 the current line number is not known the string `??' is displayed.
4415 Indicates the current program counter address.
4419 File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI
4424 The TUI installs several key bindings in the readline keymaps (*note
4425 Command Line Editing::). They allow to leave or enter in the TUI mode
4426 or they operate directly on the TUI layout and windows. The TUI also
4427 provides a _SingleKey_ keymap which binds several keys directly to GDB
4428 commands. The following key bindings are installed for both TUI mode
4429 and the GDB standard mode.
4434 Enter or leave the TUI mode. When the TUI mode is left, the
4435 curses window management is left and GDB operates using its
4436 standard mode writing on the terminal directly. When the TUI mode
4437 is entered, the control is given back to the curses windows. The
4438 screen is then refreshed.
4441 Use a TUI layout with only one window. The layout will either be
4442 `source' or `assembly'. When the TUI mode is not active, it will
4443 switch to the TUI mode.
4445 Think of this key binding as the Emacs `C-x 1' binding.
4448 Use a TUI layout with at least two windows. When the current
4449 layout shows already two windows, a next layout with two windows
4450 is used. When a new layout is chosen, one window will always be
4451 common to the previous layout and the new one.
4453 Think of it as the Emacs `C-x 2' binding.
4456 Change the active window. The TUI associates several key bindings
4457 (like scrolling and arrow keys) to the active window. This command
4458 gives the focus to the next TUI window.
4460 Think of it as the Emacs `C-x o' binding.
4463 Use the TUI _SingleKey_ keymap that binds single key to gdb
4464 commands (*note TUI Single Key Mode::).
4467 The following key bindings are handled only by the TUI mode:
4470 Scroll the active window one page up.
4473 Scroll the active window one page down.
4476 Scroll the active window one line up.
4479 Scroll the active window one line down.
4482 Scroll the active window one column left.
4485 Scroll the active window one column right.
4491 In the TUI mode, the arrow keys are used by the active window for
4492 scrolling. This means they are available for readline when the active
4493 window is the command window. When the command window does not have
4494 the focus, it is necessary to use other readline key bindings such as
4495 <C-p>, <C-n>, <C-b> and <C-f>.
4498 File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI
4503 The TUI provides a _SingleKey_ mode in which it installs a particular
4504 key binding in the readline keymaps to connect single keys to some gdb
4520 exit the _SingleKey_ mode.
4538 Other keys temporarily switch to the GDB command prompt. The key
4539 that was pressed is inserted in the editing buffer so that it is
4540 possible to type most GDB commands without interaction with the TUI
4541 _SingleKey_ mode. Once the command is entered the TUI _SingleKey_ mode
4542 is restored. The only way to permanently leave this mode is by hitting
4546 File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI
4548 TUI specific commands
4549 =====================
4551 The TUI has specific commands to control the text windows. These
4552 commands are always available, that is they do not depend on the
4553 current terminal mode in which GDB runs. When GDB is in the standard
4554 mode, using these commands will automatically switch in the TUI mode.
4557 List and give the size of all displayed windows.
4560 Display the next layout.
4563 Display the previous layout.
4566 Display the source window only.
4569 Display the assembly window only.
4572 Display the source and assembly window.
4575 Display the register window together with the source or assembly
4578 `focus next | prev | src | asm | regs | split'
4579 Set the focus to the named window. This command allows to change
4580 the active window so that scrolling keys can be affected to
4584 Refresh the screen. This is similar to using <C-L> key.
4587 Show the floating point registers in the register window.
4590 Show the general registers in the register window.
4593 Show the next register group. The list of register groups as well
4594 as their order is target specific. The predefined register groups
4595 are the following: `general', `float', `system', `vector', `all',
4599 Show the system registers in the register window.
4602 Update the source window and the current execution point.
4604 `winheight NAME +COUNT'
4605 `winheight NAME -COUNT'
4606 Change the height of the window NAME by COUNT lines. Positive
4607 counts increase the height, while negative counts decrease it.
4611 File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI
4613 TUI configuration variables
4614 ===========================
4616 The TUI has several configuration variables that control the appearance
4617 of windows on the terminal.
4619 `set tui border-kind KIND'
4620 Select the border appearance for the source, assembly and register
4621 windows. The possible values are the following:
4623 Use a space character to draw the border.
4626 Use ascii characters + - and | to draw the border.
4629 Use the Alternate Character Set to draw the border. The
4630 border is drawn using character line graphics if the terminal
4634 `set tui active-border-mode MODE'
4635 Select the attributes to display the border of the active window.
4636 The possible values are `normal', `standout', `reverse', `half',
4637 `half-standout', `bold' and `bold-standout'.
4639 `set tui border-mode MODE'
4640 Select the attributes to display the border of other windows. The
4641 MODE can be one of the following:
4643 Use normal attributes to display the border.
4649 Use reverse video mode.
4652 Use half bright mode.
4655 Use half bright and standout mode.
4658 Use extra bright or bold mode.
4661 Use extra bright or bold and standout mode.
4666 File: gdb.info, Node: Emacs, Next: Annotations, Prev: Interpreters, Up: Top
4668 Using GDB under GNU Emacs
4669 *************************
4671 A special interface allows you to use GNU Emacs to view (and edit) the
4672 source files for the program you are debugging with GDB.
4674 To use this interface, use the command `M-x gdb' in Emacs. Give the
4675 executable file you want to debug as an argument. This command starts
4676 GDB as a subprocess of Emacs, with input and output through a newly
4677 created Emacs buffer.
4679 Using GDB under Emacs is just like using GDB normally except for two
4682 * All "terminal" input and output goes through the Emacs buffer.
4684 This applies both to GDB commands and their output, and to the input
4685 and output done by the program you are debugging.
4687 This is useful because it means that you can copy the text of
4688 previous commands and input them again; you can even use parts of the
4691 All the facilities of Emacs' Shell mode are available for interacting
4692 with your program. In particular, you can send signals the usual
4693 way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop.
4695 * GDB displays source code through Emacs.
4697 Each time GDB displays a stack frame, Emacs automatically finds the
4698 source file for that frame and puts an arrow (`=>') at the left margin
4699 of the current line. Emacs uses a separate buffer for source display,
4700 and splits the screen to show both your GDB session and the source.
4702 Explicit GDB `list' or search commands still produce output as
4703 usual, but you probably have no reason to use them from Emacs.
4705 If you specify an absolute file name when prompted for the `M-x gdb'
4706 argument, then Emacs sets your current working directory to where your
4707 program resides. If you only specify the file name, then Emacs sets
4708 your current working directory to to the directory associated with the
4709 previous buffer. In this case, GDB may find your program by searching
4710 your environment's `PATH' variable, but on some operating systems it
4711 might not find the source. So, although the GDB input and output
4712 session proceeds normally, the auxiliary buffer does not display the
4713 current source and line of execution.
4715 The initial working directory of GDB is printed on the top line of
4716 the GDB I/O buffer and this serves as a default for the commands that
4717 specify files for GDB to operate on. *Note Commands to specify files:
4720 By default, `M-x gdb' calls the program called `gdb'. If you need
4721 to call GDB by a different name (for example, if you keep several
4722 configurations around, with different names) you can customize the
4723 Emacs variable `gud-gdb-command-name' to run the one you want.
4725 In the GDB I/O buffer, you can use these special Emacs commands in
4726 addition to the standard Shell mode commands:
4729 Describe the features of Emacs' GDB Mode.
4732 Execute to another source line, like the GDB `step' command; also
4733 update the display window to show the current file and location.
4736 Execute to next source line in this function, skipping all function
4737 calls, like the GDB `next' command. Then update the display window
4738 to show the current file and location.
4741 Execute one instruction, like the GDB `stepi' command; update
4742 display window accordingly.
4745 Execute until exit from the selected stack frame, like the GDB
4749 Continue execution of your program, like the GDB `continue'
4753 Go up the number of frames indicated by the numeric argument
4754 (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
4758 Go down the number of frames indicated by the numeric argument,
4759 like the GDB `down' command.
4761 In any source file, the Emacs command `C-x SPC' (`gud-break') tells
4762 GDB to set a breakpoint on the source line point is on.
4764 If you type `M-x speedbar', then Emacs displays a separate frame
4765 which shows a backtrace when the GDB I/O buffer is current. Move point
4766 to any frame in the stack and type <RET> to make it become the current
4767 frame and display the associated source in the source buffer.
4768 Alternatively, click `Mouse-2' to make the selected frame become the
4771 If you accidentally delete the source-display buffer, an easy way to
4772 get it back is to type the command `f' in the GDB buffer, to request a
4773 frame display; when you run under Emacs, this recreates the source
4774 buffer if necessary to show you the context of the current frame.
4776 The source files displayed in Emacs are in ordinary Emacs buffers
4777 which are visiting the source files in the usual way. You can edit the
4778 files with these buffers if you wish; but keep in mind that GDB
4779 communicates with Emacs in terms of line numbers. If you add or delete
4780 lines from the text, the line numbers that GDB knows cease to
4781 correspond properly with the code.
4783 The description given here is for GNU Emacs version 21.3 and a more
4784 detailed description of its interaction with GDB is given in the Emacs
4785 manual (*note Debuggers: (Emacs)Debuggers.).
4788 File: gdb.info, Node: GDB/MI, Next: GDB Bugs, Prev: Annotations, Up: Top
4790 The GDB/MI Interface
4791 ********************
4793 Function and Purpose
4794 ====================
4796 GDB/MI is a line based machine oriented text interface to GDB. It is
4797 specifically intended to support the development of systems which use
4798 the debugger as just one small component of a larger system.
4800 This chapter is a specification of the GDB/MI interface. It is
4801 written in the form of a reference manual.
4803 Note that GDB/MI is still under construction, so some of the
4804 features described below are incomplete and subject to change.
4806 Notation and Terminology
4807 ========================
4809 This chapter uses the following notation:
4811 * `|' separates two alternatives.
4813 * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
4816 * `( GROUP )*' means that GROUP inside the parentheses may repeat
4819 * `( GROUP )+' means that GROUP inside the parentheses may repeat
4822 * `"STRING"' means a literal STRING.
4827 In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
4832 * GDB/MI Command Syntax::
4833 * GDB/MI Compatibility with CLI::
4834 * GDB/MI Output Records::
4835 * GDB/MI Command Description Format::
4836 * GDB/MI Breakpoint Table Commands::
4837 * GDB/MI Data Manipulation::
4838 * GDB/MI Program Control::
4839 * GDB/MI Miscellaneous Commands::
4840 * GDB/MI Stack Manipulation::
4841 * GDB/MI Symbol Query::
4842 * GDB/MI Target Manipulation::
4843 * GDB/MI Thread Commands::
4844 * GDB/MI Tracepoint Commands::
4845 * GDB/MI Variable Objects::
4848 File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Up: GDB/MI
4850 GDB/MI Command Syntax
4851 =====================
4855 * GDB/MI Input Syntax::
4856 * GDB/MI Output Syntax::
4857 * GDB/MI Simple Examples::
4860 File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
4866 `CLI-COMMAND | MI-COMMAND'
4869 `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
4873 `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
4877 "any sequence of digits"
4880 `"-" PARAMETER [ " " PARAMETER ]'
4883 `NON-BLANK-SEQUENCE | C-STRING'
4886 _any of the operations described in this chapter_
4888 `NON-BLANK-SEQUENCE ==>'
4889 _anything, provided it doesn't contain special characters such as
4890 "-", NL, """ and of course " "_
4893 `""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
4900 * The CLI commands are still handled by the MI interpreter; their
4901 output is described below.
4903 * The `TOKEN', when present, is passed back when the command
4906 * Some MI commands accept optional arguments as part of the parameter
4907 list. Each option is identified by a leading `-' (dash) and may be
4908 followed by an optional argument parameter. Options occur first
4909 in the parameter list and can be delimited from normal parameters
4910 using `--' (this is useful when some parameters begin with a dash).
4914 * We want easy access to the existing CLI syntax (for debugging).
4916 * We want it to be easy to spot a MI operation.
4919 File: gdb.info, Node: GDB/MI Output Syntax, Next: GDB/MI Simple Examples, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax
4921 GDB/MI Output Syntax
4922 --------------------
4924 The output from GDB/MI consists of zero or more out-of-band records
4925 followed, optionally, by a single result record. This result record is
4926 for the most recent command. The sequence of output records is
4927 terminated by `(gdb)'.
4929 If an input command was prefixed with a `TOKEN' then the
4930 corresponding output for that command will also be prefixed by that same
4934 `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'
4937 ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'
4939 `OUT-OF-BAND-RECORD ==>'
4940 `ASYNC-RECORD | STREAM-RECORD'
4943 `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'
4945 `EXEC-ASYNC-OUTPUT ==>'
4946 `[ TOKEN ] "*" ASYNC-OUTPUT'
4948 `STATUS-ASYNC-OUTPUT ==>'
4949 `[ TOKEN ] "+" ASYNC-OUTPUT'
4951 `NOTIFY-ASYNC-OUTPUT ==>'
4952 `[ TOKEN ] "=" ASYNC-OUTPUT'
4955 `ASYNC-CLASS ( "," RESULT )* NL'
4958 `"done" | "running" | "connected" | "error" | "exit"'
4961 `"stopped" | OTHERS' (where OTHERS will be added depending on the
4962 needs--this is still in development).
4965 ` VARIABLE "=" VALUE'
4971 ` CONST | TUPLE | LIST '
4977 ` "{}" | "{" RESULT ( "," RESULT )* "}" '
4980 ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*
4984 `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'
4986 `CONSOLE-STREAM-OUTPUT ==>'
4989 `TARGET-STREAM-OUTPUT ==>'
4992 `LOG-STREAM-OUTPUT ==>'
4999 _any sequence of digits_.
5003 * All output sequences end in a single line containing a period.
5005 * The `TOKEN' is from the corresponding request. If an execution
5006 command is interrupted by the `-exec-interrupt' command, the TOKEN
5007 associated with the `*stopped' message is the one of the original
5008 execution command, not the one of the interrupt command.
5010 * STATUS-ASYNC-OUTPUT contains on-going status information about the
5011 progress of a slow operation. It can be discarded. All status
5012 output is prefixed by `+'.
5014 * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
5015 (stopped, started, disappeared). All async output is prefixed by
5018 * NOTIFY-ASYNC-OUTPUT contains supplementary information that the
5019 client should handle (e.g., a new breakpoint information). All
5020 notify output is prefixed by `='.
5022 * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in
5023 the console. It is the textual response to a CLI command. All
5024 the console output is prefixed by `~'.
5026 * TARGET-STREAM-OUTPUT is the output produced by the target program.
5027 All the target output is prefixed by `@'.
5029 * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
5030 instance messages that should be displayed as part of an error
5031 log. All the log output is prefixed by `&'.
5033 * New GDB/MI commands should only output LISTS containing VALUES.
5036 *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
5037 about the various output records.
5040 File: gdb.info, Node: GDB/MI Simple Examples, Prev: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
5042 Simple Examples of GDB/MI Interaction
5043 -------------------------------------
5045 This subsection presents several simple examples of interaction using
5046 the GDB/MI interface. In these examples, `->' means that the following
5047 line is passed to GDB/MI as input, while `<-' means the output received
5053 Here's an example of stopping the inferior process:
5060 <- *stop,reason="stop",address="0x123",source="a.c:123"
5066 Here's an example of a simple CLI command being passed through GDB/MI
5075 Command With Side Effects
5076 .........................
5078 -> -symbol-file xyz.exe
5079 <- *breakpoint,nr="3",address="0x123",source="a.c:123"
5085 Here's what happens if you pass a non-existent command:
5088 <- ^error,msg="Undefined MI command: rubbish"
5092 File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Output Records, Prev: GDB/MI Command Syntax, Up: GDB/MI
5094 GDB/MI Compatibility with CLI
5095 =============================
5097 To help users familiar with GDB's existing CLI interface, GDB/MI
5098 accepts existing CLI commands. As specified by the syntax, such
5099 commands can be directly entered into the GDB/MI interface and GDB will
5102 This mechanism is provided as an aid to developers of GDB/MI clients
5103 and not as a reliable interface into the CLI. Since the command is
5104 being interpreteted in an environment that assumes GDB/MI behaviour,
5105 the exact output of such commands is likely to end up being an
5106 un-supported hybrid of GDB/MI and CLI output.
5109 File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Command Description Format, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI
5111 GDB/MI Output Records
5112 =====================
5116 * GDB/MI Result Records::
5117 * GDB/MI Stream Records::
5118 * GDB/MI Out-of-band Records::
5121 File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records
5123 GDB/MI Result Records
5124 ---------------------
5126 In addition to a number of out-of-band notifications, the response to a
5127 GDB/MI command includes one of the following result indications:
5129 `"^done" [ "," RESULTS ]'
5130 The synchronous operation was successful, `RESULTS' are the return
5134 The asynchronous operation was successfully started. The target is
5137 `"^error" "," C-STRING'
5138 The operation failed. The `C-STRING' contains the corresponding
5142 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
5144 GDB/MI Stream Records
5145 ---------------------
5147 GDB internally maintains a number of output streams: the console, the
5148 target, and the log. The output intended for each of these streams is
5149 funneled through the GDB/MI interface using "stream records".
5151 Each stream record begins with a unique "prefix character" which
5152 identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
5153 Syntax.). In addition to the prefix, each stream record contains a
5154 `STRING-OUTPUT'. This is either raw text (with an implicit new line)
5155 or a quoted C string (which does not contain an implicit newline).
5158 The console output stream contains text that should be displayed
5159 in the CLI console window. It contains the textual responses to
5163 The target output stream contains any textual output from the
5167 The log stream contains debugging messages being produced by GDB's
5171 File: gdb.info, Node: GDB/MI Out-of-band Records, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records
5173 GDB/MI Out-of-band Records
5174 --------------------------
5176 "Out-of-band" records are used to notify the GDB/MI client of
5177 additional changes that have occurred. Those changes can either be a
5178 consequence of GDB/MI (e.g., a breakpoint modified) or a result of
5179 target activity (e.g., target stopped).
5181 The following is a preliminary list of possible out-of-band records.
5186 File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Table Commands, Prev: GDB/MI Output Records, Up: GDB/MI
5188 GDB/MI Command Description Format
5189 =================================
5191 The remaining sections describe blocks of commands. Each block of
5192 commands is laid out in a fashion similar to this section.
5194 Note the the line breaks shown in the examples are here only for
5195 readability. They don't appear in the real output. Also note that the
5196 commands with a non-available example (N.A.) are not yet implemented.
5201 The motivation for this collection of commands.
5206 A brief introduction to this collection of commands as a whole.
5211 For each command in the block, the following is described:
5221 The corresponding GDB CLI command.
5236 File: gdb.info, Node: GDB/MI Breakpoint Table Commands, Next: GDB/MI Data Manipulation, Prev: GDB/MI Command Description Format, Up: GDB/MI
5238 GDB/MI Breakpoint table commands
5239 ================================
5241 This section documents GDB/MI commands for manipulating breakpoints.
5243 The `-break-after' Command
5244 --------------------------
5249 -break-after NUMBER COUNT
5251 The breakpoint number NUMBER is not in effect until it has been hit
5252 COUNT times. To see how this is reflected in the output of the
5253 `-break-list' command, see the description of the `-break-list' command
5259 The corresponding GDB command is `ignore'.
5266 ^done,bkpt={number="1",addr="0x000100d0",file="hello.c",line="5"}
5273 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
5274 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5275 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5276 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5277 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5278 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5279 {width="40",alignment="2",col_name="what",colhdr="What"}],
5280 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
5281 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
5285 The `-break-condition' Command
5286 ------------------------------
5291 -break-condition NUMBER EXPR
5293 Breakpoint NUMBER will stop the program only if the condition in
5294 EXPR is true. The condition becomes part of the `-break-list' output
5295 (see the description of the `-break-list' command below).
5300 The corresponding GDB command is `condition'.
5306 -break-condition 1 1
5310 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
5311 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5312 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5313 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5314 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5315 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5316 {width="40",alignment="2",col_name="what",colhdr="What"}],
5317 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
5318 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
5319 times="0",ignore="3"}]}
5322 The `-break-delete' Command
5323 ---------------------------
5328 -break-delete ( BREAKPOINT )+
5330 Delete the breakpoint(s) whose number(s) are specified in the
5331 argument list. This is obviously reflected in the breakpoint list.
5336 The corresponding GDB command is `delete'.
5346 ^done,BreakpointTable={nr_rows="0",nr_cols="6",
5347 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5348 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5349 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5350 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5351 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5352 {width="40",alignment="2",col_name="what",colhdr="What"}],
5356 The `-break-disable' Command
5357 ----------------------------
5362 -break-disable ( BREAKPOINT )+
5364 Disable the named BREAKPOINT(s). The field `enabled' in the break
5365 list is now set to `n' for the named BREAKPOINT(s).
5370 The corresponding GDB command is `disable'.
5380 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
5381 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5382 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5383 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5384 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5385 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5386 {width="40",alignment="2",col_name="what",colhdr="What"}],
5387 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
5388 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]}
5391 The `-break-enable' Command
5392 ---------------------------
5397 -break-enable ( BREAKPOINT )+
5399 Enable (previously disabled) BREAKPOINT(s).
5404 The corresponding GDB command is `enable'.
5414 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
5415 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5416 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5417 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5418 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5419 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5420 {width="40",alignment="2",col_name="what",colhdr="What"}],
5421 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
5422 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]}
5425 The `-break-info' Command
5426 -------------------------
5431 -break-info BREAKPOINT
5433 Get information about a single breakpoint.
5438 The corresponding GDB command is `info break BREAKPOINT'.
5445 The `-break-insert' Command
5446 ---------------------------
5451 -break-insert [ -t ] [ -h ] [ -r ]
5452 [ -c CONDITION ] [ -i IGNORE-COUNT ]
5453 [ -p THREAD ] [ LINE | ADDR ]
5455 If specified, LINE, can be one of:
5465 The possible optional parameters of this command are:
5468 Insert a tempoary breakpoint.
5471 Insert a hardware breakpoint.
5474 Make the breakpoint conditional on CONDITION.
5477 Initialize the IGNORE-COUNT.
5480 Insert a regular breakpoint in all the functions whose names match
5481 the given regular expression. Other flags are not applicable to
5487 The result is in the form:
5489 ^done,bkptno="NUMBER",func="FUNCNAME",
5490 file="FILENAME",line="LINENO"
5492 where NUMBER is the GDB number for this breakpoint, FUNCNAME is the
5493 name of the function where the breakpoint was inserted, FILENAME is the
5494 name of the source file which contains this function, and LINENO is the
5495 source line number within that file.
5497 Note: this format is open to change.
5502 The corresponding GDB commands are `break', `tbreak', `hbreak',
5503 `thbreak', and `rbreak'.
5510 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
5512 -break-insert -t foo
5513 ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",line="11"}
5516 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
5517 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5518 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5519 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5520 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5521 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5522 {width="40",alignment="2",col_name="what",colhdr="What"}],
5523 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
5524 addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"},
5525 bkpt={number="2",type="breakpoint",disp="del",enabled="y",
5526 addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"}]}
5528 -break-insert -r foo.*
5530 ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c",line="11"}
5533 The `-break-list' Command
5534 -------------------------
5541 Displays the list of inserted breakpoints, showing the following
5545 number of the breakpoint
5548 type of the breakpoint: `breakpoint' or `watchpoint'
5551 should the breakpoint be deleted or disabled when it is hit: `keep'
5555 is the breakpoint enabled or no: `y' or `n'
5558 memory location at which the breakpoint is set
5561 logical location of the breakpoint, expressed by function name,
5562 file name, line number
5565 number of times the breakpoint has been hit
5567 If there are no breakpoints or watchpoints, the `BreakpointTable'
5568 `body' field is an empty list.
5573 The corresponding GDB command is `info break'.
5580 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
5581 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5582 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5583 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5584 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5585 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5586 {width="40",alignment="2",col_name="what",colhdr="What"}],
5587 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
5588 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
5589 bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
5590 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"}]}
5593 Here's an example of the result when there are no breakpoints:
5597 ^done,BreakpointTable={nr_rows="0",nr_cols="6",
5598 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5599 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5600 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5601 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5602 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5603 {width="40",alignment="2",col_name="what",colhdr="What"}],
5607 The `-break-watch' Command
5608 --------------------------
5613 -break-watch [ -a | -r ]
5615 Create a watchpoint. With the `-a' option it will create an
5616 "access" watchpoint, i.e. a watchpoint that triggers either on a read
5617 from or on a write to the memory location. With the `-r' option, the
5618 watchpoint created is a "read" watchpoint, i.e. it will trigger only
5619 when the memory location is accessed for reading. Without either of
5620 the options, the watchpoint created is a regular watchpoint, i.e. it
5621 will trigger when the memory location is accessed for writing. *Note
5622 Setting watchpoints: Set Watchpoints.
5624 Note that `-break-list' will report a single list of watchpoints and
5625 breakpoints inserted.
5630 The corresponding GDB commands are `watch', `awatch', and `rwatch'.
5635 Setting a watchpoint on a variable in the `main' function:
5639 ^done,wpt={number="2",exp="x"}
5643 ^done,reason="watchpoint-trigger",wpt={number="2",exp="x"},
5644 value={old="-268439212",new="55"},
5645 frame={func="main",args=[],file="recursive2.c",line="5"}
5648 Setting a watchpoint on a variable local to a function. GDB will
5649 stop the program execution twice: first for the variable changing
5650 value, then for the watchpoint going out of scope.
5654 ^done,wpt={number="5",exp="C"}
5658 ^done,reason="watchpoint-trigger",
5659 wpt={number="5",exp="C"},value={old="-276895068",new="3"},
5660 frame={func="callee4",args=[],
5661 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
5665 ^done,reason="watchpoint-scope",wpnum="5",
5666 frame={func="callee3",args=[{name="strarg",
5667 value="0x11940 \"A string argument.\""}],
5668 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
5671 Listing breakpoints and watchpoints, at different points in the
5672 program execution. Note that once the watchpoint goes out of scope, it
5677 ^done,wpt={number="2",exp="C"}
5680 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
5681 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5682 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5683 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5684 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5685 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5686 {width="40",alignment="2",col_name="what",colhdr="What"}],
5687 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
5688 addr="0x00010734",func="callee4",
5689 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
5690 bkpt={number="2",type="watchpoint",disp="keep",
5691 enabled="y",addr="",what="C",times="0"}]}
5695 ^done,reason="watchpoint-trigger",wpt={number="2",exp="C"},
5696 value={old="-276895068",new="3"},
5697 frame={func="callee4",args=[],
5698 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
5701 ^done,BreakpointTable={nr_rows="2",nr_cols="6",
5702 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5703 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5704 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5705 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5706 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5707 {width="40",alignment="2",col_name="what",colhdr="What"}],
5708 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
5709 addr="0x00010734",func="callee4",
5710 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
5711 bkpt={number="2",type="watchpoint",disp="keep",
5712 enabled="y",addr="",what="C",times="-5"}]}
5716 ^done,reason="watchpoint-scope",wpnum="2",
5717 frame={func="callee3",args=[{name="strarg",
5718 value="0x11940 \"A string argument.\""}],
5719 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
5722 ^done,BreakpointTable={nr_rows="1",nr_cols="6",
5723 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
5724 {width="14",alignment="-1",col_name="type",colhdr="Type"},
5725 {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
5726 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
5727 {width="10",alignment="-1",col_name="addr",colhdr="Address"},
5728 {width="40",alignment="2",col_name="what",colhdr="What"}],
5729 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
5730 addr="0x00010734",func="callee4",
5731 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}]}
5735 File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Program Control, Prev: GDB/MI Breakpoint Table Commands, Up: GDB/MI
5737 GDB/MI Data Manipulation
5738 ========================
5740 This section describes the GDB/MI commands that manipulate data:
5741 examine memory and registers, evaluate expressions, etc.
5743 The `-data-disassemble' Command
5744 -------------------------------
5750 [ -s START-ADDR -e END-ADDR ]
5751 | [ -f FILENAME -l LINENUM [ -n LINES ] ]
5757 is the beginning address (or `$pc')
5763 is the name of the file to disassemble
5766 is the line number to disassemble around
5769 is the the number of disassembly lines to be produced. If it is
5770 -1, the whole function will be disassembled, in case no END-ADDR is
5771 specified. If END-ADDR is specified as a non-zero value, and
5772 LINES is lower than the number of disassembly lines between
5773 START-ADDR and END-ADDR, only LINES lines are displayed; if LINES
5774 is higher than the number of lines between START-ADDR and
5775 END-ADDR, only the lines up to END-ADDR are displayed.
5778 is either 0 (meaning only disassembly) or 1 (meaning mixed source
5784 The output for each instruction is composed of four fields:
5794 Note that whatever included in the instruction field, is not
5795 manipulated directely by GDB/MI, i.e. it is not possible to adjust its
5801 There's no direct mapping from this command to the CLI.
5806 Disassemble from the current value of `$pc' to `$pc + 20':
5809 -data-disassemble -s $pc -e "$pc + 20" -- 0
5812 {address="0x000107c0",func-name="main",offset="4",
5814 {address="0x000107c4",func-name="main",offset="8",
5815 inst="sethi %hi(0x11800), %o2"},
5816 {address="0x000107c8",func-name="main",offset="12",
5817 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
5818 {address="0x000107cc",func-name="main",offset="16",
5819 inst="sethi %hi(0x11800), %o2"},
5820 {address="0x000107d0",func-name="main",offset="20",
5821 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
5824 Disassemble the whole `main' function. Line 32 is part of `main'.
5826 -data-disassemble -f basics.c -l 32 -- 0
5828 {address="0x000107bc",func-name="main",offset="0",
5829 inst="save %sp, -112, %sp"},
5830 {address="0x000107c0",func-name="main",offset="4",
5832 {address="0x000107c4",func-name="main",offset="8",
5833 inst="sethi %hi(0x11800), %o2"},
5835 {address="0x0001081c",func-name="main",offset="96",inst="ret "},
5836 {address="0x00010820",func-name="main",offset="100",inst="restore "}]
5839 Disassemble 3 instructions from the start of `main':
5842 -data-disassemble -f basics.c -l 32 -n 3 -- 0
5844 {address="0x000107bc",func-name="main",offset="0",
5845 inst="save %sp, -112, %sp"},
5846 {address="0x000107c0",func-name="main",offset="4",
5848 {address="0x000107c4",func-name="main",offset="8",
5849 inst="sethi %hi(0x11800), %o2"}]
5852 Disassemble 3 instructions from the start of `main' in mixed mode:
5855 -data-disassemble -f basics.c -l 32 -n 3 -- 1
5857 src_and_asm_line={line="31",
5858 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
5859 testsuite/gdb.mi/basics.c",line_asm_insn=[
5860 {address="0x000107bc",func-name="main",offset="0",
5861 inst="save %sp, -112, %sp"}]},
5862 src_and_asm_line={line="32",
5863 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
5864 testsuite/gdb.mi/basics.c",line_asm_insn=[
5865 {address="0x000107c0",func-name="main",offset="4",
5867 {address="0x000107c4",func-name="main",offset="8",
5868 inst="sethi %hi(0x11800), %o2"}]}]
5871 The `-data-evaluate-expression' Command
5872 ---------------------------------------
5877 -data-evaluate-expression EXPR
5879 Evaluate EXPR as an expression. The expression could contain an
5880 inferior function call. The function call will execute synchronously.
5881 If the expression contains spaces, it must be enclosed in double quotes.
5886 The corresponding GDB commands are `print', `output', and `call'. In
5887 `gdbtk' only, there's a corresponding `gdb_eval' command.
5892 In the following example, the numbers that precede the commands are the
5893 "tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command
5894 Syntax. Notice how GDB/MI returns the same tokens in its output.
5896 211-data-evaluate-expression A
5899 311-data-evaluate-expression &A
5900 311^done,value="0xefffeb7c"
5902 411-data-evaluate-expression A+3
5905 511-data-evaluate-expression "A + 3"
5909 The `-data-list-changed-registers' Command
5910 ------------------------------------------
5915 -data-list-changed-registers
5917 Display a list of the registers that have changed.
5922 GDB doesn't have a direct analog for this command; `gdbtk' has the
5923 corresponding command `gdb_changed_register_list'.
5935 *stopped,reason="breakpoint-hit",bkptno="1",frame={func="main",
5936 args=[],file="try.c",line="5"}
5938 -data-list-changed-registers
5939 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
5940 "10","11","13","14","15","16","17","18","19","20","21","22","23",
5941 "24","25","26","27","28","30","31","64","65","66","67","69"]
5944 The `-data-list-register-names' Command
5945 ---------------------------------------
5950 -data-list-register-names [ ( REGNO )+ ]
5952 Show a list of register names for the current target. If no
5953 arguments are given, it shows a list of the names of all the registers.
5954 If integer numbers are given as arguments, it will print a list of the
5955 names of the registers corresponding to the arguments. To ensure
5956 consistency between a register name and its number, the output list may
5957 include empty register names.
5962 GDB does not have a command which corresponds to
5963 `-data-list-register-names'. In `gdbtk' there is a corresponding
5964 command `gdb_regnames'.
5969 For the PPC MBX board:
5971 -data-list-register-names
5972 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
5973 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
5974 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
5975 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
5976 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
5977 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
5978 "", "pc","ps","cr","lr","ctr","xer"]
5980 -data-list-register-names 1 2 3
5981 ^done,register-names=["r1","r2","r3"]
5984 The `-data-list-register-values' Command
5985 ----------------------------------------
5990 -data-list-register-values FMT [ ( REGNO )*]
5992 Display the registers' contents. FMT is the format according to
5993 which the registers' contents are to be returned, followed by an
5994 optional list of numbers specifying the registers to display. A
5995 missing list of numbers indicates that the contents of all the
5996 registers must be returned.
5998 Allowed formats for FMT are:
6021 The corresponding GDB commands are `info reg', `info all-reg', and (in
6022 `gdbtk') `gdb_fetch_registers'.
6027 For a PPC MBX board (note: line breaks are for readability only, they
6028 don't appear in the actual output):
6031 -data-list-register-values r 64 65
6032 ^done,register-values=[{number="64",value="0xfe00a300"},
6033 {number="65",value="0x00029002"}]
6035 -data-list-register-values x
6036 ^done,register-values=[{number="0",value="0xfe0043c8"},
6037 {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
6038 {number="3",value="0x0"},{number="4",value="0xa"},
6039 {number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
6040 {number="7",value="0xfe011e98"},{number="8",value="0x2"},
6041 {number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
6042 {number="11",value="0x1"},{number="12",value="0x0"},
6043 {number="13",value="0x4544"},{number="14",value="0xffdfffff"},
6044 {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
6045 {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
6046 {number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
6047 {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
6048 {number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
6049 {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
6050 {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
6051 {number="29",value="0x0"},{number="30",value="0xfe010000"},
6052 {number="31",value="0x0"},{number="32",value="0x0"},
6053 {number="33",value="0x0"},{number="34",value="0x0"},
6054 {number="35",value="0x0"},{number="36",value="0x0"},
6055 {number="37",value="0x0"},{number="38",value="0x0"},
6056 {number="39",value="0x0"},{number="40",value="0x0"},
6057 {number="41",value="0x0"},{number="42",value="0x0"},
6058 {number="43",value="0x0"},{number="44",value="0x0"},
6059 {number="45",value="0x0"},{number="46",value="0x0"},
6060 {number="47",value="0x0"},{number="48",value="0x0"},
6061 {number="49",value="0x0"},{number="50",value="0x0"},
6062 {number="51",value="0x0"},{number="52",value="0x0"},
6063 {number="53",value="0x0"},{number="54",value="0x0"},
6064 {number="55",value="0x0"},{number="56",value="0x0"},
6065 {number="57",value="0x0"},{number="58",value="0x0"},
6066 {number="59",value="0x0"},{number="60",value="0x0"},
6067 {number="61",value="0x0"},{number="62",value="0x0"},
6068 {number="63",value="0x0"},{number="64",value="0xfe00a300"},
6069 {number="65",value="0x29002"},{number="66",value="0x202f04b5"},
6070 {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
6071 {number="69",value="0x20002b03"}]
6074 The `-data-read-memory' Command
6075 -------------------------------
6080 -data-read-memory [ -o BYTE-OFFSET ]
6081 ADDRESS WORD-FORMAT WORD-SIZE
6082 NR-ROWS NR-COLS [ ASCHAR ]
6087 An expression specifying the address of the first memory word to be
6088 read. Complex expressions containing embedded white space should
6089 be quoted using the C convention.
6092 The format to be used to print the memory words. The notation is
6093 the same as for GDB's `print' command (*note Output formats:
6097 The size of each memory word in bytes.
6100 The number of rows in the output table.
6103 The number of columns in the output table.
6106 If present, indicates that each row should include an ASCII dump.
6107 The value of ASCHAR is used as a padding character when a byte is
6108 not a member of the printable ASCII character set (printable ASCII
6109 characters are those whose code is between 32 and 126,
6113 An offset to add to the ADDRESS before fetching memory.
6115 This command displays memory contents as a table of NR-ROWS by
6116 NR-COLS words, each word being WORD-SIZE bytes. In total, `NR-ROWS *
6117 NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes').
6118 Should less than the requested number of bytes be returned by the
6119 target, the missing words are identified using `N/A'. The number of
6120 bytes read from the target is returned in `nr-bytes' and the starting
6121 address used to read memory in `addr'.
6123 The address of the next/previous row or page is available in
6124 `next-row' and `prev-row', `next-page' and `prev-page'.
6129 The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory
6135 Read six bytes of memory starting at `bytes+6' but then offset by `-6'
6136 bytes. Format as three rows of two columns. One byte per word.
6137 Display each word in hex.
6140 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
6141 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
6142 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
6143 prev-page="0x0000138a",memory=[
6144 {addr="0x00001390",data=["0x00","0x01"]},
6145 {addr="0x00001392",data=["0x02","0x03"]},
6146 {addr="0x00001394",data=["0x04","0x05"]}]
6149 Read two bytes of memory starting at address `shorts + 64' and
6150 display as a single word formatted in decimal.
6153 5-data-read-memory shorts+64 d 2 1 1
6154 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
6155 next-row="0x00001512",prev-row="0x0000150e",
6156 next-page="0x00001512",prev-page="0x0000150e",memory=[
6157 {addr="0x00001510",data=["128"]}]
6160 Read thirty two bytes of memory starting at `bytes+16' and format as
6161 eight rows of four columns. Include a string encoding with `x' used as
6162 the non-printable character.
6165 4-data-read-memory bytes+16 x 1 8 4 x
6166 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
6167 next-row="0x000013c0",prev-row="0x0000139c",
6168 next-page="0x000013c0",prev-page="0x00001380",memory=[
6169 {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
6170 {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
6171 {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
6172 {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
6173 {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
6174 {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
6175 {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
6176 {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
6179 The `-display-delete' Command
6180 -----------------------------
6185 -display-delete NUMBER
6187 Delete the display NUMBER.
6192 The corresponding GDB command is `delete display'.
6199 The `-display-disable' Command
6200 ------------------------------
6205 -display-disable NUMBER
6207 Disable display NUMBER.
6212 The corresponding GDB command is `disable display'.
6219 The `-display-enable' Command
6220 -----------------------------
6225 -display-enable NUMBER
6227 Enable display NUMBER.
6232 The corresponding GDB command is `enable display'.
6239 The `-display-insert' Command
6240 -----------------------------
6245 -display-insert EXPRESSION
6247 Display EXPRESSION every time the program stops.
6252 The corresponding GDB command is `display'.
6259 The `-display-list' Command
6260 ---------------------------
6267 List the displays. Do not show the current values.
6272 The corresponding GDB command is `info display'.
6279 The `-environment-cd' Command
6280 -----------------------------
6285 -environment-cd PATHDIR
6287 Set GDB's working directory.
6292 The corresponding GDB command is `cd'.
6298 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
6302 The `-environment-directory' Command
6303 ------------------------------------
6308 -environment-directory [ -r ] [ PATHDIR ]+
6310 Add directories PATHDIR to beginning of search path for source files.
6311 If the `-r' option is used, the search path is reset to the default
6312 search path. If directories PATHDIR are supplied in addition to the
6313 `-r' option, the search path is first reset and then addition occurs as
6314 normal. Multiple directories may be specified, separated by blanks.
6315 Specifying multiple directories in a single command results in the
6316 directories added to the beginning of the search path in the same order
6317 they were presented in the command. If blanks are needed as part of a
6318 directory name, double-quotes should be used around the name. In the
6319 command output, the path will show up separated by the system
6320 directory-separator character. The directory-seperator character must
6321 not be used in any directory name. If no directories are specified,
6322 the current search path is displayed.
6327 The corresponding GDB command is `dir'.
6333 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
6334 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
6336 -environment-directory ""
6337 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
6339 -environment-directory -r /home/jjohnstn/src/gdb /usr/src
6340 ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
6342 -environment-directory -r
6343 ^done,source-path="$cdir:$cwd"
6346 The `-environment-path' Command
6347 -------------------------------
6352 -environment-path [ -r ] [ PATHDIR ]+
6354 Add directories PATHDIR to beginning of search path for object files.
6355 If the `-r' option is used, the search path is reset to the original
6356 search path that existed at gdb start-up. If directories PATHDIR are
6357 supplied in addition to the `-r' option, the search path is first reset
6358 and then addition occurs as normal. Multiple directories may be
6359 specified, separated by blanks. Specifying multiple directories in a
6360 single command results in the directories added to the beginning of the
6361 search path in the same order they were presented in the command. If
6362 blanks are needed as part of a directory name, double-quotes should be
6363 used around the name. In the command output, the path will show up
6364 separated by the system directory-separator character. The
6365 directory-seperator character must not be used in any directory name.
6366 If no directories are specified, the current path is displayed.
6371 The corresponding GDB command is `path'.
6378 ^done,path="/usr/bin"
6380 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
6381 ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
6383 -environment-path -r /usr/local/bin
6384 ^done,path="/usr/local/bin:/usr/bin"
6387 The `-environment-pwd' Command
6388 ------------------------------
6395 Show the current working directory.
6400 The corresponding GDB command is `pwd'.
6407 ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
6411 File: gdb.info, Node: GDB/MI Program Control, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Data Manipulation, Up: GDB/MI
6413 GDB/MI Program control
6414 ======================
6419 As a result of execution, the inferior program can run to completion, if
6420 it doesn't encounter any breakpoints. In this case the output will
6421 include an exit code, if the program has exited exceptionally.
6426 Program exited normally:
6433 *stopped,reason="exited-normally"
6436 Program exited exceptionally:
6443 *stopped,reason="exited",exit-code="01"
6446 Another way the program can terminate is if it receives a signal
6447 such as `SIGINT'. In this case, GDB/MI displays this:
6450 *stopped,reason="exited-signalled",signal-name="SIGINT",
6451 signal-meaning="Interrupt"
6453 The `-exec-abort' Command
6454 -------------------------
6461 Kill the inferior running program.
6466 The corresponding GDB command is `kill'.
6473 The `-exec-arguments' Command
6474 -----------------------------
6479 -exec-arguments ARGS
6481 Set the inferior program arguments, to be used in the next
6487 The corresponding GDB command is `set args'.
6492 Don't have one around.
6494 The `-exec-continue' Command
6495 ----------------------------
6502 Asynchronous command. Resumes the execution of the inferior program
6503 until a breakpoint is encountered, or until the inferior exits.
6508 The corresponding GDB corresponding is `continue'.
6517 *stopped,reason="breakpoint-hit",bkptno="2",frame={func="foo",args=[],
6518 file="hello.c",line="13"}
6521 The `-exec-finish' Command
6522 --------------------------
6529 Asynchronous command. Resumes the execution of the inferior program
6530 until the current function is exited. Displays the results returned by
6536 The corresponding GDB command is `finish'.
6541 Function returning `void'.
6547 *stopped,reason="function-finished",frame={func="main",args=[],
6548 file="hello.c",line="7"}
6551 Function returning other than `void'. The name of the internal GDB
6552 variable storing the result is printed, together with the value itself.
6557 *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
6558 args=[{name="a",value="1"],{name="b",value="9"}},
6559 file="recursive2.c",line="14"},
6560 gdb-result-var="$1",return-value="0"
6563 The `-exec-interrupt' Command
6564 -----------------------------
6571 Asynchronous command. Interrupts the background execution of the
6572 target. Note how the token associated with the stop message is the one
6573 for the execution command that has been interrupted. The token for the
6574 interrupt itself only appears in the `^done' output. If the user is
6575 trying to interrupt a non-running program, an error message will be
6581 The corresponding GDB command is `interrupt'.
6594 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
6595 frame={addr="0x00010140",func="foo",args=[],file="try.c",line="13"}
6600 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
6603 The `-exec-next' Command
6604 ------------------------
6611 Asynchronous command. Resumes execution of the inferior program,
6612 stopping when the beginning of the next source line is reached.
6617 The corresponding GDB command is `next'.
6625 *stopped,reason="end-stepping-range",line="8",file="hello.c"
6628 The `-exec-next-instruction' Command
6629 ------------------------------------
6634 -exec-next-instruction
6636 Asynchronous command. Executes one machine instruction. If the
6637 instruction is a function call continues until the function returns. If
6638 the program stops at an instruction in the middle of a source line, the
6639 address will be printed as well.
6644 The corresponding GDB command is `nexti'.
6650 -exec-next-instruction
6654 *stopped,reason="end-stepping-range",
6655 addr="0x000100d4",line="5",file="hello.c"
6658 The `-exec-return' Command
6659 --------------------------
6666 Makes current function return immediately. Doesn't execute the
6667 inferior. Displays the new current frame.
6672 The corresponding GDB command is `return'.
6678 200-break-insert callee4
6679 200^done,bkpt={number="1",addr="0x00010734",
6680 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
6685 000*stopped,reason="breakpoint-hit",bkptno="1",
6686 frame={func="callee4",args=[],
6687 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
6693 111^done,frame={level="0",func="callee3",
6694 args=[{name="strarg",
6695 value="0x11940 \"A string argument.\""}],
6696 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
6699 The `-exec-run' Command
6700 -----------------------
6707 Asynchronous command. Starts execution of the inferior from the
6708 beginning. The inferior executes until either a breakpoint is
6709 encountered or the program exits.
6714 The corresponding GDB command is `run'.
6721 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
6726 *stopped,reason="breakpoint-hit",bkptno="1",
6727 frame={func="main",args=[],file="recursive2.c",line="4"}
6730 The `-exec-show-arguments' Command
6731 ----------------------------------
6736 -exec-show-arguments
6738 Print the arguments of the program.
6743 The corresponding GDB command is `show args'.
6750 The `-exec-step' Command
6751 ------------------------
6758 Asynchronous command. Resumes execution of the inferior program,
6759 stopping when the beginning of the next source line is reached, if the
6760 next source line is not a function call. If it is, stop at the first
6761 instruction of the called function.
6766 The corresponding GDB command is `step'.
6771 Stepping into a function:
6776 *stopped,reason="end-stepping-range",
6777 frame={func="foo",args=[{name="a",value="10"},
6778 {name="b",value="0"}],file="recursive2.c",line="11"}
6786 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
6789 The `-exec-step-instruction' Command
6790 ------------------------------------
6795 -exec-step-instruction
6797 Asynchronous command. Resumes the inferior which executes one
6798 machine instruction. The output, once GDB has stopped, will vary
6799 depending on whether we have stopped in the middle of a source line or
6800 not. In the former case, the address at which the program stopped will
6806 The corresponding GDB command is `stepi'.
6812 -exec-step-instruction
6816 *stopped,reason="end-stepping-range",
6817 frame={func="foo",args=[],file="try.c",line="10"}
6819 -exec-step-instruction
6823 *stopped,reason="end-stepping-range",
6824 frame={addr="0x000100f4",func="foo",args=[],file="try.c",line="10"}
6827 The `-exec-until' Command
6828 -------------------------
6833 -exec-until [ LOCATION ]
6835 Asynchronous command. Executes the inferior until the LOCATION
6836 specified in the argument is reached. If there is no argument, the
6837 inferior executes until a source line greater than the current one is
6838 reached. The reason for stopping in this case will be
6844 The corresponding GDB command is `until'.
6850 -exec-until recursive2.c:6
6854 *stopped,reason="location-reached",frame={func="main",args=[],
6855 file="recursive2.c",line="6"}
6858 The `-file-exec-and-symbols' Command
6859 ------------------------------------
6864 -file-exec-and-symbols FILE
6866 Specify the executable file to be debugged. This file is the one
6867 from which the symbol table is also read. If no file is specified, the
6868 command clears the executable and symbol information. If breakpoints
6869 are set when using this command with no arguments, GDB will produce
6870 error messages. Otherwise, no output is produced, except a completion
6876 The corresponding GDB command is `file'.
6882 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
6886 The `-file-exec-file' Command
6887 -----------------------------
6892 -file-exec-file FILE
6894 Specify the executable file to be debugged. Unlike
6895 `-file-exec-and-symbols', the symbol table is _not_ read from this
6896 file. If used without argument, GDB clears the information about the
6897 executable file. No output is produced, except a completion
6903 The corresponding GDB command is `exec-file'.
6909 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
6913 The `-file-list-exec-sections' Command
6914 --------------------------------------
6919 -file-list-exec-sections
6921 List the sections of the current executable file.
6926 The GDB command `info file' shows, among the rest, the same information
6927 as this command. `gdbtk' has a corresponding command `gdb_load_info'.
6934 The `-file-list-exec-source-file' Command
6935 -----------------------------------------
6940 -file-list-exec-source-file
6942 List the line number, the current source file, and the absolute path
6943 to the current source file for the current executable.
6948 There's no GDB command which directly corresponds to this one.
6954 123-file-list-exec-source-file
6955 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
6958 The `-file-list-exec-source-files' Command
6959 ------------------------------------------
6964 -file-list-exec-source-files
6966 List the source files for the current executable.
6971 There's no GDB command which directly corresponds to this one. `gdbtk'
6972 has an analogous command `gdb_listfiles'.
6979 The `-file-list-shared-libraries' Command
6980 -----------------------------------------
6985 -file-list-shared-libraries
6987 List the shared libraries in the program.
6992 The corresponding GDB command is `info shared'.
6999 The `-file-list-symbol-files' Command
7000 -------------------------------------
7005 -file-list-symbol-files
7012 The corresponding GDB command is `info file' (part of it).
7019 The `-file-symbol-file' Command
7020 -------------------------------
7025 -file-symbol-file FILE
7027 Read symbol table info from the specified FILE argument. When used
7028 without arguments, clears GDB's symbol table info. No output is
7029 produced, except for a completion notification.
7034 The corresponding GDB command is `symbol-file'.
7040 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
7045 File: gdb.info, Node: GDB/MI Miscellaneous Commands, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Program Control, Up: GDB/MI
7047 Miscellaneous GDB commands in GDB/MI
7048 ====================================
7050 The `-gdb-exit' Command
7051 -----------------------
7058 Exit GDB immediately.
7063 Approximately corresponds to `quit'.
7071 The `-gdb-set' Command
7072 ----------------------
7079 Set an internal GDB variable.
7084 The corresponding GDB command is `set'.
7094 The `-gdb-show' Command
7095 -----------------------
7102 Show the current value of a GDB variable.
7107 The corresponding GDB command is `show'.
7117 The `-gdb-version' Command
7118 --------------------------
7125 Show version information for GDB. Used mostly in testing.
7130 There's no equivalent GDB command. GDB by default shows this
7131 information when you start an interactive session.
7139 ~Copyright 2000 Free Software Foundation, Inc.
7140 ~GDB is free software, covered by the GNU General Public License, and
7141 ~you are welcome to change it and/or distribute copies of it under
7142 ~ certain conditions.
7143 ~Type "show copying" to see the conditions.
7144 ~There is absolutely no warranty for GDB. Type "show warranty" for
7146 ~This GDB was configured as
7147 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
7151 The `-interpreter-exec' Command
7152 -------------------------------
7157 -interpreter-exec INTERPRETER COMMAND
7159 Execute the specified COMMAND in the given INTERPRETER.
7164 The corresponding GDB command is `interpreter-exec'.
7170 -interpreter-exec console "break main"
7171 &"During symbol reading, couldn't parse type; debugger out of date?.\n"
7172 &"During symbol reading, bad structure-type format.\n"
7173 ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
7178 File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Symbol Query, Prev: GDB/MI Miscellaneous Commands, Up: GDB/MI
7180 GDB/MI Stack Manipulation Commands
7181 ==================================
7183 The `-stack-info-frame' Command
7184 -------------------------------
7191 Get info on the current frame.
7196 The corresponding GDB command is `info frame' or `frame' (without
7204 The `-stack-info-depth' Command
7205 -------------------------------
7210 -stack-info-depth [ MAX-DEPTH ]
7212 Return the depth of the stack. If the integer argument MAX-DEPTH is
7213 specified, do not count beyond MAX-DEPTH frames.
7218 There's no equivalent GDB command.
7223 For a stack with frame levels 0 through 11:
7232 -stack-info-depth 12
7235 -stack-info-depth 11
7238 -stack-info-depth 13
7242 The `-stack-list-arguments' Command
7243 -----------------------------------
7248 -stack-list-arguments SHOW-VALUES
7249 [ LOW-FRAME HIGH-FRAME ]
7251 Display a list of the arguments for the frames between LOW-FRAME and
7252 HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided,
7253 list the arguments for the whole call stack.
7255 The SHOW-VALUES argument must have a value of 0 or 1. A value of 0
7256 means that only the names of the arguments are listed, a value of 1
7257 means that both names and values of the arguments are printed.
7262 GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args'
7263 command which partially overlaps with the functionality of
7264 `-stack-list-arguments'.
7273 frame={level="0",addr="0x00010734",func="callee4",
7274 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
7275 frame={level="1",addr="0x0001076c",func="callee3",
7276 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
7277 frame={level="2",addr="0x0001078c",func="callee2",
7278 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
7279 frame={level="3",addr="0x000107b4",func="callee1",
7280 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
7281 frame={level="4",addr="0x000107e0",func="main",
7282 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
7284 -stack-list-arguments 0
7287 frame={level="0",args=[]},
7288 frame={level="1",args=[name="strarg"]},
7289 frame={level="2",args=[name="intarg",name="strarg"]},
7290 frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
7291 frame={level="4",args=[]}]
7293 -stack-list-arguments 1
7296 frame={level="0",args=[]},
7298 args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
7299 frame={level="2",args=[
7300 {name="intarg",value="2"},
7301 {name="strarg",value="0x11940 \"A string argument.\""}]},
7302 {frame={level="3",args=[
7303 {name="intarg",value="2"},
7304 {name="strarg",value="0x11940 \"A string argument.\""},
7305 {name="fltarg",value="3.5"}]},
7306 frame={level="4",args=[]}]
7308 -stack-list-arguments 0 2 2
7309 ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
7311 -stack-list-arguments 1 2 2
7312 ^done,stack-args=[frame={level="2",
7313 args=[{name="intarg",value="2"},
7314 {name="strarg",value="0x11940 \"A string argument.\""}]}]
7317 The `-stack-list-frames' Command
7318 --------------------------------
7323 -stack-list-frames [ LOW-FRAME HIGH-FRAME ]
7325 List the frames currently on the stack. For each frame it displays
7329 The frame number, 0 being the topmost frame, i.e. the innermost
7333 The `$pc' value for that frame.
7339 File name of the source file where the function lives.
7342 Line number corresponding to the `$pc'.
7344 If invoked without arguments, this command prints a backtrace for the
7345 whole stack. If given two integer arguments, it shows the frames whose
7346 levels are between the two arguments (inclusive). If the two arguments
7347 are equal, it shows the single frame at the corresponding level.
7352 The corresponding GDB commands are `backtrace' and `where'.
7357 Full stack backtrace:
7362 [frame={level="0",addr="0x0001076c",func="foo",
7363 file="recursive2.c",line="11"},
7364 frame={level="1",addr="0x000107a4",func="foo",
7365 file="recursive2.c",line="14"},
7366 frame={level="2",addr="0x000107a4",func="foo",
7367 file="recursive2.c",line="14"},
7368 frame={level="3",addr="0x000107a4",func="foo",
7369 file="recursive2.c",line="14"},
7370 frame={level="4",addr="0x000107a4",func="foo",
7371 file="recursive2.c",line="14"},
7372 frame={level="5",addr="0x000107a4",func="foo",
7373 file="recursive2.c",line="14"},
7374 frame={level="6",addr="0x000107a4",func="foo",
7375 file="recursive2.c",line="14"},
7376 frame={level="7",addr="0x000107a4",func="foo",
7377 file="recursive2.c",line="14"},
7378 frame={level="8",addr="0x000107a4",func="foo",
7379 file="recursive2.c",line="14"},
7380 frame={level="9",addr="0x000107a4",func="foo",
7381 file="recursive2.c",line="14"},
7382 frame={level="10",addr="0x000107a4",func="foo",
7383 file="recursive2.c",line="14"},
7384 frame={level="11",addr="0x00010738",func="main",
7385 file="recursive2.c",line="4"}]
7388 Show frames between LOW_FRAME and HIGH_FRAME:
7391 -stack-list-frames 3 5
7393 [frame={level="3",addr="0x000107a4",func="foo",
7394 file="recursive2.c",line="14"},
7395 frame={level="4",addr="0x000107a4",func="foo",
7396 file="recursive2.c",line="14"},
7397 frame={level="5",addr="0x000107a4",func="foo",
7398 file="recursive2.c",line="14"}]
7401 Show a single frame:
7404 -stack-list-frames 3 3
7406 [frame={level="3",addr="0x000107a4",func="foo",
7407 file="recursive2.c",line="14"}]
7410 The `-stack-list-locals' Command
7411 --------------------------------
7416 -stack-list-locals PRINT-VALUES
7418 Display the local variable names for the current frame. With an
7419 argument of 0 or `--no-values', prints only the names of the variables.
7420 With argument of 1 or `--all-values', prints also their values. With
7421 argument of 2 or `--simple-values', prints the name, type and value for
7422 simple data types and the name and type for arrays, structures and
7423 unions. In this last case, the idea is that the user can see the value
7424 of simple data types immediately and he can create variable objects for
7425 other data types if he wishes to explore their values in more detail.
7430 `info locals' in GDB, `gdb_get_locals' in `gdbtk'.
7436 -stack-list-locals 0
7437 ^done,locals=[name="A",name="B",name="C"]
7439 -stack-list-locals --all-values
7440 ^done,locals=[{name="A",value="1"},{name="B",value="2"},
7441 {name="C",value="{1, 2, 3}"}]
7442 -stack-list-locals --simple-values
7443 ^done,locals=[{name="A",type="int",value="1"},
7444 {name="B",type="int",value="2"},{name="C",type="int [3]"}]
7447 The `-stack-select-frame' Command
7448 ---------------------------------
7453 -stack-select-frame FRAMENUM
7455 Change the current frame. Select a different frame FRAMENUM on the
7461 The corresponding GDB commands are `frame', `up', `down',
7462 `select-frame', `up-silent', and `down-silent'.
7468 -stack-select-frame 2
7473 File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI Target Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI
7475 GDB/MI Symbol Query Commands
7476 ============================
7478 The `-symbol-info-address' Command
7479 ----------------------------------
7484 -symbol-info-address SYMBOL
7486 Describe where SYMBOL is stored.
7491 The corresponding GDB command is `info address'.
7498 The `-symbol-info-file' Command
7499 -------------------------------
7506 Show the file for the symbol.
7511 There's no equivalent GDB command. `gdbtk' has `gdb_find_file'.
7518 The `-symbol-info-function' Command
7519 -----------------------------------
7524 -symbol-info-function
7526 Show which function the symbol lives in.
7531 `gdb_get_function' in `gdbtk'.
7538 The `-symbol-info-line' Command
7539 -------------------------------
7546 Show the core addresses of the code for a source line.
7551 The corresponding GDB command is `info line'. `gdbtk' has the
7552 `gdb_get_line' and `gdb_get_file' commands.
7559 The `-symbol-info-symbol' Command
7560 ---------------------------------
7565 -symbol-info-symbol ADDR
7567 Describe what symbol is at location ADDR.
7572 The corresponding GDB command is `info symbol'.
7579 The `-symbol-list-functions' Command
7580 ------------------------------------
7585 -symbol-list-functions
7587 List the functions in the executable.
7592 `info functions' in GDB, `gdb_listfunc' and `gdb_search' in `gdbtk'.
7599 The `-symbol-list-lines' Command
7600 --------------------------------
7605 -symbol-list-lines FILENAME
7607 Print the list of lines that contain code and their associated
7608 program addresses for the given source filename. The entries are
7609 sorted in ascending PC order.
7614 There is no corresponding GDB command.
7620 -symbol-list-lines basics.c
7621 ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
7624 The `-symbol-list-types' Command
7625 --------------------------------
7632 List all the type names.
7637 The corresponding commands are `info types' in GDB, `gdb_search' in
7645 The `-symbol-list-variables' Command
7646 ------------------------------------
7651 -symbol-list-variables
7653 List all the global and static variable names.
7658 `info variables' in GDB, `gdb_search' in `gdbtk'.
7665 The `-symbol-locate' Command
7666 ----------------------------
7676 `gdb_loc' in `gdbtk'.
7683 The `-symbol-type' Command
7684 --------------------------
7689 -symbol-type VARIABLE
7691 Show type of VARIABLE.
7696 The corresponding GDB command is `ptype', `gdbtk' has
7705 File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI Thread Commands, Prev: GDB/MI Symbol Query, Up: GDB/MI
7707 GDB/MI Target Manipulation Commands
7708 ===================================
7710 The `-target-attach' Command
7711 ----------------------------
7716 -target-attach PID | FILE
7718 Attach to a process PID or a file FILE outside of GDB.
7723 The corresponding GDB command is `attach'.
7730 The `-target-compare-sections' Command
7731 --------------------------------------
7736 -target-compare-sections [ SECTION ]
7738 Compare data of section SECTION on target to the exec file. Without
7739 the argument, all sections are compared.
7744 The GDB equivalent is `compare-sections'.
7751 The `-target-detach' Command
7752 ----------------------------
7759 Disconnect from the remote target. There's no output.
7764 The corresponding GDB command is `detach'.
7774 The `-target-disconnect' Command
7775 --------------------------------
7782 Disconnect from the remote target. There's no output.
7787 The corresponding GDB command is `disconnect'.
7797 The `-target-download' Command
7798 ------------------------------
7805 Loads the executable onto the remote target. It prints out an
7806 update message every half second, which includes the fields:
7809 The name of the section.
7812 The size of what has been sent so far for that section.
7815 The size of the section.
7818 The total size of what was sent so far (the current and the
7822 The size of the overall executable to download.
7824 Each message is sent as status record (*note GDB/MI Output Syntax:
7825 GDB/MI Output Syntax.).
7827 In addition, it prints the name and size of the sections, as they are
7828 downloaded. These messages include the following fields:
7831 The name of the section.
7834 The size of the section.
7837 The size of the overall executable to download.
7839 At the end, a summary is printed.
7844 The corresponding GDB command is `load'.
7849 Note: each status message appears on a single line. Here the messages
7850 have been broken down so that they can fit onto a page.
7854 +download,{section=".text",section-size="6668",total-size="9880"}
7855 +download,{section=".text",section-sent="512",section-size="6668",
7856 total-sent="512",total-size="9880"}
7857 +download,{section=".text",section-sent="1024",section-size="6668",
7858 total-sent="1024",total-size="9880"}
7859 +download,{section=".text",section-sent="1536",section-size="6668",
7860 total-sent="1536",total-size="9880"}
7861 +download,{section=".text",section-sent="2048",section-size="6668",
7862 total-sent="2048",total-size="9880"}
7863 +download,{section=".text",section-sent="2560",section-size="6668",
7864 total-sent="2560",total-size="9880"}
7865 +download,{section=".text",section-sent="3072",section-size="6668",
7866 total-sent="3072",total-size="9880"}
7867 +download,{section=".text",section-sent="3584",section-size="6668",
7868 total-sent="3584",total-size="9880"}
7869 +download,{section=".text",section-sent="4096",section-size="6668",
7870 total-sent="4096",total-size="9880"}
7871 +download,{section=".text",section-sent="4608",section-size="6668",
7872 total-sent="4608",total-size="9880"}
7873 +download,{section=".text",section-sent="5120",section-size="6668",
7874 total-sent="5120",total-size="9880"}
7875 +download,{section=".text",section-sent="5632",section-size="6668",
7876 total-sent="5632",total-size="9880"}
7877 +download,{section=".text",section-sent="6144",section-size="6668",
7878 total-sent="6144",total-size="9880"}
7879 +download,{section=".text",section-sent="6656",section-size="6668",
7880 total-sent="6656",total-size="9880"}
7881 +download,{section=".init",section-size="28",total-size="9880"}
7882 +download,{section=".fini",section-size="28",total-size="9880"}
7883 +download,{section=".data",section-size="3156",total-size="9880"}
7884 +download,{section=".data",section-sent="512",section-size="3156",
7885 total-sent="7236",total-size="9880"}
7886 +download,{section=".data",section-sent="1024",section-size="3156",
7887 total-sent="7748",total-size="9880"}
7888 +download,{section=".data",section-sent="1536",section-size="3156",
7889 total-sent="8260",total-size="9880"}
7890 +download,{section=".data",section-sent="2048",section-size="3156",
7891 total-sent="8772",total-size="9880"}
7892 +download,{section=".data",section-sent="2560",section-size="3156",
7893 total-sent="9284",total-size="9880"}
7894 +download,{section=".data",section-sent="3072",section-size="3156",
7895 total-sent="9796",total-size="9880"}
7896 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
7900 The `-target-exec-status' Command
7901 ---------------------------------
7908 Provide information on the state of the target (whether it is
7909 running or not, for instance).
7914 There's no equivalent GDB command.
7921 The `-target-list-available-targets' Command
7922 --------------------------------------------
7927 -target-list-available-targets
7929 List the possible targets to connect to.
7934 The corresponding GDB command is `help target'.
7941 The `-target-list-current-targets' Command
7942 ------------------------------------------
7947 -target-list-current-targets
7949 Describe the current target.
7954 The corresponding information is printed by `info file' (among other
7962 The `-target-list-parameters' Command
7963 -------------------------------------
7968 -target-list-parameters
7980 The `-target-select' Command
7981 ----------------------------
7986 -target-select TYPE PARAMETERS ...
7988 Connect GDB to the remote target. This command takes two args:
7991 The type of target, for instance `async', `remote', etc.
7994 Device names, host names and the like. *Note Commands for
7995 managing targets: Target Commands, for more details.
7997 The output is a connection notification, followed by the address at
7998 which the target program is, in the following form:
8000 ^connected,addr="ADDRESS",func="FUNCTION NAME",
8006 The corresponding GDB command is `target'.
8012 -target-select async /dev/ttya
8013 ^connected,addr="0xfe00a300",func="??",args=[]
8017 File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI
8019 GDB/MI Thread Commands
8020 ======================
8022 The `-thread-info' Command
8023 --------------------------
8040 The `-thread-list-all-threads' Command
8041 --------------------------------------
8046 -thread-list-all-threads
8051 The equivalent GDB command is `info threads'.
8058 The `-thread-list-ids' Command
8059 ------------------------------
8066 Produces a list of the currently known GDB thread ids. At the end
8067 of the list it also prints the total number of such threads.
8072 Part of `info threads' supplies the same information.
8077 No threads present, besides the main process:
8081 ^done,thread-ids={},number-of-threads="0"
8088 ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
8089 number-of-threads="3"
8092 The `-thread-select' Command
8093 ----------------------------
8098 -thread-select THREADNUM
8100 Make THREADNUM the current thread. It prints the number of the new
8101 current thread, and the topmost frame for that thread.
8106 The corresponding GDB command is `thread'.
8115 *stopped,reason="end-stepping-range",thread-id="2",line="187",
8116 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
8120 thread-ids={thread-id="3",thread-id="2",thread-id="1"},
8121 number-of-threads="3"
8124 ^done,new-thread-id="3",
8125 frame={level="0",func="vprintf",
8126 args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
8127 {name="arg",value="0x2"}],file="vprintf.c",line="31"}
8131 File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Variable Objects, Prev: GDB/MI Thread Commands, Up: GDB/MI
8133 GDB/MI Tracepoint Commands
8134 ==========================
8136 The tracepoint commands are not yet implemented.
8139 File: gdb.info, Node: GDB/MI Variable Objects, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI
8141 GDB/MI Variable Objects
8142 =======================
8144 Motivation for Variable Objects in GDB/MI
8145 -----------------------------------------
8147 For the implementation of a variable debugger window (locals, watched
8148 expressions, etc.), we are proposing the adaptation of the existing code
8151 The two main reasons for that are:
8153 1. It has been proven in practice (it is already on its second
8156 2. It will shorten development time (needless to say how important it
8159 The original interface was designed to be used by Tcl code, so it was
8160 slightly changed so it could be used through GDB/MI. This section
8161 describes the GDB/MI operations that will be available and gives some
8162 hints about their use.
8164 _Note_: In addition to the set of operations described here, we
8165 expect the GUI implementation of a variable window to require, at
8166 least, the following operations:
8168 * `-gdb-show' `output-radix'
8170 * `-stack-list-arguments'
8172 * `-stack-list-locals'
8174 * `-stack-select-frame'
8176 Introduction to Variable Objects in GDB/MI
8177 ------------------------------------------
8179 The basic idea behind variable objects is the creation of a named object
8180 to represent a variable, an expression, a memory location or even a CPU
8181 register. For each object created, a set of operations is available for
8182 examining or changing its properties.
8184 Furthermore, complex data types, such as C structures, are
8185 represented in a tree format. For instance, the `struct' type variable
8186 is the root and the children will represent the struct members. If a
8187 child is itself of a complex type, it will also have children of its
8188 own. Appropriate language differences are handled for C, C++ and Java.
8190 When returning the actual values of the objects, this facility allows
8191 for the individual selection of the display format used in the result
8192 creation. It can be chosen among: binary, decimal, hexadecimal, octal
8193 and natural. Natural refers to a default format automatically chosen
8194 based on the variable type (like decimal for an `int', hex for
8197 The following is the complete set of GDB/MI operations defined to
8198 access this functionality:
8200 *Operation* *Description*
8201 `-var-create' create a variable object
8202 `-var-delete' delete the variable object and its children
8203 `-var-set-format' set the display format of this variable
8204 `-var-show-format' show the display format of this variable
8205 `-var-info-num-children' tells how many children this object has
8206 `-var-list-children' return a list of the object's children
8207 `-var-info-type' show the type of this variable object
8208 `-var-info-expression' print what this variable object represents
8209 `-var-show-attributes' is this variable editable? does it exist
8211 `-var-evaluate-expression' get the value of this variable
8212 `-var-assign' set the value of this variable
8213 `-var-update' update the variable and its children
8215 In the next subsection we describe each operation in detail and
8216 suggest how it can be used.
8218 Description And Use of Operations on Variable Objects
8219 -----------------------------------------------------
8221 The `-var-create' Command
8222 -------------------------
8227 -var-create {NAME | "-"}
8228 {FRAME-ADDR | "*"} EXPRESSION
8230 This operation creates a variable object, which allows the
8231 monitoring of a variable, the result of an expression, a memory cell or
8234 The NAME parameter is the string by which the object can be
8235 referenced. It must be unique. If `-' is specified, the varobj system
8236 will generate a string "varNNNNNN" automatically. It will be unique
8237 provided that one does not specify NAME on that format. The command
8238 fails if a duplicate name is found.
8240 The frame under which the expression should be evaluated can be
8241 specified by FRAME-ADDR. A `*' indicates that the current frame should
8244 EXPRESSION is any expression valid on the current language set (must
8245 not begin with a `*'), or one of the following:
8247 * `*ADDR', where ADDR is the address of a memory cell
8249 * `*ADDR-ADDR' -- a memory address range (TBD)
8251 * `$REGNAME' -- a CPU register name
8256 This operation returns the name, number of children and the type of the
8257 object created. Type is returned as a string as the ones generated by
8260 name="NAME",numchild="N",type="TYPE"
8262 The `-var-delete' Command
8263 -------------------------
8270 Deletes a previously created variable object and all of its children.
8272 Returns an error if the object NAME is not found.
8274 The `-var-set-format' Command
8275 -----------------------------
8280 -var-set-format NAME FORMAT-SPEC
8282 Sets the output format for the value of the object NAME to be
8285 The syntax for the FORMAT-SPEC is as follows:
8288 {binary | decimal | hexadecimal | octal | natural}
8290 The `-var-show-format' Command
8291 ------------------------------
8296 -var-show-format NAME
8298 Returns the format used to display the value of the object NAME.
8303 The `-var-info-num-children' Command
8304 ------------------------------------
8309 -var-info-num-children NAME
8311 Returns the number of children of a variable object NAME:
8315 The `-var-list-children' Command
8316 --------------------------------
8321 -var-list-children [PRINT-VALUES] NAME
8323 Returns a list of the children of the specified variable object.
8324 With just the variable object name as an argument or with an optional
8325 preceding argument of 0 or `--no-values', prints only the names of the
8326 variables. With an optional preceding argument of 1 or `--all-values',
8327 also prints their values.
8333 -var-list-children n
8334 numchild=N,children=[{name=NAME,
8335 numchild=N,type=TYPE},(repeats N times)]
8337 -var-list-children --all-values n
8338 numchild=N,children=[{name=NAME,
8339 numchild=N,value=VALUE,type=TYPE},(repeats N times)]
8341 The `-var-info-type' Command
8342 ----------------------------
8349 Returns the type of the specified variable NAME. The type is
8350 returned as a string in the same format as it is output by the GDB CLI:
8354 The `-var-info-expression' Command
8355 ----------------------------------
8360 -var-info-expression NAME
8362 Returns what is represented by the variable object NAME:
8364 lang=LANG-SPEC,exp=EXPRESSION
8366 where LANG-SPEC is `{"C" | "C++" | "Java"}'.
8368 The `-var-show-attributes' Command
8369 ----------------------------------
8374 -var-show-attributes NAME
8376 List attributes of the specified variable object NAME:
8378 status=ATTR [ ( ,ATTR )* ]
8380 where ATTR is `{ { editable | noneditable } | TBD }'.
8382 The `-var-evaluate-expression' Command
8383 --------------------------------------
8388 -var-evaluate-expression NAME
8390 Evaluates the expression that is represented by the specified
8391 variable object and returns its value as a string in the current format
8392 specified for the object:
8396 Note that one must invoke `-var-list-children' for a variable before
8397 the value of a child variable can be evaluated.
8399 The `-var-assign' Command
8400 -------------------------
8405 -var-assign NAME EXPRESSION
8407 Assigns the value of EXPRESSION to the variable object specified by
8408 NAME. The object must be `editable'. If the variable's value is
8409 altered by the assign, the variable will show up in any subsequent
8420 ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}]
8423 The `-var-update' Command
8424 -------------------------
8429 -var-update {NAME | "*"}
8431 Update the value of the variable object NAME by evaluating its
8432 expression after fetching all the new values from memory or registers.
8433 A `*' causes all existing variable objects to be updated.
8436 File: gdb.info, Node: Annotations, Next: GDB/MI, Prev: Emacs, Up: Top
8441 This chapter describes annotations in GDB. Annotations were designed
8442 to interface GDB to graphical user interfaces or other similar programs
8443 which want to interact with GDB at a relatively high level.
8445 The annotation mechanism has largely been superseeded by GDB/MI
8450 * Annotations Overview:: What annotations are; the general syntax.
8451 * Server Prefix:: Issuing a command without affecting user state.
8452 * Prompting:: Annotations marking GDB's need for input.
8453 * Errors:: Annotations for error messages.
8454 * Invalidation:: Some annotations describe things now invalid.
8455 * Annotations for Running::
8456 Whether the program is running, how it stopped, etc.
8457 * Source Annotations:: Annotations describing source code.
8460 File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
8462 What is an Annotation?
8463 ======================
8465 Annotations start with a newline character, two `control-z' characters,
8466 and the name of the annotation. If there is no additional information
8467 associated with this annotation, the name of the annotation is followed
8468 immediately by a newline. If there is additional information, the name
8469 of the annotation is followed by a space, the additional information,
8470 and a newline. The additional information cannot contain newline
8473 Any output not beginning with a newline and two `control-z'
8474 characters denotes literal output from GDB. Currently there is no need
8475 for GDB to output a newline followed by two `control-z' characters, but
8476 if there was such a need, the annotations could be extended with an
8477 `escape' annotation which means those three characters as output.
8479 The annotation LEVEL, which is specified using the `--annotate'
8480 command line option (*note Mode Options::), controls how much
8481 information GDB prints together with its prompt, values of expressions,
8482 source lines, and other types of output. Level 0 is for no anntations,
8483 level 1 is for use when GDB is run as a subprocess of GNU Emacs, level
8484 3 is the maximum annotation suitable for programs that control GDB, and
8485 level 2 annotations have been made obsolete (*note Limitations of the
8486 Annotation Interface: (annotate)Limitations.). This chapter describes
8487 level 3 annotations.
8489 A simple example of starting up GDB with annotations is:
8493 Copyright 2003 Free Software Foundation, Inc.
8494 GDB is free software, covered by the GNU General Public License,
8495 and you are welcome to change it and/or distribute copies of it
8496 under certain conditions.
8497 Type "show copying" to see the conditions.
8498 There is absolutely no warranty for GDB. Type "show warranty"
8500 This GDB was configured as "i386-pc-linux-gnu"
8510 Here `quit' is input to GDB; the rest is output from GDB. The three
8511 lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
8512 annotations; the rest is output from GDB.
8515 File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations
8520 To issue a command to GDB without affecting certain aspects of the
8521 state which is seen by users, prefix it with `server '. This means
8522 that this command will not affect the command history, nor will it
8523 affect GDB's notion of which command to repeat if <RET> is pressed on a
8526 The server prefix does not affect the recording of values into the
8527 value history; to print a value without recording it into the value
8528 history, use the `output' command instead of the `print' command.
8531 File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
8533 Annotation for GDB Input
8534 ========================
8536 When GDB prompts for input, it annotates this fact so it is possible to
8537 know when to send output, when the output from a given command is over,
8540 Different kinds of input each have a different "input type". Each
8541 input type has three annotations: a `pre-' annotation, which denotes
8542 the beginning of any prompt which is being output, a plain annotation,
8543 which denotes the end of the prompt, and then a `post-' annotation
8544 which denotes the end of any echo which may (or may not) be associated
8545 with the input. For example, the `prompt' input type features the
8546 following annotations:
8555 When GDB is prompting for a command (the main GDB prompt).
8558 When GDB prompts for a set of commands, like in the `commands'
8559 command. The annotations are repeated for each command which is
8563 When GDB wants the user to select between various overloaded
8567 When GDB wants the user to confirm a potentially dangerous
8570 `prompt-for-continue'
8571 When GDB is asking the user to press return to continue. Note:
8572 Don't expect this to work well; instead use `set height 0' to
8573 disable prompting. This is because the counting of lines is buggy
8574 in the presence of annotations.
8577 File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
8584 This annotation occurs right before GDB responds to an interrupt.
8588 This annotation occurs right before GDB responds to an error.
8590 Quit and error annotations indicate that any annotations which GDB
8591 was in the middle of may end abruptly. For example, if a
8592 `value-history-begin' annotation is followed by a `error', one cannot
8593 expect to receive the matching `value-history-end'. One cannot expect
8594 not to receive it either, however; an error annotation does not
8595 necessarily mean that GDB is immediately returning all the way to the
8598 A quit or error annotation may be preceded by
8602 Any output between that and the quit or error annotation is the error
8605 Warning messages are not yet annotated.
8608 File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
8610 Invalidation Notices
8611 ====================
8613 The following annotations say that certain pieces of state may have
8616 `^Z^Zframes-invalid'
8617 The frames (for example, output from the `backtrace' command) may
8620 `^Z^Zbreakpoints-invalid'
8621 The breakpoints may have changed. For example, the user just
8622 added or deleted a breakpoint.
8625 File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
8630 When the program starts executing due to a GDB command such as `step'
8635 is output. When the program stops,
8639 is output. Before the `stopped' annotation, a variety of
8640 annotations describe how the program stopped.
8642 `^Z^Zexited EXIT-STATUS'
8643 The program exited, and EXIT-STATUS is the exit status (zero for
8644 successful exit, otherwise nonzero).
8647 The program exited with a signal. After the `^Z^Zsignalled', the
8648 annotation continues:
8657 ^Z^Zsignal-string-end
8660 where NAME is the name of the signal, such as `SIGILL' or
8661 `SIGSEGV', and STRING is the explanation of the signal, such as
8662 `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT,
8663 MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
8667 The syntax of this annotation is just like `signalled', but GDB is
8668 just saying that the program received the signal, not that it was
8671 `^Z^Zbreakpoint NUMBER'
8672 The program hit breakpoint number NUMBER.
8674 `^Z^Zwatchpoint NUMBER'
8675 The program hit watchpoint number NUMBER.
8678 File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
8683 The following annotation is used instead of displaying source code:
8685 ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
8687 where FILENAME is an absolute file name indicating which source
8688 file, LINE is the line number within that file (where 1 is the first
8689 line in the file), CHARACTER is the character position within the file
8690 (where 0 is the first character in the file) (for most debug formats
8691 this will necessarily point to the beginning of a line), MIDDLE is
8692 `middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
8693 the beginning of the line, and ADDR is the address in the target
8694 program associated with the source which is being displayed. ADDR is
8695 in the form `0x' followed by one or more lowercase hex digits (note
8696 that this does not depend on the language).
8699 File: gdb.info, Node: GDB Bugs, Next: Formatting Documentation, Prev: GDB/MI, Up: Top
8701 Reporting Bugs in GDB
8702 *********************
8704 Your bug reports play an essential role in making GDB reliable.
8706 Reporting a bug may help you by bringing a solution to your problem,
8707 or it may not. But in any case the principal function of a bug report
8708 is to help the entire community by making the next version of GDB work
8709 better. Bug reports are your contribution to the maintenance of GDB.
8711 In order for a bug report to serve its purpose, you must include the
8712 information that enables us to fix the bug.
8716 * Bug Criteria:: Have you found a bug?
8717 * Bug Reporting:: How to report bugs
8720 File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
8722 Have you found a bug?
8723 =====================
8725 If you are not sure whether you have found a bug, here are some
8728 * If the debugger gets a fatal signal, for any input whatever, that
8729 is a GDB bug. Reliable debuggers never crash.
8731 * If GDB produces an error message for valid input, that is a bug.
8732 (Note that if you're cross debugging, the problem may also be
8733 somewhere in the connection to the target.)
8735 * If GDB does not produce an error message for invalid input, that
8736 is a bug. However, you should note that your idea of "invalid
8737 input" might be our idea of "an extension" or "support for
8738 traditional practice".
8740 * If you are an experienced user of debugging tools, your suggestions
8741 for improvement of GDB are welcome in any case.
8744 File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
8749 A number of companies and individuals offer support for GNU products.
8750 If you obtained GDB from a support organization, we recommend you
8751 contact that organization first.
8753 You can find contact information for many support companies and
8754 individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
8756 In any event, we also recommend that you submit bug reports for GDB.
8757 The prefered method is to submit them directly using GDB's Bugs web
8758 page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the
8759 e-mail gateway <bug-gdb@gnu.org> can be used.
8761 *Do not send bug reports to `info-gdb', or to `help-gdb', or to any
8762 newsgroups.* Most users of GDB do not want to receive bug reports.
8763 Those that do have arranged to receive `bug-gdb'.
8765 The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
8766 serves as a repeater. The mailing list and the newsgroup carry exactly
8767 the same messages. Often people think of posting bug reports to the
8768 newsgroup instead of mailing them. This appears to work, but it has one
8769 problem which can be crucial: a newsgroup posting often lacks a mail
8770 path back to the sender. Thus, if we need to ask for more information,
8771 we may be unable to reach you. For this reason, it is better to send
8772 bug reports to the mailing list.
8774 The fundamental principle of reporting bugs usefully is this:
8775 *report all the facts*. If you are not sure whether to state a fact or
8776 leave it out, state it!
8778 Often people omit facts because they think they know what causes the
8779 problem and assume that some details do not matter. Thus, you might
8780 assume that the name of the variable you use in an example does not
8781 matter. Well, probably it does not, but one cannot be sure. Perhaps
8782 the bug is a stray memory reference which happens to fetch from the
8783 location where that name is stored in memory; perhaps, if the name were
8784 different, the contents of that location would fool the debugger into
8785 doing the right thing despite the bug. Play it safe and give a
8786 specific, complete example. That is the easiest thing for you to do,
8787 and the most helpful.
8789 Keep in mind that the purpose of a bug report is to enable us to fix
8790 the bug. It may be that the bug has been reported previously, but
8791 neither you nor we can know that unless your bug report is complete and
8794 Sometimes people give a few sketchy facts and ask, "Does this ring a
8795 bell?" Those bug reports are useless, and we urge everyone to _refuse
8796 to respond to them_ except to chide the sender to report bugs properly.
8798 To enable us to fix the bug, you should include all these things:
8800 * The version of GDB. GDB announces it if you start with no
8801 arguments; you can also print it at any time using `show version'.
8803 Without this, we will not know whether there is any point in
8804 looking for the bug in the current version of GDB.
8806 * The type of machine you are using, and the operating system name
8809 * What compiler (and its version) was used to compile GDB--e.g.
8812 * What compiler (and its version) was used to compile the program
8813 you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
8814 C Compiler". For GCC, you can say `gcc --version' to get this
8815 information; for other compilers, see the documentation for those
8818 * The command arguments you gave the compiler to compile your
8819 example and observe the bug. For example, did you use `-O'? To
8820 guarantee you will not omit something important, list them all. A
8821 copy of the Makefile (or the output from make) is sufficient.
8823 If we were to try to guess the arguments, we would probably guess
8824 wrong and then we might not encounter the bug.
8826 * A complete input script, and all necessary source files, that will
8829 * A description of what behavior you observe that you believe is
8830 incorrect. For example, "It gets a fatal signal."
8832 Of course, if the bug is that GDB gets a fatal signal, then we
8833 will certainly notice it. But if the bug is incorrect output, we
8834 might not notice unless it is glaringly wrong. You might as well
8835 not give us a chance to make a mistake.
8837 Even if the problem you experience is a fatal signal, you should
8838 still say so explicitly. Suppose something strange is going on,
8839 such as, your copy of GDB is out of synch, or you have encountered
8840 a bug in the C library on your system. (This has happened!) Your
8841 copy might crash and ours would not. If you told us to expect a
8842 crash, then when ours fails to crash, we would know that the bug
8843 was not happening for us. If you had not told us to expect a
8844 crash, then we would not be able to draw any conclusion from our
8847 * If you wish to suggest changes to the GDB source, send us context
8848 diffs. If you even discuss something in the GDB source, refer to
8849 it by context, not by line number.
8851 The line numbers in our development sources will not match those
8852 in your sources. Your line numbers would convey no useful
8856 Here are some things that are not necessary:
8858 * A description of the envelope of the bug.
8860 Often people who encounter a bug spend a lot of time investigating
8861 which changes to the input file will make the bug go away and which
8862 changes will not affect it.
8864 This is often time consuming and not very useful, because the way
8865 we will find the bug is by running a single example under the
8866 debugger with breakpoints, not by pure deduction from a series of
8867 examples. We recommend that you save your time for something else.
8869 Of course, if you can find a simpler example to report _instead_
8870 of the original one, that is a convenience for us. Errors in the
8871 output will be easier to spot, running under the debugger will take
8872 less time, and so on.
8874 However, simplification is not vital; if you do not want to do
8875 this, report the bug anyway and send us the entire test case you
8878 * A patch for the bug.
8880 A patch for the bug does help us if it is a good one. But do not
8881 omit the necessary information, such as the test case, on the
8882 assumption that a patch is all we need. We might see problems
8883 with your patch and decide to fix the problem another way, or we
8884 might not understand it at all.
8886 Sometimes with a program as complicated as GDB it is very hard to
8887 construct an example that will make the program follow a certain
8888 path through the code. If you do not send us the example, we will
8889 not be able to construct one, so we will not be able to verify
8890 that the bug is fixed.
8892 And if we cannot understand what bug you are trying to fix, or why
8893 your patch should be an improvement, we will not install it. A
8894 test case will help us to understand.
8896 * A guess about what the bug is or what it depends on.
8898 Such guesses are usually wrong. Even we cannot guess right about
8899 such things without first using the debugger to find the facts.
8902 File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Formatting Documentation, Up: Top
8904 Command Line Editing
8905 ********************
8907 This chapter describes the basic features of the GNU command line
8912 * Introduction and Notation:: Notation used in this text.
8913 * Readline Interaction:: The minimum set of commands for editing a line.
8914 * Readline Init File:: Customizing Readline from a user's view.
8915 * Bindable Readline Commands:: A description of most of the Readline commands
8916 available for binding
8917 * Readline vi Mode:: A short description of how to make Readline
8918 behave like the vi editor.
8921 File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
8923 Introduction to Line Editing
8924 ============================
8926 The following paragraphs describe the notation used to represent
8929 The text `C-k' is read as `Control-K' and describes the character
8930 produced when the <k> key is pressed while the Control key is depressed.
8932 The text `M-k' is read as `Meta-K' and describes the character
8933 produced when the Meta key (if you have one) is depressed, and the <k>
8934 key is pressed. The Meta key is labeled <ALT> on many keyboards. On
8935 keyboards with two keys labeled <ALT> (usually to either side of the
8936 space bar), the <ALT> on the left side is generally set to work as a
8937 Meta key. The <ALT> key on the right may also be configured to work as
8938 a Meta key or may be configured as some other modifier, such as a
8939 Compose key for typing accented characters.
8941 If you do not have a Meta or <ALT> key, or another key working as a
8942 Meta key, the identical keystroke can be generated by typing <ESC>
8943 _first_, and then typing <k>. Either process is known as "metafying"
8946 The text `M-C-k' is read as `Meta-Control-k' and describes the
8947 character produced by "metafying" `C-k'.
8949 In addition, several keys have their own names. Specifically,
8950 <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
8951 when seen in this text, or in an init file (*note Readline Init File::).
8952 If your keyboard lacks a <LFD> key, typing <C-j> will produce the
8953 desired character. The <RET> key may be labeled <Return> or <Enter> on
8957 File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
8959 Readline Interaction
8960 ====================
8962 Often during an interactive session you type in a long line of text,
8963 only to notice that the first word on the line is misspelled. The
8964 Readline library gives you a set of commands for manipulating the text
8965 as you type it in, allowing you to just fix your typo, and not forcing
8966 you to retype the majority of the line. Using these editing commands,
8967 you move the cursor to the place that needs correction, and delete or
8968 insert the text of the corrections. Then, when you are satisfied with
8969 the line, you simply press <RET>. You do not have to be at the end of
8970 the line to press <RET>; the entire line is accepted regardless of the
8971 location of the cursor within the line.
8975 * Readline Bare Essentials:: The least you need to know about Readline.
8976 * Readline Movement Commands:: Moving about the input line.
8977 * Readline Killing Commands:: How to delete text, and how to get it back!
8978 * Readline Arguments:: Giving numeric arguments to commands.
8979 * Searching:: Searching through previous lines.
8982 File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
8984 Readline Bare Essentials
8985 ------------------------
8987 In order to enter characters into the line, simply type them. The typed
8988 character appears where the cursor was, and then the cursor moves one
8989 space to the right. If you mistype a character, you can use your erase
8990 character to back up and delete the mistyped character.
8992 Sometimes you may mistype a character, and not notice the error
8993 until you have typed several other characters. In that case, you can
8994 type `C-b' to move the cursor to the left, and then correct your
8995 mistake. Afterwards, you can move the cursor to the right with `C-f'.
8997 When you add text in the middle of a line, you will notice that
8998 characters to the right of the cursor are `pushed over' to make room
8999 for the text that you have inserted. Likewise, when you delete text
9000 behind the cursor, characters to the right of the cursor are `pulled
9001 back' to fill in the blank space created by the removal of the text. A
9002 list of the bare essentials for editing the text of an input line
9006 Move back one character.
9009 Move forward one character.
9011 <DEL> or <Backspace>
9012 Delete the character to the left of the cursor.
9015 Delete the character underneath the cursor.
9018 Insert the character into the line at the cursor.
9021 Undo the last editing command. You can undo all the way back to an
9024 (Depending on your configuration, the <Backspace> key be set to delete
9025 the character to the left of the cursor and the <DEL> key set to delete
9026 the character underneath the cursor, like `C-d', rather than the
9027 character to the left of the cursor.)
9030 File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
9032 Readline Movement Commands
9033 --------------------------
9035 The above table describes the most basic keystrokes that you need in
9036 order to do editing of the input line. For your convenience, many
9037 other commands have been added in addition to `C-b', `C-f', `C-d', and
9038 <DEL>. Here are some commands for moving more rapidly about the line.
9041 Move to the start of the line.
9044 Move to the end of the line.
9047 Move forward a word, where a word is composed of letters and
9051 Move backward a word.
9054 Clear the screen, reprinting the current line at the top.
9056 Notice how `C-f' moves forward a character, while `M-f' moves
9057 forward a word. It is a loose convention that control keystrokes
9058 operate on characters while meta keystrokes operate on words.
9061 File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
9063 Readline Killing Commands
9064 -------------------------
9066 "Killing" text means to delete the text from the line, but to save it
9067 away for later use, usually by "yanking" (re-inserting) it back into
9068 the line. (`Cut' and `paste' are more recent jargon for `kill' and
9071 If the description for a command says that it `kills' text, then you
9072 can be sure that you can get the text back in a different (or the same)
9075 When you use a kill command, the text is saved in a "kill-ring".
9076 Any number of consecutive kills save all of the killed text together, so
9077 that when you yank it back, you get it all. The kill ring is not line
9078 specific; the text that you killed on a previously typed line is
9079 available to be yanked back later, when you are typing another line.
9081 Here is the list of commands for killing text.
9084 Kill the text from the current cursor position to the end of the
9088 Kill from the cursor to the end of the current word, or, if between
9089 words, to the end of the next word. Word boundaries are the same
9090 as those used by `M-f'.
9093 Kill from the cursor the start of the current word, or, if between
9094 words, to the start of the previous word. Word boundaries are the
9095 same as those used by `M-b'.
9098 Kill from the cursor to the previous whitespace. This is
9099 different than `M-<DEL>' because the word boundaries differ.
9102 Here is how to "yank" the text back into the line. Yanking means to
9103 copy the most-recently-killed text from the kill buffer.
9106 Yank the most recently killed text back into the buffer at the
9110 Rotate the kill-ring, and yank the new top. You can only do this
9111 if the prior command is `C-y' or `M-y'.
9114 File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
9119 You can pass numeric arguments to Readline commands. Sometimes the
9120 argument acts as a repeat count, other times it is the sign of the
9121 argument that is significant. If you pass a negative argument to a
9122 command which normally acts in a forward direction, that command will
9123 act in a backward direction. For example, to kill text back to the
9124 start of the line, you might type `M-- C-k'.
9126 The general way to pass numeric arguments to a command is to type
9127 meta digits before the command. If the first `digit' typed is a minus
9128 sign (`-'), then the sign of the argument will be negative. Once you
9129 have typed one meta digit to get the argument started, you can type the
9130 remainder of the digits, and then the command. For example, to give
9131 the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
9132 will delete the next ten characters on the input line.