GDB Annotations | HP gnu source-level debugger 5992-4701 specification

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

20.1 What is an annotation?

To produce annotations, start GDB with the --annotate=2option.

Annotations start with a newline character, two control-zcharacters, 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-zcharacters denotes literal output from GDB. Currently there is no need for GDB to output a newline followed by two control-zcharacters, 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-zcharacter) are annotations; the rest is output from GDB.

20.2 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

20.1 What is an annotation? 297

Image 297

HP gnu source-level debugger 5992-4701 manual GDB Annotations, What is an annotation?, Server prefix

Contents

Debugging with GDB Manual Page Table of Contents Print settings Value history Continuing and stepping SignalsBreakpoints Stack frames Examining the Symbol Table Specifying a Debugging Target Scramble previous memory contents at malloc/free calls Stop when freeing unallocated or deallocated blocksBatch Mode Commands for heap profiling Support for the dumpcore command Support for the info target CommandEnhancements to the dumpcore command Example Illustrating Execution Path Recovery Support for steplast command for C and C++ Command for evaluating the address of an expressionDebugging the application using GDB under Aries Detecting memory leaks using GDB under Aries HP-UX Terminal User Interface Setting Command History Feature in GDB 281 17.4 Miscellaneous commands 265 16.3User-defined commands 287 18.2 Command files 289 Commands for controlled output 290 22.2 How to report bugs 361 20.7 Errors 302 20.820.9 Invalidation notices 303 304 List of Tables List of Examples Summary of GDB Free SoftwareContributors to GDB Page Contributors to GDB Page Let us use GDB to try to see what is going on Sample GDB SessionLoading the Executable Setting Breakpoints Setting Display widthHere we describe how to set a breakpoint Running the executable under GDB Stepping into a subroutine Examining the StackPrinting 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 Line number in a standard, recognizable fashion each GNU Emacs sets this option when it runs GDB as aTime a stack frame is displayed which includes each Like two `\032 characters, followed by the file name Emacs Quitting GDB Redirecting WDB input and output to a fileInterface Shell commands Page GDB Commands Command syntaxCommand completion GDB sounds bell press TAB again, to see Short list of named classes of commands Getting helpHelp , h Results Apropos reloadComplete This is intended for use by GNU Emacs Getting help Page Compiling for debugging Running Programs Under GDBStarting your program Arguments, so that you may use normal See Arguments To Your Program Your program. SeeProgram EnvironmentDirectory Arguments To Your Program Program EnvironmentProgram. See Program Input and Output Display the list of search paths for executables For example, this commandPath environment variable Do not supply varname, print the names Program Input and Output Working directory Debugging a Running Process Killing the child process Debugging programs with multiple threads New process 35 thread Thread apply command allows you to Here are commands to get more information about threadsWith the command argument threadno Display a summary of all threads currently Debugging programs with multiple processes Unimpeded. This is the default New process. The mode can beSet the debugger response to a program call Fork. The child process runs Breakpoints Stopping and Continuing Setting breakpoints Breakpoints See Break conditions page 59, for more Catchpoint BreakpointWhether Breakpoint is Enabled When hitMarked to be Breakpoints are Setting catchpoints Is currently only available for HP-UX Call to vfork. This is currently onlyUnloading of any dynamically loaded Shared library, or the unloading Deleting breakpoints Disabling breakpointsSelecting a frame page 73 . When Break conditions No symbol foo in current context Breakpoint, GDB prints an error messageStops your program only if the value Use condition, GDB checks expression 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 Commands for Examining the Stack Stacks Without framesBacktraces Selecting a frame When used without any argument, this command does not Have existed longer. n defaults to oneWith an argument, this command is used to select a stack Information about a frame Setting catchpoints Page Printing source lines Examining Source FilesList Show listsize Searching source files Specifying source directories Source and machine code Show directoriesContains Disassemble or x/i commands Set disassembly-flavorSelect the instruction set to use when Disassembling the program viaPage Examining Data Following forms of print command are supportedExpressions To See Artificial arrays page 85, for more information Program variables Where it is defined. See Program variablesType addr Normally supposed to reside at addr Artificial arrays You can print the contents of array with Output formats Examining memory Machine instruction. The default isPrint, s null-terminated string, or Time you use either x or print However, the count n must come first wx4 does not work For fmt specifying only a display format and not a size or Automatic displaySee Output formats For fmt i or s, or including a unit-size or a number Print settings File name and line number of a symbol A symbol. This is the defaultSymbolic form of an address Address Strings. When GDB starts, this limit is set to Default is offSetting number-of-elementsto zero Short strings. The default is off Show which format GDB is using to print This is the default formatPrint using only seven-bit characters if this Default Default is on These settings are of interest when debugging C++ programsShow whether C++ names in assembly listings Would print Value history Convenience variables Format in which the data was printed Command, in which case it is a pointer to the type of $$exitcode Program being debugged terminates Info registers Info all-registers Info registers regname RegistersOr print the instruction to be executed next with Or add four to the stack pointer3 with3with Floating point hardware Printing Floating Point ValuesTo get the bit pattern, try the following macro This is what the macro produces 100 Switching between source languages Using GDB with Different LanguagesList of filename extensions and languages Cpp Not skip over function prologues when stepping Setting the working languageHaving GDB infer the source language Files Displaying the language Type and range checkingAn overview of type checking An overview of range checking Supported languages C++ Non-zero for true Expressions is 0 for false and non-zero for trueLeft shift, and right shift. Defined on integral types Types and pointer types Double colons also represent the GDB scope operator see Class typesExpressions page 83. Same precedence as , above C++ constants GDB expression handling can interpret most C++ expressions 1.3 C++ expressions C++ defaults Printing the variable or class returnsC++ type and range checks GDB and C GDB features for C++Breakpoint menus See Breakpoint menus Fortran Fortran typesFortran types supported Less than or equal to Less thanGreater than Greater than or equal to Fortran special issues CommonblocknameBlock Examining the Symbol Table As with whatis, using ptype without an Two commands give this outputSymbols will be read when needed For example, for this variable declaration Replace symbol definitions Allow GDB to reload the symbols forDo not replace symbol Once. This is the default Is in another source file. The default is on SettingTell GDB to resolve opaque types. An opaque Class, or union―for example, struct Assignment to variables Altering Execution Stores the value 4 into that memory location Continuing at a different address Giving your program a signal You can use the following command to return from a functionReturning from a function Patching programs Calling program functionsReturn , return Is used as the return value from the function value Patching programs 124 GDB Files Commands to specify files See Optional warnings and messages GDB has the entire symbol table available Option with any of the commands that loadWrite the symbols for your program into a Map in symbol information from this auxiliary Section To display or set the threshold, use the commands Symbols were loaded. Both the commands listIf threshold is nonzero, symbols from all New library has been loaded, until the symbol Searching the default system directories Names where the desired shared libraries reside. GDBSpecifying shared library locations Megabytes Errors reading symbol files Verbose on. See Optional warningsMessages Is the symbol type of the uncomprehended Symbol scope block as starting on the previousGDB circumvents the error by ignoring this Debug your program, though certain symbols Commands for managing targets Specifying a Debugging TargetActive targets See Commands to specify files Choosing target byte order Instruct GDB to assume the target is little-endian Instruct GDB to assume the target is big-endianExecutable Display GDBs current idea of the target byte order 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 HP-UX dependencies Linker DependenciesDependent Standard Library Routines for Run Time Checking Getpid Close Srand Strchr Abort Unlink Atoi Supported Platforms and Modes Support for Alternate root HP-UX targetsWDB Location GDB location Librtc.sl location $WDBROOT/bin Opt/langtools/ n/a Specifying object file directoriesNone Bin $WDBROOT/bin Fix and continue debugging Fix and Continue restrictions Fix and Continue compiler dependencies Using Fix and Continue Example Fix and Continue session Compile the programRun the program Gdb run Gdb b mainGdb edit Make the necessary changes. In this case, add return total Inline Support Inline Debugging in HP 9000 SystemsGdb q Following options available for the set inline-debugcommand Breakpoint info frame disassemblyInline Debugging in Integrity Systems Step next list backtrace frame n info locals info args Debugging Inline Functions in Integrity Systems Limitations Info frame disassembly Debugging MacrosViewing and Evaluating Macro Definitions Compiler Options to Enable Macro Debugging Evaluating MacrosDebug=none Examples for Macro Debugging HP-UX Configuration-Specific Information Debugging Memory Problems When to suspect a memory leak Memory debugging restrictionsMemory Debugging Methodologies Debugging Memory in Interactive Mode This command are ignored from report. If Displays all current settings for memoryHeap growth. The default value is 100. Every Command discards the data existing in the file Debugging Memory Problems Have occurred and WDB reports the problem Debugging when the string option is set forSpecific pattern when it is allocated or Such as attempting to access space that is freed If the user specifies a value less than 16 for Use the info command to show list of memory leaksNumber of bytes, the debugger ignores it User-specified value Debugging Memory in Batch Mode Setting Configuration Options for 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 PA applications For 64-bit IPF applications Ldpreload Environment variable setting for Batch mode debugging Aborts execution when out of memory Aborts execution when heap objectsLog file for batch mode must be Stderr error message goes to stderr Example for Batch Mode RTC Complete one of the following steps Rtcconfig file should contain entries such as the following Preload the librtc library as followsRun the program as follows For 32 bit PA applications Run the program Start a debugging session as follows Configuring memory debugging settingsSpecifying the stack depth Specifying minimum leak size Scenarios in memory debugging Stop when freeing unallocated or deallocated blocksFor example, if you use Specifying minimum block size Interactive debugging mode set heap-check scramble on off Scramble previous memory contents at malloc/free callsSyntax Detect dangling pointers and dangling blocks Detect in-block corruption of freed blocks Off Memory Debugging Commands in Interactive and Batch Mode Point you use the info heap command Commands for heap profilingHeap Profiling As the start of the heap, end of the heap, heap 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 Unlock-not-own onoff The set thread-check unlock-not-own Onoff command checks if an applicationMixed-sched-policy onoff The set thread-check Cv-multiple-mxs onoff The set thread-check cv-multiple-mxs User and prints a warning message when this This returns an Einval error toCommand checks if any thread has terminated Different mutexes. The debugger transfers Command checks if a thread has terminated When this condition is detected. This situationException or a cancel without joining or Created with the detach attribute. When an Is provided, the command displays extended Provided, the command displays extendedCondvar-id is provided, the command displays Rwlock-id is provided, the command displays For 64-bit PA applications Thread Debugging in Batch Mode Pre-requisites for Batch mode of Thread Debugging For 64 bit IPF applications, setFor 64-bit PA applications, set Set the environment variable Batchrtc to on as And/Or Opt/langtools/lib/hpux64/librtc.so Thread Debugging in +check Mode Where Pid is the process idLimitations in Batch mode of thread debugging Where pid is the process identifier IssueDebugging MPI Programs Serial mode for set follow-fork-mode Ask mode for set follow-fork-modeSupport for showing unwind info Debugger response to a program call to fork or vfork is ask Printing CFM and PFS registers Command to Search for a Pattern in the Memory Address Space Specifies the length of the memory address range. This Parameter is mandatory when end-addressis notString value. The character pattern must be enclosed Within double quotes. This parameter is mandatory Example 14-1 Sample Output for the find command Using the /size-charparameter Using the /max-countparameterStr0 Specifies the starting address Specifies the pattern expr1 Generating core files with packcore /unpackcore/getcore Debugging Core Files Support for the info target Command When starting from the HP WDB command line Support for the dumpcore commandWhen starting from the shell prompt Enhancements to the dumpcore command Support for display of run time type information When starting from shell promptInfo rtti address Sample Output Info exec-path summary Info global-exec-path summaryExec-path updownpathindex aliased to ep Example Illustrating Execution Path Recovery Sample ProgramSample Debugging Session Command to Unwind Beyond 10000 Frames Invoking GDB Before a Program Aborts Aborting a Command Line Call Enhanced support for watchpoints and breakpoints Instruction Level SteppingDeferred watchpoints Hardware watchpoints Support for template breakpoints Support for procedural breakpointsRbp Rdp Debugging support for shared libraries Using shared library as main program Setting Deferred Breakpoints in Shared Library Using catch loadPrivately mapping shared libraries Opt/langtools/bin/pxdb -s on executable-name Selectively Mapping Shared Libraries As Private Enhancement to the info shared Command Setting breakpoints in shared libraryDebugging support for Decimal Floating Point data type Printing Decimal Floating point data types Printing NaT Registers Following are sample commands to print NaT registersHandling Decimal Floating Point Data types Evaluating Decimal Floating Point data types Arithmetic Operations Assignment of Decimal floating point value to variableComparison Operations Printing type of Decimal Floating Point variable Support for Binary Floating Point constants f, l Additional Support for binary floating point data typeThis prints the binary floating point value as oat This prints the binary floating point value as double Java Stack Unwind Features Language supportEnhanced Java Debugging Support Gdb help java Gdb Subcommands for Java VM Debugging Java and native stack frames Frame command of GDB has been enhanced to interpret a JavaInfo frame Stack frame Java corefile debugging support Java attach mode debugging support Syntax Enhanced support for C++ templates Support for fpreg data type on IPF Support for Complex variables in HP CSupport for debugging namespaces Command for evaluating the address of an expression Viewing Wide Character StringsThis is equivalent to executing Support for dumping array in an Ascii file Support for output logging Support for Fortran array slices Support for steplast command for C and C++Displaying enumerators Support for debugging typedefs Getting information from a non-debug executable Debugging optimized code Break Call Clear Disassem ListBreak Call Cond Jump Return Print Set var Watch Whatis HP-UX Configuration-Specific Information Debugging Optimized Code at Various Optimization Levels 14.29.1.1 +O0 and +O114.29.1.2 +O2/+O3/+O4/-ipo Following limitations apply when debugging optimized code Debugging with Aries+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 Using the TUI mode Changing the size of the source or debugger paneFor dterm, use the following Editing the command line and command-line history Using commands to browse through source filesSaving the contents of a debugging session to a file Loading source files GNU GDB Logging Commands Support for XDB commandsSupport for command line calls in a stripped executable Stop in/at dbx commands For 32-bit applications Execute the chatr -B immediate executable command Support for debugging stripped binaries Command line calls to non-stripped libraryFor 64-bit applications Printing of locals and globals in a stripped module Displaying the current block scope information Linux supportSyntax 242 HP-UX Terminal User Interface Invoke the debugger using a command like the followingStarting the TUI Main Screen Layouts Automatically running a program at startup Disassembly pane appears when you issue the command Disassembly paneSource pane Pane looks like this Source/Disassembly pane Disassembly/Register paneSource/Disassembly pane appears when you issue the command Source/Register pane Source/Register pane appears when you issue the command Toggle split-screen mode Use the commandsCycling through the panes Changing pane focus 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 commandsInvocation commands Window mode 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 commandStatus viewing commands Job control commands Overall breakpoint commands Auxiliary breakpoint commandsOverall breakpoint commands Breakpoint creation commands Auxillary breakpoint commands10 Breakpoint creation commands 11 Overall breakpoint commands Breakpoint status commands Global breakpoint commands All-procedures breakpoint commands12 Global breakpoint commands Bp bpt bpx dp Dpt Dpx Assertion control commands Record and playback commandsMacro facility commands Miscellaneous commands Signal control commands13 Macro facility commands 14 Signal control commands Format of the print command is different in XDB and GDB 16 Data format commandsXDB data formats and HP WDB equivalents Decimal integer 17 Macro facility commands XDB location syntax and HP WDB equivalentsXDB special language operators and HP WDB equivalents XDB special variables and HP WDB equivalents 18 Special language operators19 Special variables XDB variable identifiers and HP WDB equivalents Alphabetical lists of XDB commands and HP WDB equivalents16.8.1 a 20 Variable Identifiers 22 B 16.8.2 B 23 C through D Through D 16.8.5 L Through K24 F through K 25 L 26 M through P Through P 16.8.8 T Through S27 Q through S 28 T 29 U through Z Through Z 30 Symbols Symbols Any string Control-C # text 280 Setting Command Editing Options in GDB Setting the GDB PromptSetting Command History Feature in GDB Controlling GDB To fname. This is the file where GDB reads an Control the settingsExits. You can access this list through history Expansion or through the history command Supported Number Formats Setting the GDB Screen Size Optional warnings and messages Optional messages about internal happenings Set confirm onShow 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 Execute to next instruction, using the GDB nexti command Calls, like the GDB next command. Then update the displayUpdate display window accordingly GDB up command 295 296 What is an annotation? GDB AnnotationsServer prefix Values When printing a structure, GDB annotates it as follows When printing an array, GDB annotates it as follows FramesFrame 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 Done running connected error exit 21.1.2 GDB/MI Output syntaxPragmatics Value Const tuple list String Tuple → 21.2 GDB/MI compatibility with CLI Here is what happens if you pass a bad commandSimple examples of GDB/MI interaction Here is an example to evaluate an expression 21.3 GDB/MI output records 21.4 GDB/MI command description format21.3.1 GDB/MI result records 21.3.2 GDB/MI stream records -break-after Command 21.5 GDB/MI breakpoint table commands Corresponding GDB command is condition -break-condition command -break-disable command -break-delete commandCorresponding GDB command is delete Corresponding GDB command is disable -break-info Command -break-enable command Result -break-insert command -break-list command -break-watch command Corresponding GDB commands are watch, awatch, and rwatchSetting a watchpoint on a variable in the main function Exec-continue running gdb 21.6 GDB/MI Data manipulation -data-disassemble command There is no direct mapping from this command to the CLI Disassemble from the current value of $pc to $pc +Disassemble 3 instructions from the start of main -data-evaluate-expression command -data-list-register-names command -data-list-changed-registers CommandDisplay a list of the registers that have changed On a PPC MBX board -data-list-register-values command -data-read-memory command Space should be quoted using the C conventionTo be read. Complex expressions containing embedded white Word-format Word-sizenr-rowsnr-cols aschar -display-disable Command -display-delete command -display-insert Command -display-enable command-display-list command -environment-cd command -environment-path command -environment-directory command Corresponding GDB command is pwd -environment-pwd command21.7 GDB/MI program control Show the current working directory -exec-abort command -exec-arguments command-exec-continue command -exec-interrupt command -exec-finish commandCorresponding GDB command is finish Corresponding GDB command is interrupt -exec-next-instruction command -exec-nextcommand SynopsisCorresponding GDB command is next Corresponding GDB command is nexti -exec-runcommand Synopsis -exec-return commandCorresponding GDB command is return Corresponding GDB command is run Example -exec-stepCommand Synopsis -exec-show-arguments command -exec-until command -exec-step-instruction commandCorresponding GDB command is stepi Regular stepping -file-exec-file command -file-exec-and-symbols commandCorresponding GDB command is until Corresponding GDB command is file -file-list-exec-sections command -file-list-exec-source-files command-file-list-shared-libraries command -file-list-symbol-files command Miscellaneous GDB commands in GDB/MI-file-symbol-file command -gdb-exitcommand Synopsis -gdb-setcommand Synopsis -gdb-showcommand Synopsis-gdb-version command 21.9 GDB/MI Stack Manipulation Commands -stack-info-frame command-stack-info-depth command For a stack with frame levels 0 through -stack-list-arguments command Synopsis -stack-list-frames command Full stack backtrace Corresponding GDB commands are backtrace and whereShow frames between lowframe and highframe Show a single frame -stack-list-locals command -stack-select-frame commandInfo locals in GDB, gdbgetlocals in gdbtk -symbol-info-address command 21.10 GDB/MI Symbol query commands-symbol-info-file command -symbol-info-function command -symbol-info-symbol command -symbol-info-line command-symbol-list-functions command -symbol-list-types command -symbol-list-variables command -symbol-locate command-symbol-type command -target-attach command 21.11 GDB/MI Target Manipulation Commands-target-compare-sections command -target-detach command Corresponding GDB command is load -target-download commandName of the section At the end, a summary is printed -target-exec-status command -target-list-available-targets command -target-list-current-targets command-target-list-parameters command -target-select command 21.12 GDB/MI thread commands-thread-info command -thread-list-all-threads command -thread-select command -thread-list-ids command 21.13 GDB/MI tracepoint commands Tracepoint commands are not yet implemented21.14 GDB/MI variable objects -var-create command GDB/MI OperationsDescription and use of operations on variable objects -var-set-format command -var-delete command-var-show-format command -var-info-num-children command -var-info-type command -var-list-children command-var-info-expression command -var-show-attributes command -var-update command -var-assign command 360 How to report bugs Reporting Bugs in GDBHave you found a bug? Reporting Bugs in GDB How to report bugs 364 Installing GDB Compiling GDB in another directory Gdb-gdb-199991101/mmallocPackage Specifying names for hosts and targets Separate directories. configure writes configuration Configure optionsTo use the source in the directory dirname. configure Srcdir= dirname All available targets Target=target