GDB/MI Interface | HP gnu source-level debugger 5992-4701 specification

21 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.

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.

21.1 GDB/MI Command Syntax

21.1.1 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 does not contain special
	characters such as “-”, nl, """ and of course “”
c-string	""" seven-bit-iso-c-string-content """
nl	CR CR-LF

21.1 GDB/MI Command Syntax 307

Page 307

Image 307

HP gnu source-level debugger 5992-4701 manual GDB/MI Interface, 21.1 GDB/MI Command Syntax

Contents

Debugging with GDB Manual Page Table of Contents Stack frames Continuing and stepping SignalsPrint settings Value history Breakpoints Examining the Symbol Table Specifying a Debugging Target Commands for heap profiling Stop when freeing unallocated or deallocated blocksScramble previous memory contents at malloc/free calls Batch Mode Example Illustrating Execution Path Recovery Support for the info target CommandSupport for the dumpcore command Enhancements to the dumpcore command Detecting memory leaks using GDB under Aries Command for evaluating the address of an expressionSupport for steplast command for C and C++ Debugging the application using GDB under Aries HP-UX Terminal User Interface Command files 289 Commands for controlled output 290 Miscellaneous commands 265 16.3Setting Command History Feature in GDB 281 17.4 User-defined commands 287 18.2 304 20.7 Errors 302 20.822.2 How to report bugs 361 20.9 Invalidation notices 303 List of Tables List of Examples Free Software Summary of GDBContributors to GDB Page Contributors to GDB Page Sample GDB Session Let us use GDB to try to see what is going onLoading the Executable Running the executable under GDB Setting Display widthSetting Breakpoints Here we describe how to set a breakpoint Examining the Stack Stepping into a subroutinePrinting Variable Values Listing Source Code Setting Variable Values During a Session Gdb c Continuing Definebaz,defnQUOTEfooUNQUOTE Baz Page Invoking GDB Getting In and Out of GDB Files Choosing files Choosing modes Processed. See Command files Like two `\032 characters, followed by the file name GNU Emacs sets this option when it runs GDB as aLine number in a standard, recognizable fashion each Time a stack frame is displayed which includes each Emacs Redirecting WDB input and output to a file Quitting GDBInterface Shell commands Page Command syntax GDB CommandsCommand completion GDB sounds bell press TAB again, to see Getting help Short list of named classes of commandsHelp , h This is intended for use by GNU Emacs Apropos reloadResults Complete Getting help Page Arguments, so that you may use normal Running Programs Under GDBCompiling for debugging Starting your program Your program. SeeProgram Environment See Arguments To Your ProgramDirectory Program Environment Arguments To Your ProgramProgram. See Program Input and Output Do not supply varname, print the names For example, this commandDisplay the list of search paths for executables Path environment variable Program Input and Output Working directory Debugging a Running Process Killing the child process Debugging programs with multiple threads New process 35 thread Display a summary of all threads currently Here are commands to get more information about threadsThread apply command allows you to With the command argument threadno Debugging programs with multiple processes Fork. The child process runs New process. The mode can beUnimpeded. This is the default Set the debugger response to a program call Breakpoints Stopping and Continuing Setting breakpoints Breakpoints See Break conditions page 59, for more Breakpoint is BreakpointCatchpoint Whether Breakpoints are When hitEnabled Marked to be Setting catchpoints Shared library, or the unloading Call to vfork. This is currently onlyIs currently only available for HP-UX Unloading of any dynamically loaded Disabling breakpoints Deleting breakpointsSelecting a frame page 73 . When Break conditions Use condition, GDB checks expression Breakpoint, GDB prints an error messageNo symbol foo in current context Stops your program only if the value Breakpoint command lists Breakpoint menus Cannot insert breakpoints Conditions Continuing and stepping Function Setting breakpoints page 52. This form of the command Stops. See Automatic display Signals Info handle is an alias for info signals Stopping and starting multi-thread programs Stopping and Continuing Stack frames Examining the Stack Stacks Without frames Commands for Examining the StackBacktraces Selecting a frame Information about a frame Have existed longer. n defaults to oneWhen used without any argument, this command does not With an argument, this command is used to select a stack Setting catchpoints Page Show listsize Examining Source FilesPrinting source lines List Searching source files Specifying source directories Show directories Source and machine codeContains Disassembling the program via Set disassembly-flavorDisassemble or x/i commands Select the instruction set to use whenPage To See Artificial arrays page 85, for more information Following forms of print command are supportedExamining Data Expressions Normally supposed to reside at addr Where it is defined. See Program variablesProgram variables Type addr Artificial arrays You can print the contents of array with Output formats Time you use either x or print Machine instruction. The default isExamining memory Print, s null-terminated string, or However, the count n must come first wx4 does not work For fmt i or s, or including a unit-size or a number Automatic displayFor fmt specifying only a display format and not a size or See Output formats Print settings Address A symbol. This is the defaultFile name and line number of a symbol Symbolic form of an address Short strings. The default is off Default is offStrings. When GDB starts, this limit is set to Setting number-of-elementsto zero Default This is the default formatShow which format GDB is using to print Print using only seven-bit characters if this Would print These settings are of interest when debugging C++ programsDefault is on Show whether C++ names in assembly listings Value history Convenience variables Program being debugged terminates Command, in which case it is a pointer to the type of $Format in which the data was printed $exitcode Or add four to the stack pointer3 with3with RegistersInfo registers Info all-registers Info registers regname Or print the instruction to be executed next with This is what the macro produces Printing Floating Point ValuesFloating point hardware To get the bit pattern, try the following macro 100 Cpp Using GDB with Different LanguagesSwitching between source languages List of filename extensions and languages Files Setting the working languageNot skip over function prologues when stepping Having GDB infer the source language Type and range checking Displaying the languageAn overview of type checking An overview of range checking Supported languages C++ Types and pointer types Expressions is 0 for false and non-zero for trueNon-zero for true Left shift, and right shift. Defined on integral types C++ constants Class typesDouble colons also represent the GDB scope operator see Expressions page 83. Same precedence as , above GDB expression handling can interpret most C++ expressions 1.3 C++ expressions Printing the variable or class returns C++ defaultsC++ type and range checks See Breakpoint menus GDB features for C++GDB and C Breakpoint menus Fortran types FortranFortran types supported Greater than or equal to Less thanLess than or equal to Greater than Commonblockname Fortran special issuesBlock Examining the Symbol Table For example, for this variable declaration Two commands give this outputAs with whatis, using ptype without an Symbols will be read when needed Once. This is the default Allow GDB to reload the symbols forReplace symbol definitions Do not replace symbol Class, or union―for example, struct SettingIs in another source file. The default is on Tell GDB to resolve opaque types. An opaque Assignment to variables Altering Execution Stores the value 4 into that memory location Continuing at a different address You can use the following command to return from a function Giving your program a signalReturning from a function Is used as the return value from the function value Calling program functionsPatching programs Return , return Patching programs 124 GDB Files Commands to specify files See Optional warnings and messages Map in symbol information from this auxiliary Option with any of the commands that loadGDB has the entire symbol table available Write the symbols for your program into a Section New library has been loaded, until the symbol Symbols were loaded. Both the commands listTo display or set the threshold, use the commands If threshold is nonzero, symbols from all Megabytes Names where the desired shared libraries reside. GDBSearching the default system directories Specifying shared library locations Verbose on. See Optional warnings Errors reading symbol filesMessages Debug your program, though certain symbols Symbol scope block as starting on the previousIs the symbol type of the uncomprehended GDB circumvents the error by ignoring this Specifying a Debugging Target Commands for managing targetsActive targets See Commands to specify files Choosing target byte order Display GDBs current idea of the target byte order Instruct GDB to assume the target is big-endianInstruct GDB to assume the target is little-endian Executable Summary of HP Enhancements to GDB HP-UX Configuration-Specific Information Support for setting breakpoints using shared library name Implementation of ask mode for set follow-fork-mode Command watchtarget Linker Dependencies HP-UX dependenciesDependent Standard Library Routines for Run Time Checking Getpid Close Srand Strchr Abort Unlink Atoi Supported Platforms and Modes GDB location HP-UX targetsSupport for Alternate root WDB Location Bin $WDBROOT/bin Specifying object file directoriesLibrtc.sl location $WDBROOT/bin Opt/langtools/ n/a None Fix and continue debugging Fix and Continue restrictions Fix and Continue compiler dependencies Using Fix and Continue Compile the program Example Fix and Continue sessionRun the program Make the necessary changes. In this case, add return total Gdb b mainGdb run Gdb edit Inline Debugging in HP 9000 Systems Inline SupportGdb q Step next list backtrace frame n info locals info args Breakpoint info frame disassemblyFollowing options available for the set inline-debugcommand Inline Debugging in Integrity Systems Debugging Inline Functions in Integrity Systems Limitations Debugging Macros Info frame disassemblyViewing and Evaluating Macro Definitions Evaluating Macros Compiler Options to Enable Macro DebuggingDebug=none Examples for Macro Debugging HP-UX Configuration-Specific Information Debugging Memory Problems Memory debugging restrictions When to suspect a memory leakMemory Debugging Methodologies Debugging Memory in Interactive Mode Command discards the data existing in the file Displays all current settings for memoryThis command are ignored from report. If Heap growth. The default value is 100. Every Debugging Memory Problems Such as attempting to access space that is freed Debugging when the string option is set forHave occurred and WDB reports the problem Specific pattern when it is allocated or User-specified value Use the info command to show list of memory leaksIf the user specifies a value less than 16 for Number of bytes, the debugger ignores it Setting Configuration Options for Batch Mode Debugging Memory in Batch ModeGdb info leak Sets the number of frames to be printed for leak context Framecount=noframes or set heap-check frame-count noframes For 64-bit IPF applications For 32 bit IPF applicationsFor 64 bit IPF applications For 64 bit PA applications Ldpreload Environment variable setting for Batch mode debugging Stderr error message goes to stderr Aborts execution when heap objectsAborts execution when out of memory Log file for batch mode must be Example for Batch Mode RTC Complete one of the following steps Preload the librtc library as follows Rtcconfig file should contain entries such as the followingRun the program as follows For 32 bit PA applications Specifying minimum leak size Configuring memory debugging settingsRun the program Start a debugging session as follows Specifying the stack depth Specifying minimum block size Stop when freeing unallocated or deallocated blocksScenarios in memory debugging For example, if you use Detect dangling pointers and dangling blocks Scramble previous memory contents at malloc/free callsInteractive debugging mode set heap-check scramble on off Syntax Detect in-block corruption of freed blocks Off Memory Debugging Commands in Interactive and Batch Mode As the start of the heap, end of the heap, heap Commands for heap profilingPoint you use the info heap command Heap Profiling Set a breakpoint This example shows how to use this feature on HP-UX Changes for a given run Commands to track the change in data segment value Support for Enabling and Disabling Specific Threads Thread Debugging Support Advanced Thread Debugging Support Backtrace Support for Thread Debugging Pre-requisites for Advanced Thread Debugging Enabling and Disabling Advanced Thread Debugging Features Cv-multiple-mxs onoff The set thread-check cv-multiple-mxs Onoff command checks if an applicationUnlock-not-own onoff The set thread-check unlock-not-own Mixed-sched-policy onoff The set thread-check Different mutexes. The debugger transfers This returns an Einval error toUser and prints a warning message when this Command checks if any thread has terminated Created with the detach attribute. When an When this condition is detected. This situationCommand checks if a thread has terminated Exception or a cancel without joining or Rwlock-id is provided, the command displays Provided, the command displays extendedIs provided, the command displays extended Condvar-id is provided, the command displays For 64-bit PA applications Thread Debugging in Batch Mode For 64 bit IPF applications, set Pre-requisites for Batch mode of Thread DebuggingFor 64-bit PA applications, set Set the environment variable Batchrtc to on as And/Or Opt/langtools/lib/hpux64/librtc.so Where Pid is the process id Thread Debugging in +check ModeLimitations in Batch mode of thread debugging Issue Where pid is the process identifierDebugging MPI Programs Debugger response to a program call to fork or vfork is ask Ask mode for set follow-fork-modeSerial mode for set follow-fork-mode Support for showing unwind info Printing CFM and PFS registers Command to Search for a Pattern in the Memory Address Space Within double quotes. This parameter is mandatory Parameter is mandatory when end-addressis notSpecifies the length of the memory address range. This String value. The character pattern must be enclosed Example 14-1 Sample Output for the find command Specifies the pattern expr1 Using the /max-countparameterUsing the /size-charparameter Str0 Specifies the starting address Generating core files with packcore /unpackcore/getcore Debugging Core Files Support for the info target Command Enhancements to the dumpcore command Support for the dumpcore commandWhen starting from the HP WDB command line When starting from the shell prompt Sample Output When starting from shell promptSupport for display of run time type information Info rtti address Info global-exec-path summary Info exec-path summaryExec-path updownpathindex aliased to ep Sample Program Example Illustrating Execution Path RecoverySample Debugging Session Command to Unwind Beyond 10000 Frames Invoking GDB Before a Program Aborts Aborting a Command Line Call Hardware watchpoints Instruction Level SteppingEnhanced support for watchpoints and breakpoints Deferred watchpoints Rdp Support for procedural breakpointsSupport for template breakpoints Rbp Debugging support for shared libraries Using shared library as main program Using catch load Setting Deferred Breakpoints in Shared LibraryPrivately mapping shared libraries Opt/langtools/bin/pxdb -s on executable-name Selectively Mapping Shared Libraries As Private Printing Decimal Floating point data types Setting breakpoints in shared libraryEnhancement to the info shared Command Debugging support for Decimal Floating Point data type Evaluating Decimal Floating Point data types Following are sample commands to print NaT registersPrinting NaT Registers Handling Decimal Floating Point Data types Printing type of Decimal Floating Point variable Assignment of Decimal floating point value to variableArithmetic Operations Comparison Operations This prints the binary floating point value as double Additional Support for binary floating point data typeSupport for Binary Floating Point constants f, l This prints the binary floating point value as oat Language support Java Stack Unwind FeaturesEnhanced Java Debugging Support Gdb help java Gdb Subcommands for Java VM Debugging Stack frame Frame command of GDB has been enhanced to interpret a JavaJava and native stack frames Info frame Java corefile debugging support Java attach mode debugging support Syntax Enhanced support for C++ templates Support for Complex variables in HP C Support for fpreg data type on IPFSupport for debugging namespaces Viewing Wide Character Strings Command for evaluating the address of an expressionThis is equivalent to executing Support for dumping array in an Ascii file Support for output logging Support for debugging typedefs Support for steplast command for C and C++Support for Fortran array slices Displaying enumerators Getting information from a non-debug executable Break Call Clear Disassem List Debugging optimized codeBreak Call Cond Jump Return Print Set var Watch Whatis HP-UX Configuration-Specific Information 14.29.1.1 +O0 and +O1 Debugging Optimized Code at Various Optimization Levels14.29.1.2 +O2/+O3/+O4/-ipo Debugging with Aries Following limitations apply when debugging optimized code+O2 or -O Limitations of GDB Support under Aries Debugging the application using GDB under Aries Attaching GDB to an already running emulated process Detecting memory leaks using GDB under Aries Starting and stopping Visual Interface for WDB Visual Interface for WDB Visual Interface for WDB GUI display Navigating the Visual Interface for WDB display Specifying foreground and background colors Using the X-window graphical interface Changing the size of the source or debugger pane Using the TUI modeFor dterm, use the following Loading source files Using commands to browse through source filesEditing the command line and command-line history Saving the contents of a debugging session to a file Stop in/at dbx commands Support for XDB commandsGNU GDB Logging Commands Support for command line calls in a stripped executable For 32-bit applications Execute the chatr -B immediate executable command Printing of locals and globals in a stripped module Command line calls to non-stripped librarySupport for debugging stripped binaries For 64-bit applications Linux support Displaying the current block scope informationSyntax 242 Main Invoke the debugger using a command like the followingHP-UX Terminal User Interface Starting the TUI Screen Layouts Automatically running a program at startup Pane looks like this Disassembly paneDisassembly pane appears when you issue the command Source pane Disassembly/Register pane Source/Disassembly paneSource/Disassembly pane appears when you issue the command Source/Register pane Source/Register pane appears when you issue the command Changing pane focus Use the commandsToggle split-screen mode Cycling through the panes Fs regs Foc next Changing the register display Scrolling panes Changing the pane size Refreshing and updating the window XDB to WDB Transition Guide By-function lists of XDB commands and HP WDB equivalents Window mode commands Invocation commandsWindow mode commands Invocation commands File viewing commands File viewing commands Data Viewing and modification commands Source directory mapping commands Ll string Lm string Data viewing and modification commands Stack viewing commands Stack viewing commands Job control commands Status-viewing commandJob control commands Status viewing commands Auxiliary breakpoint commands Overall breakpoint commandsOverall breakpoint commands Auxillary breakpoint commands Breakpoint creation commands10 Breakpoint creation commands 11 Overall breakpoint commands Breakpoint status commands Bp bpt bpx dp Dpt Dpx All-procedures breakpoint commandsGlobal breakpoint commands 12 Global breakpoint commands Record and playback commands Assertion control commandsMacro facility commands 14 Signal control commands Signal control commandsMiscellaneous commands 13 Macro facility commands 16 Data format commands Format of the print command is different in XDB and GDBXDB data formats and HP WDB equivalents Decimal integer XDB location syntax and HP WDB equivalents 17 Macro facility commandsXDB special language operators and HP WDB equivalents 18 Special language operators XDB special variables and HP WDB equivalents19 Special variables 20 Variable Identifiers Alphabetical lists of XDB commands and HP WDB equivalentsXDB variable identifiers and HP WDB equivalents 16.8.1 a 22 B 16.8.2 B 23 C through D Through D 25 L Through K16.8.5 L 24 F through K 26 M through P Through P 28 T Through S16.8.8 T 27 Q through S 29 U through Z Through Z 30 Symbols Symbols Any string Control-C # text 280 Controlling GDB Setting the GDB PromptSetting Command Editing Options in GDB Setting Command History Feature in GDB Expansion or through the history command Control the settingsTo fname. This is the file where GDB reads an Exits. You can access this list through history Supported Number Formats Setting the GDB Screen Size Optional warnings and messages Set confirm on Optional messages about internal happeningsShow confirm Displays state of confirmation requests Object debugging info Show debug varobj User-defined commands Canned Sequences of Commands User-defined command hooks To add source directories or Command files Commands for controlled output Output formats Expressions 292 Using GDB under gnu Emacs GDB up command Calls, like the GDB next command. Then update the displayExecute to next instruction, using the GDB nexti command Update display window accordingly 295 296 GDB Annotations What is an annotation?Server prefix Values When printing a structure, GDB annotates it as follows Frames When printing an array, GDB annotates it as followsFrame annotation begins with Then comes Annotation for GDB input Displays Information on breakpoints Errors Running the program Invalidation notices Displaying source Target-invalid Annotations We Might Want in the Future 306 GDB/MI Interface 21.1 GDB/MI Command Syntax 21.1.2 GDB/MI Output syntax Done running connected error exitPragmatics Value Const tuple list String Tuple → Here is an example to evaluate an expression Here is what happens if you pass a bad command21.2 GDB/MI compatibility with CLI Simple examples of GDB/MI interaction 21.3.2 GDB/MI stream records 21.4 GDB/MI command description format21.3 GDB/MI output records 21.3.1 GDB/MI result records -break-after Command 21.5 GDB/MI breakpoint table commands Corresponding GDB command is condition -break-condition command Corresponding GDB command is disable -break-delete command-break-disable command Corresponding GDB command is delete -break-info Command -break-enable command Result -break-insert command -break-list command Corresponding GDB commands are watch, awatch, and rwatch -break-watch commandSetting a watchpoint on a variable in the main function Exec-continue running gdb 21.6 GDB/MI Data manipulation -data-disassemble command Disassemble from the current value of $pc to $pc + There is no direct mapping from this command to the CLIDisassemble 3 instructions from the start of main -data-evaluate-expression command On a PPC MBX board -data-list-changed-registers Command-data-list-register-names command Display a list of the registers that have changed -data-list-register-values command Space should be quoted using the C convention -data-read-memory commandTo be read. Complex expressions containing embedded white Word-format Word-sizenr-rowsnr-cols aschar -display-disable Command -display-delete command -environment-cd command -display-enable command-display-insert Command -display-list command -environment-path command -environment-directory command Show the current working directory -environment-pwd commandCorresponding GDB command is pwd 21.7 GDB/MI program control -exec-arguments command -exec-abort command-exec-continue command Corresponding GDB command is interrupt -exec-finish command-exec-interrupt command Corresponding GDB command is finish Corresponding GDB command is nexti -exec-nextcommand Synopsis-exec-next-instruction command Corresponding GDB command is next Corresponding GDB command is run -exec-return command-exec-runcommand Synopsis Corresponding GDB command is return Example -exec-stepCommand Synopsis -exec-show-arguments command Regular stepping -exec-step-instruction command-exec-until command Corresponding GDB command is stepi Corresponding GDB command is file -file-exec-and-symbols command-file-exec-file command Corresponding GDB command is until -file-list-exec-source-files command -file-list-exec-sections command-file-list-shared-libraries command -gdb-exitcommand Synopsis Miscellaneous GDB commands in GDB/MI-file-list-symbol-files command -file-symbol-file command -gdb-showcommand Synopsis -gdb-setcommand Synopsis-gdb-version command -stack-info-frame command 21.9 GDB/MI Stack Manipulation Commands-stack-info-depth command For a stack with frame levels 0 through -stack-list-arguments command Synopsis -stack-list-frames command Show a single frame Corresponding GDB commands are backtrace and whereFull stack backtrace Show frames between lowframe and highframe -stack-select-frame command -stack-list-locals commandInfo locals in GDB, gdbgetlocals in gdbtk -symbol-info-function command 21.10 GDB/MI Symbol query commands-symbol-info-address command -symbol-info-file command -symbol-list-types command -symbol-info-line command-symbol-info-symbol command -symbol-list-functions command -symbol-locate command -symbol-list-variables command-symbol-type command -target-detach command 21.11 GDB/MI Target Manipulation Commands-target-attach command -target-compare-sections command At the end, a summary is printed -target-download commandCorresponding GDB command is load Name of the section -target-exec-status command -target-list-current-targets command -target-list-available-targets command-target-list-parameters command -thread-list-all-threads command 21.12 GDB/MI thread commands-target-select command -thread-info command -thread-select command -thread-list-ids command Tracepoint commands are not yet implemented 21.13 GDB/MI tracepoint commands21.14 GDB/MI variable objects GDB/MI Operations -var-create commandDescription and use of operations on variable objects -var-info-num-children command -var-delete command-var-set-format command -var-show-format command -var-show-attributes command -var-list-children command-var-info-type command -var-info-expression command -var-update command -var-assign command 360 Reporting Bugs in GDB How to report bugsHave you found a bug? Reporting Bugs in GDB How to report bugs 364 Installing GDB Gdb-gdb-199991101/mmalloc Compiling GDB in another directoryPackage Specifying names for hosts and targets Srcdir= dirname Configure optionsSeparate directories. configure writes configuration To use the source in the directory dirname. configure All available targets Target=target

21 The GDB/MI Interface

Function and purpose

Notation and terminology

21.1 GDB/MI Command Syntax

21.1.1 GDB/MI Input syntax

characters such as “-”, nl, """ and of course “”