This is ./gdb.info, produced by makeinfo version 4.0b from gdb.texinfo. INFO-DIR-SECTION Programming & development tools. START-INFO-DIR-ENTRY * Gdb: (gdb). The GNU debugger. END-INFO-DIR-ENTRY This file documents the GNU debugger GDB. This is the Ninth Edition, January 2002, of `Debugging with GDB: the GNU Source-Level Debugger' for GDB Version 5.1.1. Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Free Software" and "Free Software Needs Free Documentation", with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. (a) The Free Software Foundation's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: Numbers, Up: Controlling GDB Optional warnings and messages ============================== By default, GDB is silent about its inner workings. If you are running on a slow machine, you may want to use the `set verbose' command. This makes GDB tell you when it does a lengthy internal operation, so you will not think it has crashed. Currently, the messages controlled by `set verbose' are those which announce that the symbol table for a source file is being read; see `symbol-file' in *Note Commands to specify files: Files. `set verbose on' Enables GDB output of certain informational messages. `set verbose off' Disables GDB output of certain informational messages. `show verbose' Displays whether `set verbose' is on or off. By default, if GDB encounters bugs in the symbol table of an object file, it is silent; but if you are debugging a compiler, you may find this information useful (*note Errors reading symbol files: Symbol Errors.). `set complaints LIMIT' Permits GDB to output LIMIT complaints about each type of unusual symbols before becoming silent about the problem. Set LIMIT to zero to suppress all complaints; set it to a large number to prevent complaints from being suppressed. `show complaints' Displays how many symbol complaints GDB is permitted to produce. By default, GDB is cautious, and asks what sometimes seems to be a lot of stupid questions to confirm certain commands. For example, if you try to run a program which is already running: (gdb) run The program being debugged has been started already. Start it from the beginning? (y or n) If you are willing to unflinchingly face the consequences of your own commands, you can disable this "feature": `set confirm off' Disables confirmation requests. `set confirm on' Enables confirmation requests (the default). `show confirm' Displays state of confirmation requests.  File: gdb.info, Node: Debugging Output, Prev: Messages/Warnings, Up: Controlling GDB Optional messages about internal happenings =========================================== `set debug arch' Turns on or off display of gdbarch debugging info. The default is off `show debug arch' Displays the current state of displaying gdbarch debugging info. `set debug event' Turns on or off display of GDB event debugging info. The default is off. `show debug event' Displays the current state of displaying GDB event debugging info. `set debug expression' Turns on or off display of GDB expression debugging info. The default is off. `show debug expression' Displays the current state of displaying GDB expression debugging info. `set debug overload' Turns on or off display of GDB C++ overload debugging info. This includes info such as ranking of functions, etc. The default is off. `show debug overload' Displays the current state of displaying GDB C++ overload debugging info. `set debug remote' Turns on or off display of reports on all packets sent back and forth across the serial line to the remote machine. The info is printed on the GDB standard output stream. The default is off. `show debug remote' Displays the state of display of remote packets. `set debug serial' Turns on or off display of GDB serial debugging info. The default is off. `show debug serial' Displays the current state of displaying GDB serial debugging info. `set debug target' Turns on or off display of GDB target debugging info. This info includes what is going on at the target level of GDB, as it happens. The default is off. `show debug target' Displays the current state of displaying GDB target debugging info. `set debug varobj' Turns on or off display of GDB variable object debugging info. The default is off. `show debug varobj' Displays the current state of displaying GDB variable object debugging info.  File: gdb.info, Node: Sequences, Next: TUI, Prev: Controlling GDB, Up: Top Canned Sequences of Commands **************************** Aside from breakpoint commands (*note Breakpoint command lists: Break Commands.), GDB provides two ways to store sequences of commands for execution as a unit: user-defined commands and command files. * Menu: * Define:: User-defined commands * Hooks:: User-defined command hooks * Command Files:: Command files * Output:: Commands for controlled output  File: gdb.info, Node: Define, Next: Hooks, Up: Sequences User-defined commands ===================== A "user-defined command" is a sequence of GDB commands to which you assign a new name as a command. This is done with the `define' command. User commands may accept up to 10 arguments separated by whitespace. Arguments are accessed within the user command via $ARG0...$ARG9. A trivial example: define adder print $arg0 + $arg1 + $arg2 To execute the command use: adder 1 2 3 This defines the command `adder', which prints the sum of its three arguments. Note the arguments are text substitutions, so they may reference variables, use complex expressions, or even perform inferior functions calls. `define COMMANDNAME' Define a command named COMMANDNAME. If there is already a command by that name, you are asked to confirm that you want to redefine it. The definition of the command is made up of other GDB command lines, which are given following the `define' command. The end of these commands is marked by a line containing `end'. `if' Takes a single argument, which is an expression to evaluate. It is followed by a series of commands that are executed only if the expression is true (nonzero). There can then optionally be a line `else', followed by a series of commands that are only executed if the expression was false. The end of the list is marked by a line containing `end'. `while' The syntax is similar to `if': the command takes a single argument, which is an expression to evaluate, and must be followed by the commands to execute, one per line, terminated by an `end'. The commands are executed repeatedly as long as the expression evaluates to true. `document COMMANDNAME' Document the user-defined command COMMANDNAME, so that it can be accessed by `help'. The command COMMANDNAME must already be defined. This command reads lines of documentation just as `define' reads the lines of the command definition, ending with `end'. After the `document' command is finished, `help' on command COMMANDNAME displays the documentation you have written. You may use the `document' command again to change the documentation of a command. Redefining the command with `define' does not change the documentation. `help user-defined' List all user-defined commands, with the first line of the documentation (if any) for each. `show user' `show user COMMANDNAME' Display the GDB commands used to define COMMANDNAME (but not its documentation). If no COMMANDNAME is given, display the definitions for all user-defined commands. When user-defined commands are executed, the commands of the definition are not printed. An error in any command stops execution of the user-defined command. If used interactively, commands that would ask for confirmation proceed without asking when used inside a user-defined command. Many GDB commands that normally print messages to say what they are doing omit the messages when used in a user-defined command.  File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences User-defined command hooks ========================== You may define "hooks", which are a special kind of user-defined command. Whenever you run the command `foo', if the user-defined command `hook-foo' exists, it is executed (with no arguments) before that command. A hook may also be defined which is run after the command you executed. Whenever you run the command `foo', if the user-defined command `hookpost-foo' exists, it is executed (with no arguments) after that command. Post-execution hooks may exist simultaneously with pre-execution hooks, for the same command. It is valid for a hook to call the command which it hooks. If this occurs, the hook is not re-executed, thereby avoiding infinte recursion. In addition, a pseudo-command, `stop' exists. Defining (`hook-stop') makes the associated commands execute every time execution stops in your program: before breakpoint commands are run, displays are printed, or the stack frame is printed. For example, to ignore `SIGALRM' signals while single-stepping, but treat them normally during normal execution, you could define: define hook-stop handle SIGALRM nopass end define hook-run handle SIGALRM pass end define hook-continue handle SIGLARM pass end As a further example, to hook at the begining and end of the `echo' command, and to add extra text to the beginning and end of the message, you could define: define hook-echo echo <<<--- end define hookpost-echo echo --->>>\n end (gdb) echo Hello World <<<---Hello World--->>> (gdb) You can define a hook for any single-word command in GDB, but not for command aliases; you should define a hook for the basic command name, e.g. `backtrace' rather than `bt'. If an error occurs during the execution of your hook, execution of GDB commands stops and GDB issues a prompt (before the command that you actually typed had a chance to run). If you try to define a hook which does not match any known command, you get a warning from the `define' command.  File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences Command files ============= A command file for GDB is a file of lines that are GDB commands. Comments (lines starting with `#') may also be included. An empty line in a command file does nothing; it does not mean to repeat the last command, as it would from the terminal. When you start GDB, it automatically executes commands from its "init files". These are files named `.gdbinit' on Unix and `gdb.ini' on DOS/Windows. During startup, GDB does the following: 1. Reads the init file (if any) in your home directory(1). 2. Processes command line options and operands. 3. Reads the init file (if any) in the current working directory. 4. Reads command files specified by the `-x' option. The init file in your home directory can set options (such as `set complaints') that affect subsequent processing of command line options and operands. Init files are not executed if you use the `-nx' option (*note Choosing modes: Mode Options.). On some configurations of GDB, the init file is known by a different name (these are typically environments where a specialized form of GDB may need to coexist with other forms, hence a different name for the specialized version's init file). These are the environments with special init file names: * VxWorks (Wind River Systems real-time OS): `.vxgdbinit' * OS68K (Enea Data Systems real-time OS): `.os68gdbinit' * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit' You can also request the execution of a command file with the `source' command: `source FILENAME' Execute the command file FILENAME. The lines in a command file are executed sequentially. They are not printed as they are executed. An error in any command terminates execution of the command file. Commands that would ask for confirmation if used interactively proceed without asking when used in a command file. Many GDB commands that normally print messages to say what they are doing omit the messages when called from command files. ---------- Footnotes ---------- (1) On DOS/Windows systems, the home directory is the one pointed to by the `HOME' environment variable.  File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences Commands for controlled output ============================== During the execution of a command file or a user-defined command, normal GDB output is suppressed; the only output that appears is what is explicitly printed by the commands in the definition. This section describes three commands useful for generating exactly the output you want. `echo TEXT' Print TEXT. Nonprinting characters can be included in TEXT using C escape sequences, such as `\n' to print a newline. *No newline is printed unless you specify one.* In addition to the standard C escape sequences, a backslash followed by a space stands for a space. This is useful for displaying a string with spaces at the beginning or the end, since leading and trailing spaces are otherwise trimmed from all arguments. To print ` and foo = ', use the command `echo \ and foo = \ '. A backslash at the end of TEXT can be used, as in C, to continue the command onto subsequent lines. For example, echo This is some text\n\ which is continued\n\ onto several lines.\n produces the same output as echo This is some text\n echo which is continued\n echo onto several lines.\n `output EXPRESSION' Print the value of EXPRESSION and nothing but that value: no newlines, no `$NN = '. The value is not entered in the value history either. *Note Expressions: Expressions, for more information on expressions. `output/FMT EXPRESSION' Print the value of EXPRESSION in format FMT. You can use the same formats as for `print'. *Note Output formats: Output Formats, for more information. `printf STRING, EXPRESSIONS...' Print the values of the EXPRESSIONS under the control of STRING. The EXPRESSIONS are separated by commas and may be either numbers or pointers. Their values are printed as specified by STRING, exactly as if your program were to execute the C subroutine printf (STRING, EXPRESSIONS...); For example, you can print two values in hex like this: printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo The only backslash-escape sequences that you can use in the format string are the simple ones that consist of backslash followed by a letter.  File: gdb.info, Node: TUI, Next: Emacs, Prev: Sequences, Up: Top GDB Text User Interface *********************** * Menu: * TUI Overview:: TUI overview * TUI Keys:: TUI key bindings * TUI Commands:: TUI specific commands * TUI Configuration:: TUI configuration variables The GDB Text User Interface, TUI in short, is a terminal interface which uses the `curses' library to show the source file, the assembly output, the program registers and GDB commands in separate text windows. The TUI is available only when GDB is configured with the `--enable-tui' configure option (*note Configure Options::).  File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI TUI overview ============ The TUI has two display modes that can be switched while GDB runs: * A curses (or TUI) mode in which it displays several text windows on the terminal. * A standard mode which corresponds to the GDB configured without the TUI. In the TUI mode, GDB can display several text window on the terminal: _command_ This window is the GDB command window with the GDB prompt and the GDB outputs. The GDB input is still managed using readline but through the TUI. The _command_ window is always visible. _source_ The source window shows the source file of the program. The current line as well as active breakpoints are displayed in this window. The current program position is shown with the `>' marker and active breakpoints are shown with `*' markers. _assembly_ The assembly window shows the disassembly output of the program. _register_ This window shows the processor registers. It detects when a register is changed and when this is the case, registers that have changed are highlighted. The source, assembly and register windows are attached to the thread and the frame position. They are updated when the current thread changes, when the frame changes or when the program counter changes. These three windows are arranged by the TUI according to several layouts. The layout defines which of these three windows are visible. The following layouts are available: * source * assembly * source and assembly * source and registers * assembly and registers  File: gdb.info, Node: TUI Keys, Next: TUI Commands, Prev: TUI Overview, Up: TUI TUI Key Bindings ================ The TUI installs several key bindings in the readline keymaps (*note Command Line Editing::). They allow to leave or enter in the TUI mode or they operate directly on the TUI layout and windows. The following key bindings are installed for both TUI mode and the GDB standard mode. `C-x C-a' `C-x a' `C-x A' Enter or leave the TUI mode. When the TUI mode is left, the curses window management is left and GDB operates using its standard mode writing on the terminal directly. When the TUI mode is entered, the control is given back to the curses windows. The screen is then refreshed. `C-x 1' Use a TUI layout with only one window. The layout will either be `source' or `assembly'. When the TUI mode is not active, it will switch to the TUI mode. Think of this key binding as the Emacs `C-x 1' binding. `C-x 2' Use a TUI layout with at least two windows. When the current layout shows already two windows, a next layout with two windows is used. When a new layout is chosen, one window will always be common to the previous layout and the new one. Think of it as the Emacs `C-x 2' binding. The following key bindings are handled only by the TUI mode: Scroll the active window one page up. Scroll the active window one page down. Scroll the active window one line up. Scroll the active window one line down. Scroll the active window one column left. Scroll the active window one column right. Refresh the screen. In the TUI mode, the arrow keys are used by the active window for scrolling. This means they are not available for readline. It is necessary to use other readline key bindings such as , , and .  File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Keys, Up: TUI TUI specific commands ===================== The TUI has specific commands to control the text windows. These commands are always available, that is they do not depend on the current terminal mode in which GDB runs. When GDB is in the standard mode, using these commands will automatically switch in the TUI mode. `layout next' Display the next layout. `layout prev' Display the previous layout. `layout src' Display the source window only. `layout asm' Display the assembly window only. `layout split' Display the source and assembly window. `layout regs' Display the register window together with the source or assembly window. `focus next | prev | src | asm | regs | split' Set the focus to the named window. This command allows to change the active window so that scrolling keys can be affected to another window. `refresh' Refresh the screen. This is similar to using key. `update' Update the source window and the current execution point. `winheight NAME +COUNT' `winheight NAME -COUNT' Change the height of the window NAME by COUNT lines. Positive counts increase the height, while negative counts decrease it.  File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI TUI configuration variables =========================== The TUI has several configuration variables that control the appearance of windows on the terminal. `set tui border-kind KIND' Select the border appearance for the source, assembly and register windows. The possible values are the following: `space' Use a space character to draw the border. `ascii' Use ascii characters + - and | to draw the border. `acs' Use the Alternate Character Set to draw the border. The border is drawn using character line graphics if the terminal supports them. `set tui active-border-mode MODE' Select the attributes to display the border of the active window. The possible values are `normal', `standout', `reverse', `half', `half-standout', `bold' and `bold-standout'. `set tui border-mode MODE' Select the attributes to display the border of other windows. The MODE can be one of the following: `normal' Use normal attributes to display the border. `standout' Use standout mode. `reverse' Use reverse video mode. `half' Use half bright mode. `half-standout' Use half bright and standout mode. `bold' Use extra bright or bold mode. `bold-standout' Use extra bright or bold and standout mode.  File: gdb.info, Node: Emacs, Next: Annotations, Prev: TUI, Up: Top Using GDB under GNU Emacs ************************* A special interface allows you to use GNU Emacs to view (and edit) the source files for the program you are debugging with GDB. To use this interface, use the command `M-x gdb' in Emacs. Give the executable file you want to debug as an argument. This command starts GDB as a subprocess of Emacs, with input and output through a newly created Emacs buffer. Using GDB under Emacs is just like using GDB normally except for two things: * All "terminal" input and output goes through the Emacs buffer. This applies both to GDB commands and their output, and to the input and output done by the program you are debugging. This is useful because it means that you can copy the text of previous commands and input them again; you can even use parts of the output in this way. All the facilities of Emacs' Shell mode are available for interacting with your program. In particular, you can send signals the usual way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop. * GDB displays source code through Emacs. Each time GDB displays a stack frame, Emacs automatically finds the source file for that frame and puts an arrow (`=>') at the left margin of the current line. Emacs uses a separate buffer for source display, and splits the screen to show both your GDB session and the source. Explicit GDB `list' or search commands still produce output as usual, but you probably have no reason to use them from Emacs. _Warning:_ If the directory where your program resides is not your current directory, it can be easy to confuse Emacs about the location of the source files, in which case the auxiliary display buffer does not appear to show your source. GDB can find programs by searching your environment's `PATH' variable, so the GDB input and output session proceeds normally; but Emacs does not get enough information back from GDB to locate the source files in this situation. To avoid this problem, either start GDB mode from the directory where your program resides, or specify an absolute file name when prompted for the `M-x gdb' argument. A similar confusion can result if you use the GDB `file' command to switch to debugging a program in some other location, from an existing GDB buffer in Emacs. By default, `M-x gdb' calls the program called `gdb'. If you need to call GDB by a different name (for example, if you keep several configurations around, with different names) you can set the Emacs variable `gdb-command-name'; for example, (setq gdb-command-name "mygdb") (preceded by `M-:' or `ESC :', or typed in the `*scratch*' buffer, or in your `.emacs' file) makes Emacs call the program named "`mygdb'" instead. In the GDB I/O buffer, you can use these special Emacs commands in addition to the standard Shell mode commands: `C-h m' Describe the features of Emacs' GDB Mode. `M-s' Execute to another source line, like the GDB `step' command; also update the display window to show the current file and location. `M-n' Execute to next source line in this function, skipping all function calls, like the GDB `next' command. Then update the display window to show the current file and location. `M-i' Execute one instruction, like the GDB `stepi' command; update display window accordingly. `M-x gdb-nexti' Execute to next instruction, using the GDB `nexti' command; update display window accordingly. `C-c C-f' Execute until exit from the selected stack frame, like the GDB `finish' command. `M-c' Continue execution of your program, like the GDB `continue' command. _Warning:_ In Emacs v19, this command is `C-c C-p'. `M-u' Go up the number of frames indicated by the numeric argument (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' command. _Warning:_ In Emacs v19, this command is `C-c C-u'. `M-d' Go down the number of frames indicated by the numeric argument, like the GDB `down' command. _Warning:_ In Emacs v19, this command is `C-c C-d'. `C-x &' Read the number where the cursor is positioned, and insert it at the end of the GDB I/O buffer. For example, if you wish to disassemble code around an address that was displayed earlier, type `disassemble'; then move the cursor to the address display, and pick up the argument for `disassemble' by typing `C-x &'. You can customize this further by defining elements of the list `gdb-print-command'; once it is defined, you can format or otherwise process numbers picked up by `C-x &' before they are inserted. A numeric argument to `C-x &' indicates that you wish special formatting, and also acts as an index to pick an element of the list. If the list element is a string, the number to be inserted is formatted using the Emacs function `format'; otherwise the number is passed as an argument to the corresponding list element. In any source file, the Emacs command `C-x SPC' (`gdb-break') tells GDB to set a breakpoint on the source line point is on. If you accidentally delete the source-display buffer, an easy way to get it back is to type the command `f' in the GDB buffer, to request a frame display; when you run under Emacs, this recreates the source buffer if necessary to show you the context of the current frame. The source files displayed in Emacs are in ordinary Emacs buffers which are visiting the source files in the usual way. You can edit the files with these buffers if you wish; but keep in mind that GDB communicates with Emacs in terms of line numbers. If you add or delete lines from the text, the line numbers that GDB knows cease to correspond properly with the code.  File: gdb.info, Node: Annotations, Next: GDB/MI, Prev: Emacs, Up: Top GDB Annotations *************** This chapter describes annotations in GDB. Annotations are designed to interface GDB to graphical user interfaces or other similar programs which want to interact with GDB at a relatively high level. * Menu: * Annotations Overview:: What annotations are; the general syntax. * Server Prefix:: Issuing a command without affecting user state. * Value Annotations:: Values are marked as such. * Frame Annotations:: Stack frames are annotated. * Displays:: GDB can be told to display something periodically. * Prompting:: Annotations marking GDB's need for input. * Errors:: Annotations for error messages. * Breakpoint Info:: Information on breakpoints. * Invalidation:: Some annotations describe things now invalid. * Annotations for Running:: Whether the program is running, how it stopped, etc. * Source Annotations:: Annotations describing source code. * TODO:: Annotations which might be added in the future.  File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations What is an Annotation? ====================== To produce annotations, start GDB with the `--annotate=2' option. Annotations start with a newline character, two `control-z' characters, and the name of the annotation. If there is no additional information associated with this annotation, the name of the annotation is followed immediately by a newline. If there is additional information, the name of the annotation is followed by a space, the additional information, and a newline. The additional information cannot contain newline characters. Any output not beginning with a newline and two `control-z' characters denotes literal output from GDB. Currently there is no need for GDB to output a newline followed by two `control-z' characters, but if there was such a need, the annotations could be extended with an `escape' annotation which means those three characters as output. A simple example of starting up GDB with annotations is: $ gdb --annotate=2 GNU GDB 5.0 Copyright 2000 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "sparc-sun-sunos4.1.3" ^Z^Zpre-prompt (gdb) ^Z^Zprompt quit ^Z^Zpost-prompt $ Here `quit' is input to GDB; the rest is output from GDB. The three lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are annotations; the rest is output from GDB.  File: gdb.info, Node: Server Prefix, Next: Value Annotations, Prev: Annotations Overview, Up: Annotations The Server Prefix ================= To issue a command to GDB without affecting certain aspects of the state which is seen by users, prefix it with `server '. This means that this command will not affect the command history, nor will it affect GDB's notion of which command to repeat if is pressed on a line by itself. The server prefix does not affect the recording of values into the value history; to print a value without recording it into the value history, use the `output' command instead of the `print' command.  File: gdb.info, Node: Value Annotations, Next: Frame Annotations, Prev: Server Prefix, Up: Annotations Values ====== When a value is printed in various contexts, GDB uses annotations to delimit the value from the surrounding text. If a value is printed using `print' and added to the value history, the annotation looks like ^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS HISTORY-STRING ^Z^Zvalue-history-value THE-VALUE ^Z^Zvalue-history-end where HISTORY-NUMBER is the number it is getting in the value history, HISTORY-STRING is a string, such as `$5 = ', which introduces the value to the user, THE-VALUE is the output corresponding to the value itself, and VALUE-FLAGS is `*' for a value which can be dereferenced and `-' for a value which cannot. If the value is not added to the value history (it is an invalid float or it is printed with the `output' command), the annotation is similar: ^Z^Zvalue-begin VALUE-FLAGS THE-VALUE ^Z^Zvalue-end When GDB prints an argument to a function (for example, in the output from the `backtrace' command), it annotates it as follows: ^Z^Zarg-begin ARGUMENT-NAME ^Z^Zarg-name-end SEPARATOR-STRING ^Z^Zarg-value VALUE-FLAGS THE-VALUE ^Z^Zarg-end where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is text which separates the name from the value for the user's benefit (such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a `value-history-begin' annotation. When printing a structure, GDB annotates it as follows: ^Z^Zfield-begin VALUE-FLAGS FIELD-NAME ^Z^Zfield-name-end SEPARATOR-STRING ^Z^Zfield-value THE-VALUE ^Z^Zfield-end where FIELD-NAME is the name of the field, SEPARATOR-STRING is text which separates the name from the value for the user's benefit (such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a `value-history-begin' annotation. When printing an array, GDB annotates it as follows: ^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS where ARRAY-INDEX is the index of the first element being annotated and VALUE-FLAGS has the same meaning as in a `value-history-begin' annotation. This is followed by any number of elements, where is element can be either a single element: `,' WHITESPACE ; omitted for the first element THE-VALUE ^Z^Zelt or a repeated element `,' WHITESPACE ; omitted for the first element THE-VALUE ^Z^Zelt-rep NUMBER-OF-REPITITIONS REPETITION-STRING ^Z^Zelt-rep-end In both cases, THE-VALUE is the output for the value of the element and WHITESPACE can contain spaces, tabs, and newlines. In the repeated case, NUMBER-OF-REPITITONS is the number of consecutive array elements which contain that value, and REPETITION-STRING is a string which is designed to convey to the user that repitition is being depicted. Once all the array elements have been output, the array annotation is ended with ^Z^Zarray-section-end  File: gdb.info, Node: Frame Annotations, Next: Displays, Prev: Value Annotations, Up: Annotations Frames ====== Whenever GDB prints a frame, it annotates it. For example, this applies to frames printed when GDB stops, output from commands such as `backtrace' or `up', etc. The frame annotation begins with ^Z^Zframe-begin LEVEL ADDRESS LEVEL-STRING where LEVEL is the number of the frame (0 is the innermost frame, and other frames have positive numbers), ADDRESS is the address of the code executing in that frame, and LEVEL-STRING is a string designed to convey the level to the user. ADDRESS is in the form `0x' followed by one or more lowercase hex digits (note that this does not depend on the language). The frame ends with ^Z^Zframe-end Between these annotations is the main body of the frame, which can consist of * ^Z^Zfunction-call FUNCTION-CALL-STRING where FUNCTION-CALL-STRING is text designed to convey to the user that this frame is associated with a function call made by GDB to a function in the program being debugged. * ^Z^Zsignal-handler-caller SIGNAL-HANDLER-CALLER-STRING where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to the user that this frame is associated with whatever mechanism is used by this operating system to call a signal handler (it is the frame which calls the signal handler, not the frame for the signal handler itself). * A normal frame. This can optionally (depending on whether this is thought of as interesting information for the user to see) begin with ^Z^Zframe-address ADDRESS ^Z^Zframe-address-end SEPARATOR-STRING where ADDRESS is the address executing in the frame (the same address as in the `frame-begin' annotation, but printed in a form which is intended for user consumption--in particular, the syntax varies depending on the language), and SEPARATOR-STRING is a string intended to separate this address from what follows for the user's benefit. Then comes ^Z^Zframe-function-name FUNCTION-NAME ^Z^Zframe-args ARGUMENTS where FUNCTION-NAME is the name of the function executing in the frame, or `??' if not known, and ARGUMENTS are the arguments to the frame, with parentheses around them (each argument is annotated individually as well, *note Value Annotations::). If source information is available, a reference to it is then printed: ^Z^Zframe-source-begin SOURCE-INTRO-STRING ^Z^Zframe-source-file FILENAME ^Z^Zframe-source-file-end : ^Z^Zframe-source-line LINE-NUMBER ^Z^Zframe-source-end where SOURCE-INTRO-STRING separates for the user's benefit the reference from the text which precedes it, FILENAME is the name of the source file, and LINE-NUMBER is the line number within that file (the first line is line 1). If GDB prints some information about where the frame is from (which library, which load segment, etc.; currently only done on the RS/6000), it is annotated with ^Z^Zframe-where INFORMATION Then, if source is to actually be displayed for this frame (for example, this is not true for output from the `backtrace' command), then a `source' annotation (*note Source Annotations::) is displayed. Unlike most annotations, this is output instead of the normal text which would be output, not in addition.  File: gdb.info, Node: Displays, Next: Prompting, Prev: Frame Annotations, Up: Annotations Displays ======== When GDB is told to display something using the `display' command, the results of the display are annotated: ^Z^Zdisplay-begin NUMBER ^Z^Zdisplay-number-end NUMBER-SEPARATOR ^Z^Zdisplay-format FORMAT ^Z^Zdisplay-expression EXPRESSION ^Z^Zdisplay-expression-end EXPRESSION-SEPARATOR ^Z^Zdisplay-value VALUE ^Z^Zdisplay-end where NUMBER is the number of the display, NUMBER-SEPARATOR is intended to separate the number from what follows for the user, FORMAT includes information such as the size, format, or other information about how the value is being displayed, EXPRESSION is the expression being displayed, EXPRESSION-SEPARATOR is intended to separate the expression from the text that follows for the user, and VALUE is the actual value being displayed.  File: gdb.info, Node: Prompting, Next: Errors, Prev: Displays, Up: Annotations Annotation for GDB Input ======================== When GDB prompts for input, it annotates this fact so it is possible to know when to send output, when the output from a given command is over, etc. Different kinds of input each have a different "input type". Each input type has three annotations: a `pre-' annotation, which denotes the beginning of any prompt which is being output, a plain annotation, which denotes the end of the prompt, and then a `post-' annotation which denotes the end of any echo which may (or may not) be associated with the input. For example, the `prompt' input type features the following annotations: ^Z^Zpre-prompt ^Z^Zprompt ^Z^Zpost-prompt The input types are `prompt' When GDB is prompting for a command (the main GDB prompt). `commands' When GDB prompts for a set of commands, like in the `commands' command. The annotations are repeated for each command which is input. `overload-choice' When GDB wants the user to select between various overloaded functions. `query' When GDB wants the user to confirm a potentially dangerous operation. `prompt-for-continue' When GDB is asking the user to press return to continue. Note: Don't expect this to work well; instead use `set height 0' to disable prompting. This is because the counting of lines is buggy in the presence of annotations.  File: gdb.info, Node: Errors, Next: Breakpoint Info, Prev: Prompting, Up: Annotations Errors ====== ^Z^Zquit This annotation occurs right before GDB responds to an interrupt. ^Z^Zerror This annotation occurs right before GDB responds to an error. Quit and error annotations indicate that any annotations which GDB was in the middle of may end abruptly. For example, if a `value-history-begin' annotation is followed by a `error', one cannot expect to receive the matching `value-history-end'. One cannot expect not to receive it either, however; an error annotation does not necessarily mean that GDB is immediately returning all the way to the top level. A quit or error annotation may be preceded by ^Z^Zerror-begin Any output between that and the quit or error annotation is the error message. Warning messages are not yet annotated.  File: gdb.info, Node: Breakpoint Info, Next: Invalidation, Prev: Errors, Up: Annotations Information on Breakpoints ========================== The output from the `info breakpoints' command is annotated as follows: ^Z^Zbreakpoints-headers HEADER-ENTRY ^Z^Zbreakpoints-table where HEADER-ENTRY has the same syntax as an entry (see below) but instead of containing data, it contains strings which are intended to convey the meaning of each field to the user. This is followed by any number of entries. If a field does not apply for this entry, it is omitted. Fields may contain trailing whitespace. Each entry consists of: ^Z^Zrecord ^Z^Zfield 0 NUMBER ^Z^Zfield 1 TYPE ^Z^Zfield 2 DISPOSITION ^Z^Zfield 3 ENABLE ^Z^Zfield 4 ADDRESS ^Z^Zfield 5 WHAT ^Z^Zfield 6 FRAME ^Z^Zfield 7 CONDITION ^Z^Zfield 8 IGNORE-COUNT ^Z^Zfield 9 COMMANDS Note that ADDRESS is intended for user consumption--the syntax varies depending on the language. The output ends with ^Z^Zbreakpoints-table-end  File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Breakpoint Info, Up: Annotations Invalidation Notices ==================== The following annotations say that certain pieces of state may have changed. `^Z^Zframes-invalid' The frames (for example, output from the `backtrace' command) may have changed. `^Z^Zbreakpoints-invalid' The breakpoints may have changed. For example, the user just added or deleted a breakpoint.  File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations Running the Program =================== When the program starts executing due to a GDB command such as `step' or `continue', ^Z^Zstarting is output. When the program stops, ^Z^Zstopped is output. Before the `stopped' annotation, a variety of annotations describe how the program stopped. `^Z^Zexited EXIT-STATUS' The program exited, and EXIT-STATUS is the exit status (zero for successful exit, otherwise nonzero). `^Z^Zsignalled' The program exited with a signal. After the `^Z^Zsignalled', the annotation continues: INTRO-TEXT ^Z^Zsignal-name NAME ^Z^Zsignal-name-end MIDDLE-TEXT ^Z^Zsignal-string STRING ^Z^Zsignal-string-end END-TEXT where NAME is the name of the signal, such as `SIGILL' or `SIGSEGV', and STRING is the explanation of the signal, such as `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT, MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no particular format. `^Z^Zsignal' The syntax of this annotation is just like `signalled', but GDB is just saying that the program received the signal, not that it was terminated with it. `^Z^Zbreakpoint NUMBER' The program hit breakpoint number NUMBER. `^Z^Zwatchpoint NUMBER' The program hit watchpoint number NUMBER.  File: gdb.info, Node: Source Annotations, Next: TODO, Prev: Annotations for Running, Up: Annotations Displaying Source ================= The following annotation is used instead of displaying source code: ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR where FILENAME is an absolute file name indicating which source file, LINE is the line number within that file (where 1 is the first line in the file), CHARACTER is the character position within the file (where 0 is the first character in the file) (for most debug formats this will necessarily point to the beginning of a line), MIDDLE is `middle' if ADDR is in the middle of the line, or `beg' if ADDR is at the beginning of the line, and ADDR is the address in the target program associated with the source which is being displayed. ADDR is in the form `0x' followed by one or more lowercase hex digits (note that this does not depend on the language).  File: gdb.info, Node: TODO, Prev: Source Annotations, Up: Annotations Annotations We Might Want in the Future ======================================= - target-invalid the target might have changed (registers, heap contents, or execution status). For performance, we might eventually want to hit `registers-invalid' and `all-registers-invalid' with greater precision - systematic annotation for set/show parameters (including invalidation notices). - similarly, `info' returns a list of candidates for invalidation notices.  File: gdb.info, Node: GDB/MI, Next: GDB Bugs, Prev: Annotations, Up: Top The GDB/MI Interface ******************** Function and Purpose ==================== GDB/MI is a line based machine oriented text interface to GDB. It is specifically intended to support the development of systems which use the debugger as just one small component of a larger system. This chapter is a specification of the GDB/MI interface. It is written in the form of a reference manual. Note that GDB/MI is still under construction, so some of the features described below are incomplete and subject to change. Notation and Terminology ======================== This chapter uses the following notation: * `|' separates two alternatives. * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or may not be given. * `( GROUP )*' means that GROUP inside the parentheses may repeat zero or more times. * `( GROUP )+' means that GROUP inside the parentheses may repeat one or more times. * `"STRING"' means a literal STRING. Acknowledgments =============== In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and Elena Zannoni. * Menu: * GDB/MI Command Syntax:: * GDB/MI Compatibility with CLI:: * GDB/MI Output Records:: * GDB/MI Command Description Format:: * GDB/MI Breakpoint Table Commands:: * GDB/MI Data Manipulation:: * GDB/MI Program Control:: * GDB/MI Miscellaneous Commands:: * GDB/MI Stack Manipulation:: * GDB/MI Symbol Query:: * GDB/MI Target Manipulation:: * GDB/MI Thread Commands:: * GDB/MI Tracepoint Commands:: * GDB/MI Variable Objects::  File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Up: GDB/MI GDB/MI Command Syntax ===================== * Menu: * GDB/MI Input Syntax:: * GDB/MI Output Syntax:: * GDB/MI Simple Examples::  File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax GDB/MI Input Syntax ------------------- `COMMAND ==>' `CLI-COMMAND | MI-COMMAND' `CLI-COMMAND ==>' `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB CLI command. `MI-COMMAND ==>' `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " PARAMETER )* NL' `TOKEN ==>' "any sequence of digits" `OPTION ==>' `"-" PARAMETER [ " " PARAMETER ]' `PARAMETER ==>' `NON-BLANK-SEQUENCE | C-STRING' `OPERATION ==>' _any of the operations described in this chapter_ `NON-BLANK-SEQUENCE ==>' _anything, provided it doesn't contain special characters such as "-", NL, """ and of course " "_ `C-STRING ==>' `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' `NL ==>' `CR | CR-LF' Notes: * The CLI commands are still handled by the MI interpreter; their output is described below. * The `TOKEN', when present, is passed back when the command finishes. * Some MI commands accept optional arguments as part of the parameter list. Each option is identified by a leading `-' (dash) and may be followed by an optional argument parameter. Options occur first in the parameter list and can be delimited from normal parameters using `--' (this is useful when some parameters begin with a dash). Pragmatics: * We want easy access to the existing CLI syntax (for debugging). * We want it to be easy to spot a MI operation.