X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=e5a6f2e551212d4c2f34d49db970136ebb15ad3e;hb=03727ca61a80cd6a5ddc139d7eab27c13fa1a975;hp=af8588970a4053c6f12b1865697b33f79c99ec2c;hpb=5b5d99cf4d5ded93b60fd64c6069d45e3eeab1d3;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index af8588970a..e5a6f2e551 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, -@c 1999, 2000, 2001, 2002, 2003 +@c 1999, 2000, 2001, 2002, 2003, 2004 @c Free Software Foundation, Inc. @c @c %**start of header @@ -28,11 +28,9 @@ @syncodeindex fn cp @c !!set GDB manual's edition---not the same as GDB version! +@c This is updated by GNU Press. @set EDITION Ninth -@c !!set GDB manual's revision date -@set DATE June 2002 - @c !!set GDB edit command default editor @set EDITOR /bin/ex @@ -40,21 +38,21 @@ @c This is a dir.info fragment to support semi-automated addition of @c manuals to an info tree. -@dircategory Programming & development tools. +@dircategory Software development @direntry -* Gdb: (gdb). The @sc{gnu} debugger. +* Gdb: (gdb). The GNU debugger. @end direntry @ifinfo This file documents the @sc{gnu} debugger @value{GDBN}. -This is the @value{EDITION} Edition, @value{DATE}, -of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger} -for @value{GDBN} Version @value{GDBVN}. +This is the @value{EDITION} Edition, of @cite{Debugging with +@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN} +Version @value{GDBVN}. Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@* - 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. + 1999, 2000, 2001, 2002, 2003, 2004 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 @@ -74,7 +72,6 @@ development.'' @subtitle The @sc{gnu} Source-Level Debugger @sp 1 @subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN} -@subtitle @value{DATE} @author Richard Stallman, Roland Pesch, Stan Shebs, et al. @page @tex @@ -87,7 +84,7 @@ development.'' @vskip 0pt plus 1filll Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, -1996, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. @sp 2 Published by the Free Software Foundation @* 59 Temple Place - Suite 330, @* @@ -115,10 +112,10 @@ development.'' This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. -This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version +This is the @value{EDITION} Edition, for @value{GDBN} Version @value{GDBVN}. -Copyright (C) 1988-2003 Free Software Foundation, Inc. +Copyright (C) 1988-2004 Free Software Foundation, Inc. @menu * Summary:: Summary of @value{GDBN} @@ -146,6 +143,7 @@ Copyright (C) 1988-2003 Free Software Foundation, Inc. * Controlling GDB:: Controlling @value{GDBN} * Sequences:: Canned sequences of commands * TUI:: @value{GDBN} Text User Interface +* Interpreters:: Command Interpreters * Emacs:: Using @value{GDBN} under @sc{gnu} Emacs * Annotations:: @value{GDBN}'s annotation interface. * GDB/MI:: @value{GDBN}'s Machine Interface. @@ -158,6 +156,7 @@ Copyright (C) 1988-2003 Free Software Foundation, Inc. * Installing GDB:: Installing GDB * Maintenance Commands:: Maintenance Commands * Remote Protocol:: GDB Remote Serial Protocol +* Agent Expressions:: The GDB Agent Expression Mechanism * Copying:: GNU General Public License says how you can copy and share GDB * GNU Free Documentation License:: The license for this documentation @@ -193,7 +192,7 @@ Change things in your program, so you can experiment with correcting the effects of one bug and go on to learn about another. @end itemize -You can use @value{GDBN} to debug programs written in C and C++. +You can use @value{GDBN} to debug programs written in C and C@t{++}. For more information, see @ref{Support,,Supported languages}. For more information, see @ref{C,,C and C++}. @@ -212,6 +211,9 @@ syntax. it may be necessary to refer to some variables with a trailing underscore. +@value{GDBN} can be used to debug programs written in Objective-C, +using either the Apple/NeXT or the GNU Objective-C runtime. + @menu * Free Software:: Freely redistributable software * Contributors:: Contributors to GDB @@ -345,7 +347,7 @@ omitted from this list, we would like to add your names! So that they may not regard their many labors as thankless, we particularly thank those who shepherded @value{GDBN} through major releases: -Andrew Cagney (releases 5.3, 5.2, 5.1 and 5.0); +Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs (release 4.14); @@ -371,7 +373,7 @@ Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. David Johnson wrote the original COFF support; Pace Willison did the original support for encapsulated COFF. -Brent Benson of Harris Computer Systems contributed DWARF2 support. +Brent Benson of Harris Computer Systems contributed DWARF 2 support. Adam de Boor and Bradley Davis contributed the ISI Optimum V support. Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS @@ -416,12 +418,13 @@ Fred Fish wrote most of the support for Unix System Vr4. He also enhanced the command-completion support to cover C@t{++} overloaded symbols. -Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and -Super-H processors. +Hitachi America (now Renesas America), Ltd. sponsored the support for +H8/300, H8/500, and Super-H processors. NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. -Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors. +Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D +processors. Toshiba sponsored the support for the TX39 Mips processor. @@ -442,10 +445,10 @@ nearly innumerable bug fixes and cleanups throughout @value{GDBN}. The following people at the Hewlett-Packard Company contributed support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 (narrow mode), HP's implementation of kernel threads, HP's aC@t{++} -compiler, and the terminal user interface: Ben Krepp, Richard Title, -John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve -Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific -information in this manual. +compiler, and the Text User Interface (nee Terminal User Interface): +Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, +Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase +provided HP-specific information in this manual. DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. Robert Hoehne made significant contributions to the DJGPP port. @@ -755,6 +758,7 @@ type @kbd{quit} or @kbd{C-d} to exit. * Invoking GDB:: How to start @value{GDBN} * Quitting GDB:: How to quit @value{GDBN} * Shell Commands:: How to use shell commands inside @value{GDBN} +* Logging output:: How to log @value{GDBN}'s output to a file @end menu @node Invoking GDB @@ -857,7 +861,7 @@ equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) If the second argument begins with a decimal digit, @value{GDBN} will first attempt to attach to it as a process, and if that fails, attempt to open it as a corefile. If you have a corefile whose name begins with -a digit, you can prevent @value{GDBN} from treating it as a pid by +a digit, you can prevent @value{GDBN} from treating it as a pid by prefixing it with @file{./}, eg. @file{./12345}. If @value{GDBN} has not been configured to included core file support, @@ -897,7 +901,7 @@ file. @itemx -c @var{file} @cindex @code{--core} @cindex @code{-c} -Use file @var{file} as a core dump to examine. +Use file @var{file} as a core dump to examine. @item -c @var{number} @item -pid @var{number} @@ -1051,12 +1055,15 @@ separate window. @cindex @code{--annotate} This option sets the @dfn{annotation level} inside @value{GDBN}. Its effect is identical to using @samp{set annotate @var{level}} -(@pxref{Annotations}). -Annotation level controls how much information does @value{GDBN} print -together with its prompt, values of expressions, source lines, and other -types of output. Level 0 is the normal, level 1 is for use when -@value{GDBN} is run as a subprocess of @sc{gnu} Emacs, level 2 is the -maximum annotation suitable for programs that control @value{GDBN}. +(@pxref{Annotations}). The annotation @var{level} controls how much +information @value{GDBN} prints together with its prompt, values of +expressions, source lines, and other types of output. Level 0 is the +normal, level 1 is for use when @value{GDBN} is run as a subprocess of +@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs +that control @value{GDBN}, and level 2 has been deprecated. + +The annotation mechanism has largely been superseeded by @sc{gdb/mi} +(@pxref{GDB/MI}). @item -async @cindex @code{--async} @@ -1105,12 +1112,13 @@ Run using @var{device} for your program's standard input and output. @c resolve the situation of these eventually @item -tui @cindex @code{--tui} -Activate the Terminal User Interface when starting. -The Terminal User Interface manages several text windows on the terminal, -showing source, assembly, registers and @value{GDBN} command outputs -(@pxref{TUI, ,@value{GDBN} Text User Interface}). -Do not use this option if you run @value{GDBN} from Emacs -(@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}). +Activate the @dfn{Text User Interface} when starting. The Text User +Interface manages several text windows on the terminal, showing +source, assembly, registers and @value{GDBN} command outputs +(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the +Text User Interface can be enabled by invoking the program +@samp{gdbtui}. Do not use this option if you run @value{GDBN} from +Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}). @c @item -xdb @c @cindex @code{--xdb} @@ -1124,13 +1132,14 @@ Do not use this option if you run @value{GDBN} from Emacs Use the interpreter @var{interp} for interface with the controlling program or device. This option is meant to be set by programs which communicate with @value{GDBN} using it as a back end. +@xref{Interpreters, , Command Interpreters}. @samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes -@value{GDBN} to use the current @dfn{@sc{gdb/mi} interface} -(@pxref{GDB/MI, , The @sc{gdb/mi} Interface}). The previous @sc{gdb/mi} -interface, included in @value{GDBN} version 5.3, can be selected with -@samp{--interpreter=mi1}. Earlier @sc{gdb/mi} interfaces -are not supported. +@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, , +The @sc{gdb/mi} Interface}) included since @var{GDBN} version 6.0. The +previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and +selected with @samp{--interpreter=mi1}, is deprecated. Earlier +@sc{gdb/mi} interfaces are no longer supported. @item -write @cindex @code{--write} @@ -1207,6 +1216,32 @@ Execute the @code{make} program with the specified arguments. This is equivalent to @samp{shell make @var{make-args}}. @end table +@node Logging output +@section Logging output +@cindex logging @value{GDBN} output + +You may want to save the output of @value{GDBN} commands to a file. +There are several commands to control @value{GDBN}'s logging. + +@table @code +@kindex set logging +@item set logging on +Enable logging. +@item set logging off +Disable logging. +@item set logging file @var{file} +Change the name of the current logfile. The default logfile is @file{gdb.txt}. +@item set logging overwrite [on|off] +By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if +you want @code{set logging on} to overwrite the logfile instead. +@item set logging redirect [on|off] +By default, @value{GDBN} output will go to both the terminal and the logfile. +Set @code{redirect} if you want output to go only to the log file. +@kindex show logging +@item show logging +Show the current values of the logging settings. +@end table + @node Commands @chapter @value{GDBN} Commands @@ -1733,6 +1768,42 @@ time @value{GDBN} read its symbols, @value{GDBN} discards its symbol table, and reads it again. When it does this, @value{GDBN} tries to retain your current breakpoints. +@table @code +@kindex start +@item start +@cindex run to main procedure +The name of the main procedure can vary from language to language. +With C or C@t{++}, the main procedure name is always @code{main}, but +other languages such as Ada do not require a specific name for their +main procedure. The debugger provides a convenient way to start the +execution of the program and to stop at the beginning of the main +procedure, depending on the language used. + +The @samp{start} command does the equivalent of setting a temporary +breakpoint at the beginning of the main procedure and then invoking +the @samp{run} command. + +Some programs contain an elaboration phase where some startup code is +executed before the main program is called. This depends on the +languages used to write your program. In C@t{++} for instance, +constructors for static and global objects are executed before +@code{main} is called. It is therefore possible that the debugger stops +before reaching the main procedure. However, the temporary breakpoint +will remain to halt execution. + +Specify the arguments to give to your program as arguments to the +@samp{start} command. These arguments will be given verbatim to the +underlying @samp{run} command. Note that the same arguments will be +reused if no argument is provided during subsequent calls to +@samp{start} or @samp{run}. + +It is sometimes necessary to debug the program during elaboration. In +these cases, using the @code{start} command would stop the execution of +your program too late, as the program would have already completed the +elaboration phase. Under these circumstances, insert breakpoints in your +elaboration code before running your program. +@end table + @node Arguments @section Your program's arguments @@ -2255,9 +2326,10 @@ get its process ID. Then tell @value{GDBN} (a new invocation of the child process (@pxref{Attach}). From that point on you can debug the child process just like any other process which you attached to. -On HP-UX (11.x and later only?), @value{GDBN} provides support for -debugging programs that create additional processes using the -@code{fork} or @code{vfork} function. +On some systems, @value{GDBN} provides support for debugging programs that +create additional processes using the @code{fork} or @code{vfork} functions. +Currently, the only platforms with this feature are HP-UX (11.x and later +only?) and GNU/Linux (kernel version 2.5.60 and later). By default, when a program forks, @value{GDBN} will continue to debug the parent process and the child process will run unimpeded. @@ -2281,8 +2353,6 @@ unimpeded. This is the default. The new process is debugged after a fork. The parent process runs unimpeded. -@item ask -The debugger will ask for one of the above choices. @end table @item show follow-fork-mode @@ -2408,6 +2478,7 @@ all breakpoint in that range are operated on. * Break Commands:: Breakpoint command lists * Breakpoint Menus:: Breakpoint menus * Error in Breakpoints:: ``Cannot insert breakpoints'' +* Breakpoint related warnings:: ``Breakpoint address adjusted...'' @end menu @node Set Breaks @@ -2512,6 +2583,8 @@ example, on the DSU, only two data breakpoints can be set at a time, and @value{GDBN} will reject this command if more than two are used. Delete or disable unused hardware breakpoints before setting new ones (@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}. +@xref{set remote hardware-breakpoint-limit}. + @kindex thbreak @item thbreak @var{args} @@ -2563,16 +2636,23 @@ Whether the breakpoint is marked to be disabled or deleted when hit. Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints that are not enabled. @item Address -Where the breakpoint is in your program, as a memory address. +Where the breakpoint is in your program, as a memory address. If the +breakpoint is pending (see below for details) on a future load of a shared library, the address +will be listed as @samp{}. @item What Where the breakpoint is in the source for your program, as a file and -line number. +line number. For a pending breakpoint, the original string passed to +the breakpoint command will be listed as it cannot be resolved until +the appropriate shared library is loaded in the future. @end table @noindent If a breakpoint is conditional, @code{info break} shows the condition on the line following the affected breakpoint; breakpoint commands, if any, -are listed after that. +are listed after that. A pending breakpoint is allowed to have a condition +specified for it. The condition is not parsed for validity until a shared +library is loaded that allows the pending breakpoint to resolve to a +valid location. @noindent @code{info break} with a breakpoint @@ -2595,6 +2675,58 @@ your program. There is nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (@pxref{Conditions, ,Break conditions}). +@cindex pending breakpoints +If a specified breakpoint location cannot be found, it may be due to the fact +that the location is in a shared library that is yet to be loaded. In such +a case, you may want @value{GDBN} to create a special breakpoint (known as +a @dfn{pending breakpoint}) that +attempts to resolve itself in the future when an appropriate shared library +gets loaded. + +Pending breakpoints are useful to set at the start of your +@value{GDBN} session for locations that you know will be dynamically loaded +later by the program being debugged. When shared libraries are loaded, +a check is made to see if the load resolves any pending breakpoint locations. +If a pending breakpoint location gets resolved, +a regular breakpoint is created and the original pending breakpoint is removed. + +@value{GDBN} provides some additional commands for controlling pending +breakpoint support: + +@kindex set breakpoint pending +@kindex show breakpoint pending +@table @code +@item set breakpoint pending auto +This is the default behavior. When @value{GDBN} cannot find the breakpoint +location, it queries you whether a pending breakpoint should be created. + +@item set breakpoint pending on +This indicates that an unrecognized breakpoint location should automatically +result in a pending breakpoint being created. + +@item set breakpoint pending off +This indicates that pending breakpoints are not to be created. Any +unrecognized breakpoint location results in an error. This setting does +not affect any pending breakpoints previously created. + +@item show breakpoint pending +Show the current behavior setting for creating pending breakpoints. +@end table + +@cindex operations allowed on pending breakpoints +Normal breakpoint operations apply to pending breakpoints as well. You may +specify a condition for a pending breakpoint and/or commands to run when the +breakpoint is reached. You can also enable or disable +the pending breakpoint. When you specify a condition for a pending breakpoint, +the parsing of the condition will be deferred until the point where the +pending breakpoint location is resolved. Disabling a pending breakpoint +tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent +shared library load. When a pending breakpoint is re-enabled, +@value{GDBN} checks to see if the location is already resolved. +This is done because any number of shared library loads could have +occurred since the time the breakpoint was disabled and one or more +of these loads could resolve the location. + @cindex negative breakpoint numbers @cindex internal @value{GDBN} breakpoints @value{GDBN} itself sometimes sets breakpoints in your program for @@ -2748,6 +2880,8 @@ when a non-current thread's activity changes the expression. (Hardware watchpoints, in contrast, watch an expression in all threads.) @end quotation +@xref{set remote hardware-watchpoint-limit}. + @node Set Catchpoints @subsection Setting catchpoints @cindex catchpoints, setting @@ -3177,7 +3311,8 @@ end @cindex overloading @cindex symbol overloading -Some programming languages (notably C@t{++}) permit a single function name +Some programming languages (notably C@t{++} and Objective-C) permit a +single function name to be defined several times, for application in different contexts. This is called @dfn{overloading}. When a function name is overloaded, @samp{break @var{function}} is not enough to tell @value{GDBN} where you want @@ -3271,6 +3406,58 @@ watchpoints it needs to insert. When this message is printed, you need to disable or remove some of the hardware-assisted breakpoints and watchpoints, and then continue. +@node Breakpoint related warnings +@subsection ``Breakpoint address adjusted...'' +@cindex breakpoint address adjusted + +Some processor architectures place constraints on the addresses at +which breakpoints may be placed. For architectures thus constrained, +@value{GDBN} will attempt to adjust the breakpoint's address to comply +with the constraints dictated by the architecture. + +One example of such an architecture is the Fujitsu FR-V. The FR-V is +a VLIW architecture in which a number of RISC-like instructions may be +bundled together for parallel execution. The FR-V architecture +constrains the location of a breakpoint instruction within such a +bundle to the instruction with the lowest address. @value{GDBN} +honors this constraint by adjusting a breakpoint's address to the +first in the bundle. + +It is not uncommon for optimized code to have bundles which contain +instructions from different source statements, thus it may happen that +a breakpoint's address will be adjusted from one source statement to +another. Since this adjustment may significantly alter @value{GDBN}'s +breakpoint related behavior from what the user expects, a warning is +printed when the breakpoint is first set and also when the breakpoint +is hit. + +A warning like the one below is printed when setting a breakpoint +that's been subject to address adjustment: + +@smallexample +warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. +@end smallexample + +Such warnings are printed both for user settable and @value{GDBN}'s +internal breakpoints. If you see one of these warnings, you should +verify that a breakpoint set at the adjusted address will have the +desired affect. If not, the breakpoint in question may be removed and +other breakpoints may be set which will have the desired behavior. +E.g., it may be sufficient to place the breakpoint at a later +instruction. A conditional breakpoint may also be useful in some +cases to prevent the breakpoint from triggering too often. + +@value{GDBN} will also issue a warning when stopping at one of these +adjusted breakpoints: + +@smallexample +warning: Breakpoint 1 address previously adjusted from 0x00010414 +to 0x00010410. +@end smallexample + +When this warning is encountered, it may be too late to take remedial +action except in cases where the breakpoint is hit earlier or more +frequently than expected. @node Continuing and Stepping @section Continuing and stepping @@ -3669,6 +3856,47 @@ allows you to examine the overall state of the program, including switching between threads, without worrying that things may change underfoot. +@cindex thread breakpoints and system calls +@cindex system calls and thread breakpoints +@cindex premature return from system calls +There is an unfortunate side effect. If one thread stops for a +breakpoint, or for some other reason, and another thread is blocked in a +system call, then the system call may return prematurely. This is a +consequence of the interaction between multiple threads and the signals +that @value{GDBN} uses to implement breakpoints and other events that +stop execution. + +To handle this problem, your program should check the return value of +each system call and react appropriately. This is good programming +style anyways. + +For example, do not write code like this: + +@smallexample + sleep (10); +@end smallexample + +The call to @code{sleep} will return early if a different thread stops +at a breakpoint or for some other reason. + +Instead, write this: + +@smallexample + int unslept = 10; + while (unslept > 0) + unslept = sleep (unslept); +@end smallexample + +A system call is allowed to return early, so the system is still +conforming to its specification. But @value{GDBN} does cause your +multi-threaded program to behave differently than it would without +@value{GDBN}. + +Also, @value{GDBN} uses internal breakpoints in the thread library to +monitor certain events such as thread creation and thread destruction. +When such an event happens, a system call in another thread may return +prematurely, even though your program does not appear to stop. + @cindex continuing threads @cindex threads, continuing Conversely, whenever you restart the program, @emph{all} threads start @@ -3884,27 +4112,40 @@ The display for frame zero does not begin with a program counter value, indicating that your program has stopped at the beginning of the code for line @code{993} of @code{builtin.c}. -@kindex set backtrace-below-main -@kindex show backtrace-below-main +@kindex set backtrace past-main +@kindex show backtrace past-main +@kindex set backtrace limit +@kindex show backtrace limit + +Most programs have a standard user entry point---a place where system +libraries and startup code transition into user code. For C this is +@code{main}. When @value{GDBN} finds the entry function in a backtrace +it will terminate the backtrace, to avoid tracing into highly +system-specific (and generally uninteresting) code. -Most programs have a standard entry point---a place where system libraries -and startup code transition into user code. For C this is @code{main}. -When @value{GDBN} finds the entry function in a backtrace it will terminate -the backtrace, to avoid tracing into highly system-specific (and generally -uninteresting) code. If you need to examine the startup code, then you can -change this behavior. +If you need to examine the startup code, or limit the number of levels +in a backtrace, you can change this behavior: @table @code -@item set backtrace-below-main off +@item set backtrace past-main +@itemx set backtrace past-main on +Backtraces will continue past the user entry point. + +@item set backtrace past-main off Backtraces will stop when they encounter the user entry point. This is the default. -@item set backtrace-below-main -@itemx set backtrace-below-main on -Backtraces will continue past the user entry point to the top of the stack. +@item show backtrace past-main +Display the current user entry point backtrace policy. + +@item set backtrace limit @var{n} +@itemx set backtrace limit 0 +@cindex backtrace limit +Limit the backtrace to @var{n} levels. A value of zero means +unlimited. -@item show backtrace-below-main -Display the current backtrace policy. +@item show backtrace limit +Display the current limit on backtrace levels. @end table @node Selection @@ -4539,6 +4780,7 @@ Table}. * Registers:: Registers * Floating Point Hardware:: Floating point hardware * Vector Unit:: Vector Unit +* Auxiliary Vector:: Auxiliary data provided by operating system * Memory Region Attributes:: Memory region attributes * Dump/Restore Files:: Copy between memory and a file * Character Sets:: Debugging programs that use a different @@ -4711,13 +4953,12 @@ No symbol "foo" in current context. To solve such problems, either recompile without optimizations, or use a different debug info format, if the compiler supports several such -formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler usually -supports the @samp{-gstabs} option. @samp{-gstabs} produces debug info -in a format that is superior to formats such as COFF. You may be able -to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for -debug info. See @ref{Debugging Options,,Options for Debugging Your -Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more -information. +formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler +usually supports the @option{-gstabs+} option. @option{-gstabs+} +produces debug info in a format that is superior to formats such as +COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also +an effective form for debug info. @xref{Debugging Options,,Options +for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}. @node Arrays @@ -5720,12 +5961,38 @@ Display information about the vector unit. The exact contents and layout vary depending on the hardware. @end table +@node Auxiliary Vector +@section Operating system auxiliary vector +@cindex auxiliary vector +@cindex vector, auxiliary + +Some operating systems supply an @dfn{auxiliary vector} to programs at +startup. This is akin to the arguments and environment that you +specify for a program, but contains a system-dependent variety of +binary values that tell system libraries important details about the +hardware, operating system, and process. Each value's purpose is +identified by an integer tag; the meanings are well-known but system-specific. +Depending on the configuration and operating system facilities, +@value{GDBN} may be able to show you this information. + +@table @code +@kindex info auxv +@item info auxv +Display the auxiliary vector of the inferior, which can be either a +live process or a core dump file. @value{GDBN} prints each tag value +numerically, and also shows names and text descriptions for recognized +tags. Some values in the vector are numbers, some bit masks, and some +pointers to strings or other data. @value{GDBN} displays each value in the +most appropriate form for a recognized tag, and in hexadecimal for +an unrecognized tag. +@end table + @node Memory Region Attributes -@section Memory region attributes +@section Memory region attributes @cindex memory region attributes -@dfn{Memory region attributes} allow you to describe special handling -required by regions of your target's memory. @value{GDBN} uses attributes +@dfn{Memory region attributes} allow you to describe special handling +required by regions of your target's memory. @value{GDBN} uses attributes to determine whether to allow certain types of memory accesses; whether to use specific width accesses; and whether to cache target memory. @@ -5735,7 +6002,7 @@ accessing memory in that region. Similarly, if no memory regions have been defined, @value{GDBN} uses the default attributes when accessing all memory. -When a memory region is defined, it is given a number to identify it; +When a memory region is defined, it is given a number to identify it; to enable, disable, or remove a memory region, you specify that number. @table @code @@ -5753,7 +6020,7 @@ Remove memory regions @var{nums}@dots{}. @kindex disable mem @item disable mem @var{nums}@dots{} Disable memory regions @var{nums}@dots{}. -A disabled memory region is not forgotten. +A disabled memory region is not forgotten. It may be enabled again later. @kindex enable mem @@ -5768,7 +6035,7 @@ for each region. @table @emph @item Memory Region Number @item Enabled or Disabled. -Enabled memory regions are marked with @samp{y}. +Enabled memory regions are marked with @samp{y}. Disabled memory regions are marked with @samp{n}. @item Lo Address @@ -5785,7 +6052,7 @@ The list of attributes set for this memory region. @subsection Attributes -@subsubsection Memory Access Mode +@subsubsection Memory Access Mode The access mode attributes set whether @value{GDBN} may make read or write accesses to a memory region. @@ -5826,7 +6093,7 @@ Use 64 bit memory accesses. @c @c @table @code @c @item hwbreak -@c Always use hardware breakpoints +@c Always use hardware breakpoints @c @item swbreak (default) @c @end table @@ -5839,13 +6106,13 @@ registers. @table @code @item cache -Enable @value{GDBN} to cache target memory. +Enable @value{GDBN} to cache target memory. @item nocache Disable @value{GDBN} from caching target memory. This is the default. @end table @c @subsubsection Memory Write Verification -@c The memory write verification attributes set whether @value{GDBN} +@c The memory write verification attributes set whether @value{GDBN} @c will re-reads data after each write to verify the write was successful. @c @c @table @code @@ -5859,64 +6126,55 @@ Disable @value{GDBN} from caching target memory. This is the default. @cindex append data to a file @cindex dump data to a file @cindex restore data from a file -@kindex dump -@kindex append -@kindex restore -The commands @code{dump}, @code{append}, and @code{restore} are used -for copying data between target memory and a file. Data is written -into a file using @code{dump} or @code{append}, and restored from a -file into memory by using @code{restore}. Files may be binary, srec, -intel hex, or tekhex (but only binary files can be appended). +You can use the commands @code{dump}, @code{append}, and +@code{restore} to copy data between target memory and a file. The +@code{dump} and @code{append} commands write data to a file, and the +@code{restore} command reads data from a file back into the inferior's +memory. Files may be in binary, Motorola S-record, Intel hex, or +Tektronix Hex format; however, @value{GDBN} can only append to binary +files. @table @code -@kindex dump binary -@kindex append binary -@item dump binary memory @var{filename} @var{start_addr} @var{end_addr} -Dump contents of memory from @var{start_addr} to @var{end_addr} into -raw binary format file @var{filename}. - -@item append binary memory @var{filename} @var{start_addr} @var{end_addr} -Append contents of memory from @var{start_addr} to @var{end_addr} to -raw binary format file @var{filename}. - -@item dump binary value @var{filename} @var{expression} -Dump value of @var{expression} into raw binary format file @var{filename}. -@item append binary memory @var{filename} @var{expression} -Append value of @var{expression} to raw binary format file @var{filename}. - -@kindex dump ihex -@item dump ihex memory @var{filename} @var{start_addr} @var{end_addr} -Dump contents of memory from @var{start_addr} to @var{end_addr} into -intel hex format file @var{filename}. - -@item dump ihex value @var{filename} @var{expression} -Dump value of @var{expression} into intel hex format file @var{filename}. - -@kindex dump srec -@item dump srec memory @var{filename} @var{start_addr} @var{end_addr} -Dump contents of memory from @var{start_addr} to @var{end_addr} into -srec format file @var{filename}. +@kindex dump +@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr} +@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr} +Dump the contents of memory from @var{start_addr} to @var{end_addr}, +or the value of @var{expr}, to @var{filename} in the given format. -@item dump srec value @var{filename} @var{expression} -Dump value of @var{expression} into srec format file @var{filename}. +The @var{format} parameter may be any one of: +@table @code +@item binary +Raw binary form. +@item ihex +Intel hex format. +@item srec +Motorola S-record format. +@item tekhex +Tektronix Hex format. +@end table -@kindex dump tekhex -@item dump tekhex memory @var{filename} @var{start_addr} @var{end_addr} -Dump contents of memory from @var{start_addr} to @var{end_addr} into -tekhex format file @var{filename}. +@value{GDBN} uses the same definitions of these formats as the +@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If +@var{format} is omitted, @value{GDBN} dumps the data in raw binary +form. -@item dump tekhex value @var{filename} @var{expression} -Dump value of @var{expression} into tekhex format file @var{filename}. +@kindex append +@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr} +@itemx append @r{[}binary@r{]} value @var{filename} @var{expr} +Append the contents of memory from @var{start_addr} to @var{end_addr}, +or the value of @var{expr}, to @var{filename}, in raw binary form. +(@value{GDBN} can only append data to files in raw binary form.) -@item restore @var{filename} [@var{binary}] @var{bias} @var{start} @var{end} -Restore the contents of file @var{filename} into memory. The @code{restore} -command can automatically recognize any known bfd file format, except for -raw binary. To restore a raw binary file you must use the optional argument -@var{binary} after the filename. +@kindex restore +@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end} +Restore the contents of file @var{filename} into memory. The +@code{restore} command can automatically recognize any known @sc{bfd} +file format, except for raw binary. To restore a raw binary file you +must specify the optional keyword @code{binary} after the filename. -If @var{bias} is non-zero, its value will be added to the addresses +If @var{bias} is non-zero, its value will be added to the addresses contained in the file. Binary files always start at address zero, so they will be restored at address @var{bias}. Other bfd files have a built-in location; they will be restored at offset @var{bias} @@ -5924,7 +6182,7 @@ from that location. If @var{start} and/or @var{end} are non-zero, then only data between file offset @var{start} and file offset @var{end} will be restored. -These offsets are relative to the addresses in the file, before +These offsets are relative to the addresses in the file, before the @var{bias} argument is applied. @end table @@ -5950,7 +6208,7 @@ remote protocol (@pxref{Remote,Remote Debugging}) to debug a program running on an IBM mainframe, which uses the @sc{ebcdic} character set, then the host character set is Latin-1, and the target character set is @sc{ebcdic}. If you give @value{GDBN} the command @code{set -target-charset ebcdic-us}, then @value{GDBN} translates between +target-charset EBCDIC-US}, then @value{GDBN} translates between @sc{ebcdic} and Latin 1 as you print character or string values, or use character and string literals in expressions. @@ -5965,9 +6223,9 @@ support: @item set target-charset @var{charset} @kindex set target-charset Set the current target character set to @var{charset}. We list the -character set names @value{GDBN} recognizes below, but if you invoke the -@code{set target-charset} command with no argument, @value{GDBN} lists -the character sets it supports. +character set names @value{GDBN} recognizes below, but if you type +@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will +list the target character sets it supports. @end table @table @code @@ -5981,28 +6239,29 @@ system it is running on; you can override that default using the @value{GDBN} can only use certain character sets as its host character set. We list the character set names @value{GDBN} recognizes below, and -indicate which can be host character sets, but if you invoke the -@code{set host-charset} command with no argument, @value{GDBN} lists the -character sets it supports, placing an asterisk (@samp{*}) after those -it can use as a host character set. +indicate which can be host character sets, but if you type +@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will +list the host character sets it supports. @item set charset @var{charset} @kindex set charset -Set the current host and target character sets to @var{charset}. If you -invoke the @code{set charset} command with no argument, it lists the -character sets it supports. @value{GDBN} can only use certain character -sets as its host character set; it marks those in the list with an -asterisk (@samp{*}). +Set the current host and target character sets to @var{charset}. As +above, if you type @code{set charset} followed by @key{TAB}@key{TAB}, +@value{GDBN} will list the name of the character sets that can be used +for both host and target. + @item show charset -@itemx show host-charset -@itemx show target-charset @kindex show charset +Show the names of the current host and target charsets. + +@itemx show host-charset @kindex show host-charset +Show the name of the current host charset. + +@itemx show target-charset @kindex show target-charset -Show the current host and target charsets. The @code{show host-charset} -and @code{show target-charset} commands are synonyms for @code{show -charset}. +Show the name of the current target charset. @end table @@ -6019,7 +6278,7 @@ character set. @item ISO-8859-1 @cindex ISO 8859-1 character set @cindex ISO Latin 1 character set -The ISO Latin 1 character set. This extends ASCII with accented +The ISO Latin 1 character set. This extends @sc{ascii} with accented characters needed for French, German, and Spanish. @value{GDBN} can use this as its host character set. @@ -6069,7 +6328,7 @@ $ gdb -nw charset-test GNU gdb 2001-12-19-cvs Copyright 2001 Free Software Foundation, Inc. @dots{} -(gdb) +(gdb) @end smallexample We can use the @code{show charset} command to see what character sets @@ -6078,17 +6337,17 @@ strings: @smallexample (gdb) show charset -The current host and target character set is `iso-8859-1'. -(gdb) +The current host and target character set is `ISO-8859-1'. +(gdb) @end smallexample For the sake of printing this manual, let's use @sc{ascii} as our initial character set: @smallexample -(gdb) set charset ascii +(gdb) set charset ASCII (gdb) show charset -The current host and target character set is `ascii'. -(gdb) +The current host and target character set is `ASCII'. +(gdb) @end smallexample Let's assume that @sc{ascii} is indeed the correct character set for our @@ -6102,7 +6361,7 @@ them properly. Since our current target character set is also $1 = 0x401698 "Hello, world!\n" (gdb) print ascii_hello[0] $2 = 72 'H' -(gdb) +(gdb) @end smallexample @value{GDBN} uses the target character set for character and string @@ -6111,7 +6370,7 @@ literals you use in expressions: @smallexample (gdb) print '+' $3 = 43 '+' -(gdb) +(gdb) @end smallexample The @sc{ascii} character set uses the number 43 to encode the @samp{+} @@ -6126,20 +6385,16 @@ character set is still @sc{ascii}, we get jibberish: $4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" (gdb) print ibm1047_hello[0] $5 = 200 '\310' -(gdb) +(gdb) @end smallexample -If we invoke the @code{set target-charset} command without an argument, +If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} tells us the character sets it supports: @smallexample (gdb) set target-charset -Valid character sets are: - ascii * - iso-8859-1 * - ebcdic-us - ibm1047 -* - can be used as a host character set +ASCII EBCDIC-US IBM1047 ISO-8859-1 +(gdb) set target-charset @end smallexample We can select @sc{ibm1047} as our target character set, and examine the @@ -6149,10 +6404,10 @@ target character set, @sc{ibm1047}, to the host character set, @sc{ascii}, and they display correctly: @smallexample -(gdb) set target-charset ibm1047 +(gdb) set target-charset IBM1047 (gdb) show charset -The current host character set is `ascii'. -The current target character set is `ibm1047'. +The current host character set is `ASCII'. +The current target character set is `IBM1047'. (gdb) print ascii_hello $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" (gdb) print ascii_hello[0] @@ -6170,17 +6425,17 @@ string literals you use in expressions: @smallexample (gdb) print '+' $10 = 78 '+' -(gdb) +(gdb) @end smallexample -The IBM1047 character set uses the number 78 to encode the @samp{+} +The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} character. @node Macros @chapter C Preprocessor Macros -Some languages, such as C and C++, provide a way to define and invoke +Some languages, such as C and C@t{++}, provide a way to define and invoke ``preprocessor macros'' which expand into strings of tokens. @value{GDBN} can evaluate expressions containing macro invocations, show the result of macro expansion, and show a macro's definition, including @@ -6341,7 +6596,7 @@ Defined at /home/jimb/gdb/macros/play/sample.h:1 expands to: (42 + 1) (gdb) macro expand-once ADD(1) expands to: once (M + 1) -(gdb) +(gdb) @end smallexample In the example above, note that @command{macro expand-once} expands only @@ -6356,11 +6611,11 @@ the source line of the current stack frame: (gdb) break main Breakpoint 1 at 0x8048370: file sample.c, line 10. (gdb) run -Starting program: /home/jimb/gdb/macros/play/sample +Starting program: /home/jimb/gdb/macros/play/sample Breakpoint 1, main () at sample.c:10 10 printf ("Hello, world!\n"); -(gdb) +(gdb) @end smallexample At line 10, the definition of the macro @code{N} at line 9 is in force: @@ -6373,7 +6628,7 @@ Defined at /home/jimb/gdb/macros/play/sample.c:9 expands to: 28 < 42 (gdb) print N Q M $1 = 1 -(gdb) +(gdb) @end smallexample As we step over directives that remove @code{N}'s definition, and then @@ -6397,7 +6652,7 @@ Defined at /home/jimb/gdb/macros/play/sample.c:13 expands to: 1729 < 42 (gdb) print N Q M $2 = 0 -(gdb) +(gdb) @end smallexample @@ -6436,9 +6691,9 @@ tracepoints as of this writing. This chapter describes the tracepoint commands and features. @menu -* Set Tracepoints:: -* Analyze Collected Data:: -* Tracepoint Variables:: +* Set Tracepoints:: +* Analyze Collected Data:: +* Tracepoint Variables:: @end menu @node Set Tracepoints @@ -6463,12 +6718,12 @@ This section describes commands to set tracepoints and associated conditions and actions. @menu -* Create and Delete Tracepoints:: -* Enable and Disable Tracepoints:: -* Tracepoint Passcounts:: -* Tracepoint Actions:: -* Listing Tracepoints:: -* Starting and Stopping Trace Experiment:: +* Create and Delete Tracepoints:: +* Enable and Disable Tracepoints:: +* Tracepoint Passcounts:: +* Tracepoint Actions:: +* Listing Tracepoints:: +* Starting and Stopping Trace Experiment:: @end menu @node Create and Delete Tracepoints @@ -6567,7 +6822,7 @@ user. Examples: @smallexample -(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of +(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} (@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the @@ -7279,7 +7534,7 @@ name normally: @smallexample (gdb) overlay list -Section .ov.foo.text, loaded at 0x100000 - 0x100034, +Section .ov.foo.text, loaded at 0x100000 - 0x100034, mapped at 0x1016 - 0x104a (gdb) print foo $6 = @{int (int)@} 0x1016 @@ -7362,7 +7617,7 @@ will silently set a breakpoint there. If the overlay manager then calls this function whenever it has changed the overlay table, this will enable @value{GDBN} to accurately keep track of which overlays are in program memory, and update any breakpoints that may be set -in overlays. This will allow breakpoints to work even if the +in overlays. This will allow breakpoints to work even if the overlays are kept in ROM or other non-writable memory while they are not being executed. @@ -7442,6 +7697,7 @@ language}. * Show:: Displaying the language * Checks:: Type and range checks * Support:: Supported languages +* Unsupported languages:: Unsupported languages @end menu @node Setting @@ -7497,6 +7753,9 @@ C source file @itemx .c++ C@t{++} source file +@item .m +Objective-C source file + @item .f @itemx .F Fortran source file @@ -7772,7 +8031,7 @@ being set automatically by @value{GDBN}. @node Support @section Supported languages -@value{GDBN} supports C, C@t{++}, Fortran, Java, assembly, and Modula-2. +@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, and Modula-2. @c This is false ... Some @value{GDBN} features may be used in expressions regardless of the language you use: the @value{GDBN} @code{@@} and @code{::} operators, @@ -7789,8 +8048,9 @@ books written on each of these languages; please look to these for a language reference or tutorial. @menu -* C:: C and C@t{++} -* Modula-2:: Modula-2 +* C:: C and C@t{++} +* Objective-C:: Objective-C +* Modula-2:: Modula-2 @end menu @node C @@ -7812,11 +8072,12 @@ effectively, you must compile your C@t{++} programs with a supported C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} compiler (@code{aCC}). -For best results when using @sc{gnu} C@t{++}, use the stabs debugging -format. You can select that format explicitly with the @code{g++} -command-line options @samp{-gstabs} or @samp{-gstabs+}. See -@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu} -CC, gcc.info, Using @sc{gnu} CC}, for more information. +For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging +format; if it doesn't work on your system, try the stabs+ debugging +format. You can select those formats explicitly with the @code{g++} +command-line options @option{-gdwarf-2} and @option{-gstabs+}. +@xref{Debugging Options,,Options for Debugging Your Program or @sc{gnu} +CC, gcc.info, Using @sc{gnu} CC}. @menu * C Operators:: C and C@t{++} operators @@ -8062,28 +8323,21 @@ and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. @cindex expressions in C@t{++} @value{GDBN} expression handling can interpret most C@t{++} expressions. -@cindex C@t{++} support, not in @sc{coff} -@cindex @sc{coff} versus C@t{++} -@cindex C@t{++} and object formats -@cindex object formats and C@t{++} -@cindex a.out and C@t{++} -@cindex @sc{ecoff} and C@t{++} -@cindex @sc{xcoff} and C@t{++} -@cindex @sc{elf}/stabs and C@t{++} -@cindex @sc{elf}/@sc{dwarf} and C@t{++} -@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check -@c periodically whether this has happened... +@cindex debugging C@t{++} programs +@cindex C@t{++} compilers +@cindex debug formats and C@t{++} +@cindex @value{NGCC} and C@t{++} @quotation @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the -proper compiler. Typically, C@t{++} debugging depends on the use of -additional debugging information in the symbol table, and thus requires -special support. In particular, if your compiler generates a.out, MIPS -@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the -symbol table, these facilities are all available. (With @sc{gnu} CC, -you can use the @samp{-gstabs} option to request stabs debugging -extensions explicitly.) Where the object code format is standard -@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++} -support in @value{GDBN} does @emph{not} work. +proper compiler and the proper debug format. Currently, @value{GDBN} +works best when debugging C@t{++} code that is compiled with +@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options +@option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over +stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or +stabs+ as their default debug format, so you usually don't need to +specify a debug format explicitly. Other compilers and/or debug formats +are likely to work badly or not at all when using @value{GDBN} to debug +C@t{++} code. @end quotation @enumerate @@ -8313,7 +8567,106 @@ available choices, or to finish the type list for you. @xref{Completion,, Command completion}, for details on how to do this. @end table -@node Modula-2 +@node Objective-C +@subsection Objective-C + +@cindex Objective-C +This section provides information about some commands and command +options that are useful for debugging Objective-C code. + +@menu +* Method Names in Commands:: +* The Print Command with Objective-C:: +@end menu + +@node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C +@subsubsection Method Names in Commands + +The following commands have been extended to accept Objective-C method +names as line specifications: + +@kindex clear@r{, and Objective-C} +@kindex break@r{, and Objective-C} +@kindex info line@r{, and Objective-C} +@kindex jump@r{, and Objective-C} +@kindex list@r{, and Objective-C} +@itemize +@item @code{clear} +@item @code{break} +@item @code{info line} +@item @code{jump} +@item @code{list} +@end itemize + +A fully qualified Objective-C method name is specified as + +@smallexample +-[@var{Class} @var{methodName}] +@end smallexample + +where the minus sign is used to indicate an instance method and a +plus sign (not shown) is used to indicate a class method. The class +name @var{Class} and method name @var{methodName} are enclosed in +brackets, similar to the way messages are specified in Objective-C +source code. For example, to set a breakpoint at the @code{create} +instance method of class @code{Fruit} in the program currently being +debugged, enter: + +@smallexample +break -[Fruit create] +@end smallexample + +To list ten program lines around the @code{initialize} class method, +enter: + +@smallexample +list +[NSText initialize] +@end smallexample + +In the current version of @value{GDBN}, the plus or minus sign is +required. In future versions of @value{GDBN}, the plus or minus +sign will be optional, but you can use it to narrow the search. It +is also possible to specify just a method name: + +@smallexample +break create +@end smallexample + +You must specify the complete method name, including any colons. If +your program's source files contain more than one @code{create} method, +you'll be presented with a numbered list of classes that implement that +method. Indicate your choice by number, or type @samp{0} to exit if +none apply. + +As another example, to clear a breakpoint established at the +@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter: + +@smallexample +clear -[NSWindow makeKeyAndOrderFront:] +@end smallexample + +@node The Print Command with Objective-C +@subsubsection The Print Command With Objective-C +@kindex print-object +@kindex po @r{(@code{print-object})} + +The print command has also been extended to accept methods. For example: + +@smallexample +print -[@var{object} hash] +@end smallexample + +@cindex print an Objective-C object description +@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects +@noindent +will tell @value{GDBN} to send the @code{hash} message to @var{object} +and print the result. Also, an additional command has been added, +@code{print-object} or @code{po} for short, which is meant to print +the description of an object. However, this command may only work +with certain Objective-C libraries that have a particular hook +function, @code{_NSPrintForDebugger}, defined. + +@node Modula-2, , Objective-C, Support @subsection Modula-2 @cindex Modula-2, @value{GDBN} support @@ -8756,6 +9109,22 @@ address can be specified by an integral constant, the construct In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is interpreted as the beginning of a comment. Use @code{<>} instead. +@node Unsupported languages +@section Unsupported languages + +@cindex unsupported languages +@cindex minimal language +In addition to the other fully-supported programming languages, +@value{GDBN} also provides a pseudo-language, called @code{minimal}. +It does not represent a real programming language, but provides a set +of capabilities close to what the C or assembly languages provide. +This should allow most simple operations to be performed while debugging +an application that uses a language currently not supported by @value{GDBN}. + +If the language is set to @code{auto}, @value{GDBN} will automatically +select this language if the current frame corresponds to an unsupported +language. + @node Symbols @chapter Examining the Symbol Table @@ -8939,8 +9308,8 @@ Print the names and data types of all defined functions whose names contain a match for regular expression @var{regexp}. Thus, @samp{info fun step} finds all functions whose names include @code{step}; @samp{info fun ^step} finds those whose names -start with @code{step}. If a function name contains characters -that conflict with the regular expression language (eg. +start with @code{step}. If a function name contains characters +that conflict with the regular expression language (eg. @samp{operator*()}), they may be quoted with a backslash. @kindex info variables @@ -8953,6 +9322,20 @@ Print the names and data types of all variables (except for local variables) whose names contain a match for regular expression @var{regexp}. +@kindex info classes +@item info classes +@itemx info classes @var{regexp} +Display all Objective-C classes in your program, or +(with the @var{regexp} argument) all those matching a particular regular +expression. + +@kindex info selectors +@item info selectors +@itemx info selectors @var{regexp} +Display all Objective-C selectors in your program, or +(with the @var{regexp} argument) all those matching a particular regular +expression. + @ignore This was never implemented. @kindex info methods @@ -9037,8 +9420,66 @@ files that @value{GDBN} has skimmed, but not yet read completely. Finally, required for each object file from which @value{GDBN} has read some symbols. @xref{Files, ,Commands to specify files}, for a discussion of how @value{GDBN} reads symbols (in the description of @code{symbol-file}). + +@kindex maint info symtabs +@kindex maint info psymtabs +@cindex listing @value{GDBN}'s internal symbol tables +@cindex symbol tables, listing @value{GDBN}'s internal +@cindex full symbol tables, listing @value{GDBN}'s internal +@cindex partial symbol tables, listing @value{GDBN}'s internal +@item maint info symtabs @r{[} @var{regexp} @r{]} +@itemx maint info psymtabs @r{[} @var{regexp} @r{]} + +List the @code{struct symtab} or @code{struct partial_symtab} +structures whose names match @var{regexp}. If @var{regexp} is not +given, list them all. The output includes expressions which you can +copy into a @value{GDBN} debugging this one to examine a particular +structure in more detail. For example: + +@smallexample +(@value{GDBP}) maint info psymtabs dwarf2read +@{ objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + @{ psymtab /home/gnu/src/gdb/dwarf2read.c + ((struct partial_symtab *) 0x8474b10) + readin no + fullname (null) + text addresses 0x814d3c8 -- 0x8158074 + globals (* (struct partial_symbol **) 0x8507a08 @@ 9) + statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882) + dependencies (none) + @} +@} +(@value{GDBP}) maint info symtabs +(@value{GDBP}) +@end smallexample +@noindent +We see that there is one partial symbol table whose filename contains +the string @samp{dwarf2read}, belonging to the @samp{gdb} executable; +and we see that @value{GDBN} has not read in any symtabs yet at all. +If we set a breakpoint on a function, that will cause @value{GDBN} to +read the symtab for the compilation unit containing that function: + +@smallexample +(@value{GDBP}) break dwarf2_psymtab_to_symtab +Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, +line 1574. +(@value{GDBP}) maint info symtabs +@{ objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + @{ symtab /home/gnu/src/gdb/dwarf2read.c + ((struct symtab *) 0x86c1f38) + dirname (null) + fullname (null) + blockvector ((struct blockvector *) 0x86c1bd0) (primary) + debugformat DWARF 2 + @} +@} +(@value{GDBP}) +@end smallexample @end table + @node Altering @chapter Altering Execution @@ -9548,7 +9989,7 @@ Some embedded operating systems, like Sun Chorus and VxWorks, can load relocatable files into an already running program; such systems typically make the requirements above easy to meet. However, it's important to recognize that many native systems use complex link -procedures (@code{.linkonce} section factoring and C++ constructor table +procedures (@code{.linkonce} section factoring and C@t{++} constructor table assembly, for example) that make the requirements difficult to meet. In general, one cannot assume that using @code{add-symbol-file} to read a relocatable object file's symbolic information will have the same effect @@ -9969,7 +10410,7 @@ gnu_debuglink_crc32 (unsigned long crc, crc = ~crc & 0xffffffff; for (end = buf + len; buf < end; ++buf) crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); - return ~crc & 0xffffffff;; + return ~crc & 0xffffffff; @} @end smallexample @@ -10262,7 +10703,7 @@ specifies a fixed address. @cindex choosing target byte order @cindex target byte order -Some types of processors, such as the MIPS, PowerPC, and Hitachi SH, +Some types of processors, such as the MIPS, PowerPC, and Renesas SH, offer the ability to run either big-endian or little-endian byte orders. Usually the executable or symbol will include a bit to designate the endian-ness, and you will not need to worry about @@ -10314,9 +10755,7 @@ configuration of @value{GDBN}; use @code{help target} to list them. @node KOD @section Kernel Object Display - @cindex kernel object display -@cindex kernel object @cindex KOD Some targets support kernel object display. Using this facility, @@ -10325,6 +10764,7 @@ and can display information about operating system-level objects such as mutexes and other synchronization objects. Exactly which objects can be displayed is determined on a per-OS basis. +@kindex set os Use the @code{set os} command to set the operating system. This tells @value{GDBN} which kernel object display module to initialize: @@ -10332,11 +10772,17 @@ Use the @code{set os} command to set the operating system. This tells (@value{GDBP}) set os cisco @end smallexample +@kindex show os +The associated command @code{show os} displays the operating system +set with the @code{set os} command; if no operating system has been +set, @code{show os} will display an empty string @samp{""}. + If @code{set os} succeeds, @value{GDBN} will display some information about the operating system, and will create a new @code{info} command which can be used to query the target. The @code{info} command is named after the operating system: +@kindex info cisco @smallexample (@value{GDBP}) info cisco List of Cisco Kernel Objects @@ -10347,19 +10793,122 @@ any Any and all objects Further subcommands can be used to query about particular objects known by the kernel. -There is currently no way to determine whether a given operating system -is supported other than to try it. +There is currently no way to determine whether a given operating +system is supported other than to try setting it with @kbd{set os +@var{name}}, where @var{name} is the name of the operating system you +want to try. @node Remote Debugging @chapter Debugging remote programs @menu +* Connecting:: Connecting to a remote target * Server:: Using the gdbserver program * NetWare:: Using the gdbserve.nlm program +* Remote configuration:: Remote configuration * remote stub:: Implementing a remote stub @end menu +@node Connecting +@section Connecting to a remote target + +On the @value{GDBN} host machine, you will need an unstripped copy of +your program, since @value{GDBN} needs symobl and debugging information. +Start up @value{GDBN} as usual, using the name of the local copy of your +program as the first argument. + +@cindex serial line, @code{target remote} +If you're using a serial line, you may want to give @value{GDBN} the +@w{@samp{--baud}} option, or use the @code{set remotebaud} command +before the @code{target} command. + +After that, use @code{target remote} to establish communications with +the target machine. Its argument specifies how to communicate---either +via a devicename attached to a direct serial line, or a TCP or UDP port +(possibly to a terminal server which in turn has a serial line to the +target). For example, to use a serial line connected to the device +named @file{/dev/ttyb}: + +@smallexample +target remote /dev/ttyb +@end smallexample + +@cindex TCP port, @code{target remote} +To use a TCP connection, use an argument of the form +@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}. +For example, to connect to port 2828 on a +terminal server named @code{manyfarms}: + +@smallexample +target remote manyfarms:2828 +@end smallexample + +If your remote target is actually running on the same machine as +your debugger session (e.g.@: a simulator of your target running on +the same host), you can omit the hostname. For example, to connect +to port 1234 on your local machine: + +@smallexample +target remote :1234 +@end smallexample +@noindent + +Note that the colon is still required here. + +@cindex UDP port, @code{target remote} +To use a UDP connection, use an argument of the form +@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828 +on a terminal server named @code{manyfarms}: + +@smallexample +target remote udp:manyfarms:2828 +@end smallexample + +When using a UDP connection for remote debugging, you should keep in mind +that the `U' stands for ``Unreliable''. UDP can silently drop packets on +busy or unreliable networks, which will cause havoc with your debugging +session. + +Now you can use all the usual commands to examine and change data and to +step and continue the remote program. + +@cindex interrupting remote programs +@cindex remote programs, interrupting +Whenever @value{GDBN} is waiting for the remote program, if you type the +interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the +program. This may or may not succeed, depending in part on the hardware +and the serial drivers the remote system uses. If you type the +interrupt character once again, @value{GDBN} displays this prompt: + +@smallexample +Interrupted while waiting for the program. +Give up (and stop debugging it)? (y or n) +@end smallexample + +If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. +(If you decide you want to try again later, you can use @samp{target +remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} +goes back to waiting. + +@table @code +@kindex detach (remote) +@item detach +When you have finished debugging the remote program, you can use the +@code{detach} command to release it from @value{GDBN} control. +Detaching from the target normally resumes its execution, but the results +will depend on your particular remote stub. After the @code{detach} +command, @value{GDBN} is free to connect to another target. + +@kindex disconnect +@item disconnect +The @code{disconnect} command behaves like @code{detach}, except that +the target is generally not resumed. It will wait for @value{GDBN} +(this instance or another one) to connect and continue debugging. After +the @code{disconnect} command, @value{GDBN} is again free to connect to +another target. +@end table + @node Server @section Using the @code{gdbserver} program @@ -10442,34 +10991,28 @@ target> gdbserver @var{comm} --attach @var{pid} @var{pid} is the process ID of a currently running process. It isn't necessary to point @code{gdbserver} at a binary for the running process. -@item On the @value{GDBN} host machine, -you need an unstripped copy of your program, since @value{GDBN} needs -symbols and debugging information. Start up @value{GDBN} as usual, -using the name of the local copy of your program as the first argument. -(You may also need the @w{@samp{--baud}} option if the serial line is -running at anything other than 9600@dmn{bps}.) After that, use @code{target -remote} to establish communications with @code{gdbserver}. Its argument -is either a device name (usually a serial device, like -@file{/dev/ttyb}), or a TCP port descriptor in the form -@code{@var{host}:@var{PORT}}. For example: +@pindex pidof +@cindex attach to a program by name +You can debug processes by name instead of process ID if your target has the +@code{pidof} utility: @smallexample -(@value{GDBP}) target remote /dev/ttyb +target> gdbserver @var{comm} --attach `pidof @var{PROGRAM}` @end smallexample -@noindent -communicates with the server via serial line @file{/dev/ttyb}, and - -@smallexample -(@value{GDBP}) target remote the-target:2345 -@end smallexample +In case more than one copy of @var{PROGRAM} is running, or @var{PROGRAM} +has multiple threads, most versions of @code{pidof} support the +@code{-s} option to only return the first process ID. -@noindent -communicates via a TCP connection to port 2345 on host @w{@file{the-target}}. +@item On the host machine, +connect to your target (@pxref{Connecting,,Connecting to a remote target}). For TCP connections, you must start up @code{gdbserver} prior to using the @code{target remote} command. Otherwise you may get an error whose text depends on the host system, but which usually looks something like -@samp{Connection refused}. +@samp{Connection refused}. You don't need to use the @code{load} +command in @value{GDBN} when using gdbserver, since the program is +already on the target. + @end table @node NetWare @@ -10511,22 +11054,27 @@ using a 19200@dmn{bps} connection: load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt @end smallexample -@item On the @value{GDBN} host machine, -you need an unstripped copy of your program, since @value{GDBN} needs -symbols and debugging information. Start up @value{GDBN} as usual, -using the name of the local copy of your program as the first argument. -(You may also need the @w{@samp{--baud}} option if the serial line is -running at anything other than 9600@dmn{bps}. After that, use @code{target -remote} to establish communications with @code{gdbserve.nlm}. Its -argument is a device name (usually a serial device, like -@file{/dev/ttyb}). For example: +@item +On the @value{GDBN} host machine, connect to your target (@pxref{Connecting,, +Connecting to a remote target}). -@smallexample -(@value{GDBP}) target remote /dev/ttyb -@end smallexample +@end table -@noindent -communications with the server via serial line @file{/dev/ttyb}. +@node Remote configuration +@section Remote configuration + +The following configuration options are available when debugging remote +programs: + +@table @code +@kindex set remote hardware-watchpoint-limit +@kindex set remote hardware-breakpoint-limit +@anchor{set remote hardware-watchpoint-limit} +@anchor{set remote hardware-breakpoint-limit} +@item set remote hardware-watchpoint-limit @var{limit} +@itemx set remote hardware-breakpoint-limit @var{limit} +Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or +watchpoints. A limit of -1, the default, is treated as unlimited. @end table @node remote stub @@ -10609,9 +11157,9 @@ For Motorola 680x0 architectures. @item sh-stub.c @cindex @file{sh-stub.c} -@cindex Hitachi +@cindex Renesas @cindex SH -For Hitachi SH architectures. +For Renesas SH architectures. @item sparc-stub.c @cindex @file{sparc-stub.c} @@ -10831,93 +11379,17 @@ Download your program to your target machine (or get it there by whatever means the manufacturer provides), and start it. @item -To start remote debugging, run @value{GDBN} on the host machine, and specify -as an executable file the program that is running in the remote machine. -This tells @value{GDBN} how to find your program's symbols and the contents -of its pure text. - -@item -@cindex serial line, @code{target remote} -Establish communication using the @code{target remote} command. -Its argument specifies how to communicate with the target -machine---either via a devicename attached to a direct serial line, or a -TCP or UDP port (usually to a terminal server which in turn has a serial line -to the target). For example, to use a serial line connected to the -device named @file{/dev/ttyb}: +Start @value{GDBN} on the host, and connect to the target +(@pxref{Connecting,,Connecting to a remote target}). -@smallexample -target remote /dev/ttyb -@end smallexample +@end enumerate -@cindex TCP port, @code{target remote} -To use a TCP connection, use an argument of the form -@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}. -For example, to connect to port 2828 on a -terminal server named @code{manyfarms}: +@node Configurations +@chapter Configuration-Specific Information -@smallexample -target remote manyfarms:2828 -@end smallexample - -If your remote target is actually running on the same machine as -your debugger session (e.g.@: a simulator of your target running on -the same host), you can omit the hostname. For example, to connect -to port 1234 on your local machine: - -@smallexample -target remote :1234 -@end smallexample -@noindent - -Note that the colon is still required here. - -@cindex UDP port, @code{target remote} -To use a UDP connection, use an argument of the form -@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828 -on a terminal server named @code{manyfarms}: - -@smallexample -target remote udp:manyfarms:2828 -@end smallexample - -When using a UDP connection for remote debugging, you should keep in mind -that the `U' stands for ``Unreliable''. UDP can silently drop packets on -busy or unreliable networks, which will cause havoc with your debugging -session. - -@end enumerate - -Now you can use all the usual commands to examine and change data and to -step and continue the remote program. - -To resume the remote program and stop debugging it, use the @code{detach} -command. - -@cindex interrupting remote programs -@cindex remote programs, interrupting -Whenever @value{GDBN} is waiting for the remote program, if you type the -interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the -program. This may or may not succeed, depending in part on the hardware -and the serial drivers the remote system uses. If you type the -interrupt character once again, @value{GDBN} displays this prompt: - -@smallexample -Interrupted while waiting for the program. -Give up (and stop debugging it)? (y or n) -@end smallexample - -If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. -(If you decide you want to try again later, you can use @samp{target -remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} -goes back to waiting. - - -@node Configurations -@chapter Configuration-Specific Information - -While nearly all @value{GDBN} commands are available for all native and -cross versions of the debugger, there are some exceptions. This chapter -describes things that are only available in certain configurations. +While nearly all @value{GDBN} commands are available for all native and +cross versions of the debugger, there are some exceptions. This chapter +describes things that are only available in certain configurations. There are three major categories of configurations: native configurations, where the host and target are the same, embedded @@ -11105,10 +11577,10 @@ accepts addresses which may belong to @emph{any} segment. For example, here's how to display the Page Table entry for the page where the variable @code{i} is stored: -@smallexample +@smallexample @exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} @exdent @code{Page Table entry for address 0x11a00d30:} -@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} +@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} @end smallexample @noindent @@ -11147,9 +11619,12 @@ This command is supported only with some DPMI servers. @cindex native Cygwin debugging @cindex Cygwin-specific commands -@value{GDBN} supports native debugging of MS Windows programs, and -defines a few commands specific to the Cygwin port. This -subsection describes those commands. +@value{GDBN} supports native debugging of MS Windows programs, including +DLLs with and without symbolic debugging information. There are various +additional Cygwin-specific commands, described in this subsection. The +subsubsection @pxref{Non-debug DLL symbols} describes working with DLLs +that have no debugging symbols. + @table @code @kindex info w32 @@ -11174,9 +11649,9 @@ This is a Cygwin specific alias of info shared. This command loads symbols from a dll similarly to add-sym command but without the need to specify a base address. -@kindex set new-console +@kindex set new-console @item set new-console @var{mode} -If @var{mode} is @code{on} the debuggee will +If @var{mode} is @code{on} the debuggee will be started in a new console on next start. If @var{mode} is @code{off}i, the debuggee will be started in the same console as the debugger. @@ -11203,17 +11678,17 @@ This boolean value adds debug output concerning events seen by the debugger. @kindex set debugexec @item set debugexec -This boolean value adds debug output concerning execute events +This boolean value adds debug output concerning execute events seen by the debugger. @kindex set debugexceptions @item set debugexceptions -This boolean value adds debug ouptut concerning exception events +This boolean value adds debug ouptut concerning exception events seen by the debugger. @kindex set debugmemory @item set debugmemory -This boolean value adds debug ouptut concerning memory events +This boolean value adds debug ouptut concerning memory events seen by the debugger. @kindex set shell @@ -11227,6 +11702,130 @@ Displays if the debuggee will be started with a shell. @end table +@menu +* Non-debug DLL symbols:: Support for DLLs without debugging symbols +@end menu + +@node Non-debug DLL symbols +@subsubsection Support for DLLs without debugging symbols +@cindex DLLs with no debugging symbols +@cindex Minimal symbols and DLLs + +Very often on windows, some of the DLLs that your program relies on do +not include symbolic debugging information (for example, +@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging +symbols in a DLL, it relies on the minimal amount of symbolic +information contained in the DLL's export table. This subsubsection +describes working with such symbols, known internally to @value{GDBN} as +``minimal symbols''. + +Note that before the debugged program has started execution, no DLLs +will have been loaded. The easiest way around this problem is simply to +start the program --- either by setting a breakpoint or letting the +program run once to completion. It is also possible to force +@value{GDBN} to load a particular DLL before starting the executable --- +see the shared library information in @pxref{Files} or the +@code{dll-symbols} command in @pxref{Cygwin Native}. Currently, +explicitly loading symbols from a DLL with no debugging information will +cause the symbol names to be duplicated in @value{GDBN}'s lookup table, +which may adversely affect symbol lookup performance. + +@subsubsection DLL name prefixes + +In keeping with the naming conventions used by the Microsoft debugging +tools, DLL export symbols are made available with a prefix based on the +DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is +also entered into the symbol table, so @code{CreateFileA} is often +sufficient. In some cases there will be name clashes within a program +(particularly if the executable itself includes full debugging symbols) +necessitating the use of the fully qualified name when referring to the +contents of the DLL. Use single-quotes around the name to avoid the +exclamation mark (``!'') being interpreted as a language operator. + +Note that the internal name of the DLL may be all upper-case, even +though the file name of the DLL is lower-case, or vice-versa. Since +symbols within @value{GDBN} are @emph{case-sensitive} this may cause +some confusion. If in doubt, try the @code{info functions} and +@code{info variables} commands or even @code{maint print msymbols} (see +@pxref{Symbols}). Here's an example: + +@smallexample +(gdb) info function CreateFileA +All functions matching regular expression "CreateFileA": + +Non-debugging symbols: +0x77e885f4 CreateFileA +0x77e885f4 KERNEL32!CreateFileA +@end smallexample + +@smallexample +(gdb) info function ! +All functions matching regular expression "!": + +Non-debugging symbols: +0x6100114c cygwin1!__assert +0x61004034 cygwin1!_dll_crt0@@0 +0x61004240 cygwin1!dll_crt0(per_process *) +[etc...] +@end smallexample + +@subsubsection Working with minimal symbols + +Symbols extracted from a DLL's export table do not contain very much +type information. All that @value{GDBN} can do is guess whether a symbol +refers to a function or variable depending on the linker section that +contains the symbol. Also note that the actual contents of the memory +contained in a DLL are not available unless the program is running. This +means that you cannot examine the contents of a variable or disassemble +a function within a DLL without a running program. + +Variables are generally treated as pointers and dereferenced +automatically. For this reason, it is often necessary to prefix a +variable name with the address-of operator (``&'') and provide explicit +type information in the command. Here's an example of the type of +problem: + +@smallexample +(gdb) print 'cygwin1!__argv' +$1 = 268572168 +@end smallexample + +@smallexample +(gdb) x 'cygwin1!__argv' +0x10021610: "\230y\"" +@end smallexample + +And two possible solutions: + +@smallexample +(gdb) print ((char **)'cygwin1!__argv')[0] +$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" +@end smallexample + +@smallexample +(gdb) x/2x &'cygwin1!__argv' +0x610c0aa8 : 0x10021608 0x00000000 +(gdb) x/x 0x10021608 +0x10021608: 0x0022fd98 +(gdb) x/s 0x0022fd98 +0x22fd98: "/cygdrive/c/mydirectory/myprogram" +@end smallexample + +Setting a break point within a DLL is possible even before the program +starts execution. However, under these circumstances, @value{GDBN} can't +examine the initial instructions of the function in order to skip the +function's frame set-up code. You can work around this by using ``*&'' +to set the breakpoint at a raw memory address: + +@smallexample +(gdb) break *&'python22!PyOS_Readline' +Breakpoint 1 at 0x1e04eff0 +@end smallexample + +The author of these extensions is not entirely convinced that setting a +break point within a shared DLL like @file{kernel32.dll} is completely +safe. + @node Embedded OS @section Embedded Operating Systems @@ -11412,16 +12011,15 @@ configurations. @menu * ARM:: ARM -* H8/300:: Hitachi H8/300 -* H8/500:: Hitachi H8/500 -* i960:: Intel i960 -* M32R/D:: Mitsubishi M32R/D +* H8/300:: Renesas H8/300 +* H8/500:: Renesas H8/500 +* M32R/D:: Renesas M32R/D * M68K:: Motorola M68K * MIPS Embedded:: MIPS Embedded * OpenRISC 1000:: OpenRisc 1000 * PA:: HP PA Embedded * PowerPC: PowerPC -* SH:: Hitachi SH +* SH:: Renesas SH * Sparclet:: Tsqware Sparclet * Sparclite:: Fujitsu Sparclite * ST2000:: Tandem ST2000 @@ -11446,50 +12044,50 @@ ARM Demon monitor. @end table @node H8/300 -@subsection Hitachi H8/300 +@subsection Renesas H8/300 @table @code @kindex target hms@r{, with H8/300} @item target hms @var{dev} -A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. +A Renesas SH, H8/300, or H8/500 board, attached via serial line to your host. Use special commands @code{device} and @code{speed} to control the serial line and the communications speed used. @kindex target e7000@r{, with H8/300} @item target e7000 @var{dev} -E7000 emulator for Hitachi H8 and SH. +E7000 emulator for Renesas H8 and SH. @kindex target sh3@r{, with H8/300} @kindex target sh3e@r{, with H8/300} @item target sh3 @var{dev} @itemx target sh3e @var{dev} -Hitachi SH-3 and SH-3E target systems. +Renesas SH-3 and SH-3E target systems. @end table @cindex download to H8/300 or H8/500 @cindex H8/300 or H8/500 download -@cindex download to Hitachi SH -@cindex Hitachi SH download -When you select remote debugging to a Hitachi SH, H8/300, or H8/500 -board, the @code{load} command downloads your program to the Hitachi +@cindex download to Renesas SH +@cindex Renesas SH download +When you select remote debugging to a Renesas SH, H8/300, or H8/500 +board, the @code{load} command downloads your program to the Renesas board and also opens it as the current executable target for @value{GDBN} on your host (like the @code{file} command). @value{GDBN} needs to know these things to talk to your -Hitachi SH, H8/300, or H8/500: +Renesas SH, H8/300, or H8/500: @enumerate @item that you want to use @samp{target hms}, the remote debugging interface -for Hitachi microprocessors, or @samp{target e7000}, the in-circuit -emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is -the default when @value{GDBN} is configured specifically for the Hitachi SH, +for Renesas microprocessors, or @samp{target e7000}, the in-circuit +emulator for the Renesas SH and the Renesas 300H. (@samp{target hms} is +the default when @value{GDBN} is configured specifically for the Renesas SH, H8/300, or H8/500.) @item -what serial device connects your host to your Hitachi board (the first +what serial device connects your host to your Renesas board (the first serial device available on your host is the default). @item @@ -11497,24 +12095,24 @@ what speed to use over the serial device. @end enumerate @menu -* Hitachi Boards:: Connecting to Hitachi boards. -* Hitachi ICE:: Using the E7000 In-Circuit Emulator. -* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros. +* Renesas Boards:: Connecting to Renesas boards. +* Renesas ICE:: Using the E7000 In-Circuit Emulator. +* Renesas Special:: Special @value{GDBN} commands for Renesas micros. @end menu -@node Hitachi Boards -@subsubsection Connecting to Hitachi boards +@node Renesas Boards +@subsubsection Connecting to Renesas boards @c only for Unix hosts @kindex device -@cindex serial device, Hitachi micros +@cindex serial device, Renesas micros Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you need to explicitly set the serial device. The default @var{port} is the first available port on your host. This is only necessary on Unix hosts, where it is typically something like @file{/dev/ttya}. @kindex speed -@cindex serial line speed, Hitachi micros +@cindex serial line speed, Renesas micros @code{@value{GDBN}} has another special command to set the communications speed: @samp{speed @var{bps}}. This command also is only used from Unix hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with @@ -11522,7 +12120,7 @@ the DOS @code{mode} command (for instance, @w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection). The @samp{device} and @samp{speed} commands are available only when you -use a Unix host to debug your Hitachi microprocessor programs. If you +use a Unix host to debug your Renesas microprocessor programs. If you use a DOS host, @value{GDBN} depends on an auxiliary terminate-and-stay-resident program called @code{asynctsr} to communicate with the development board @@ -11532,7 +12130,7 @@ to set up the serial port on the DOS side. The following sample session illustrates the steps needed to start a program under @value{GDBN} control on an H8/300. The example uses a sample H8/300 program called @file{t.x}. The procedure is the same for -the Hitachi SH and the H8/500. +the Renesas SH and the H8/500. First hook up your development board. In this example, we use a board attached to serial port @code{COM2}; if you use a different serial @@ -11565,7 +12163,7 @@ connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with the name of your program as the argument. @code{@value{GDBN}} prompts you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special commands to begin your debugging session: @samp{target hms} to specify -cross-debugging to the Hitachi board, and the @code{load} command to +cross-debugging to the Renesas board, and the @code{load} command to download your program to the board. @code{load} displays the names of the program's sections, and a @samp{*} for each 2K of data downloaded. (If you want to refresh @value{GDBN} data on symbols or on the @@ -11615,12 +12213,12 @@ to detect program completion. In either case, @value{GDBN} sees the effect of a @sc{reset} on the development board as a ``normal exit'' of your program. -@node Hitachi ICE +@node Renesas ICE @subsubsection Using the E7000 in-circuit emulator -@kindex target e7000@r{, with Hitachi ICE} +@kindex target e7000@r{, with Renesas ICE} You can use the E7000 in-circuit emulator to develop code for either the -Hitachi SH or the H8/300H. Use one of these forms of the @samp{target +Renesas SH or the H8/300H. Use one of these forms of the @samp{target e7000} command to connect @value{GDBN} to your E7000: @table @code @@ -11635,8 +12233,8 @@ If your E7000 is installed as a host on a TCP/IP network, you can just specify its hostname; @value{GDBN} uses @code{telnet} to connect. @end table -@node Hitachi Special -@subsubsection Special @value{GDBN} commands for Hitachi micros +@node Renesas Special +@subsubsection Special @value{GDBN} commands for Renesas micros Some @value{GDBN} commands are available only for the H8/300: @@ -11668,136 +12266,18 @@ memory}. The accepted values for @var{mod} are @code{small}, @end table -@node i960 -@subsection Intel i960 - -@table @code - -@kindex target mon960 -@item target mon960 @var{dev} -MON960 monitor for Intel i960. - -@kindex target nindy -@item target nindy @var{devicename} -An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is -the name of the serial device to use for the connection, e.g. -@file{/dev/ttya}. - -@end table - -@cindex Nindy -@cindex i960 -@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When -@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can -tell @value{GDBN} how to connect to the 960 in several ways: - -@itemize @bullet -@item -Through command line options specifying serial port, version of the -Nindy protocol, and communications speed; - -@item -By responding to a prompt on startup; - -@item -By using the @code{target} command at any point during your @value{GDBN} -session. @xref{Target Commands, ,Commands for managing targets}. - -@end itemize - -@cindex download to Nindy-960 -With the Nindy interface to an Intel 960 board, @code{load} -downloads @var{filename} to the 960 as well as adding its symbols in -@value{GDBN}. - -@menu -* Nindy Startup:: Startup with Nindy -* Nindy Options:: Options for Nindy -* Nindy Reset:: Nindy reset command -@end menu - -@node Nindy Startup -@subsubsection Startup with Nindy - -If you simply start @code{@value{GDBP}} without using any command-line -options, you are prompted for what serial port to use, @emph{before} you -reach the ordinary @value{GDBN} prompt: - -@smallexample -Attach /dev/ttyNN -- specify NN, or "quit" to quit: -@end smallexample - -@noindent -Respond to the prompt with whatever suffix (after @samp{/dev/tty}) -identifies the serial port you want to use. You can, if you choose, -simply start up with no Nindy connection by responding to the prompt -with an empty line. If you do this and later wish to attach to Nindy, -use @code{target} (@pxref{Target Commands, ,Commands for managing targets}). - -@node Nindy Options -@subsubsection Options for Nindy - -These are the startup options for beginning your @value{GDBN} session with a -Nindy-960 board attached: - -@table @code -@item -r @var{port} -Specify the serial port name of a serial interface to be used to connect -to the target system. This option is only available when @value{GDBN} is -configured for the Intel 960 target architecture. You may specify -@var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a -device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique -suffix for a specific @code{tty} (e.g. @samp{-r a}). - -@item -O -(An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use -the ``old'' Nindy monitor protocol to connect to the target system. -This option is only available when @value{GDBN} is configured for the Intel 960 -target architecture. - -@quotation -@emph{Warning:} if you specify @samp{-O}, but are actually trying to -connect to a target system that expects the newer protocol, the connection -fails, appearing to be a speed mismatch. @value{GDBN} repeatedly -attempts to reconnect at several different line speeds. You can abort -this process with an interrupt. -@end quotation - -@item -brk -Specify that @value{GDBN} should first send a @code{BREAK} signal to the target -system, in an attempt to reset it, before connecting to a Nindy target. - -@quotation -@emph{Warning:} Many target systems do not have the hardware that this -requires; it only works with a few boards. -@end quotation -@end table - -The standard @samp{-b} option controls the line speed used on the serial -port. - -@c @group -@node Nindy Reset -@subsubsection Nindy reset command - -@table @code -@item reset -@kindex reset -For a Nindy target, this command sends a ``break'' to the remote target -system; this is only useful if the target has been equipped with a -circuit to perform a hard reset (or some other interesting action) when -a break is detected. -@end table -@c @end group - @node M32R/D -@subsection Mitsubishi M32R/D +@subsection Renesas M32R/D @table @code @kindex target m32r @item target m32r @var{dev} -Mitsubishi M32R/D ROM monitor. +Renesas M32R/D ROM monitor. + +@kindex target m32rsdi +@item target m32rsdi @var{dev} +Renesas M32R SDI server, connected via parallel port to the board. @end table @@ -11831,19 +12311,6 @@ ROM 68K monitor, running on an M68K IDP board. @end table -If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will -instead have only a single special target command: - -@table @code - -@kindex target es1800 -@item target es1800 @var{dev} -ES-1800 emulator for M68K. - -@end table - -[context?] - @table @code @kindex target rombug @@ -12157,25 +12624,25 @@ W89K monitor, running on a Winbond HPPA board. @end table @node SH -@subsection Hitachi SH +@subsection Renesas SH @table @code -@kindex target hms@r{, with Hitachi SH} +@kindex target hms@r{, with Renesas SH} @item target hms @var{dev} -A Hitachi SH board attached via serial line to your host. Use special +A Renesas SH board attached via serial line to your host. Use special commands @code{device} and @code{speed} to control the serial line and the communications speed used. -@kindex target e7000@r{, with Hitachi SH} +@kindex target e7000@r{, with Renesas SH} @item target e7000 @var{dev} -E7000 emulator for Hitachi SH. +E7000 emulator for Renesas SH. @kindex target sh3@r{, with SH} @kindex target sh3e@r{, with SH} @item target sh3 @var{dev} @item target sh3e @var{dev} -Hitachi SH-3 and SH-3E target systems. +Renesas SH-3 and SH-3E target systems. @end table @@ -12794,7 +13261,7 @@ current ABI. @kindex show osabi One @value{GDBN} configuration can debug binaries for multiple operating -system targets, either via remote debugging or native emulation. +system targets, either via remote debugging or native emulation. @value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use, but you can override its conclusion using the @code{set osabi} command. One example where this is useful is in debugging of binaries which use @@ -12838,6 +13305,32 @@ Arguments of type @code{float} will be passed directly to unprototyped functions. @end table +@kindex set cp-abi +@kindex show cp-abi +@value{GDBN} needs to know the ABI used for your program's C@t{++} +objects. The correct C@t{++} ABI depends on which C@t{++} compiler was +used to build your application. @value{GDBN} only fully supports +programs with a single C@t{++} ABI; if your program contains code using +multiple C@t{++} ABI's or if @value{GDBN} can not identify your +program's ABI correctly, you can tell @value{GDBN} which ABI to use. +Currently supported ABI's include ``gnu-v2'', for @code{g++} versions +before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and +``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may +use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is +``auto''. + +@table @code +@item show cp-abi +Show the C@t{++} ABI currently in use. + +@item set cp-abi +With no argument, show the list of supported C@t{++} ABI's. + +@item set cp-abi @var{abi} +@itemx set cp-abi auto +Set the current C@t{++} ABI to @var{abi}, or return to automatic detection. +@end table + @node Messages/Warnings @section Optional warnings and messages @@ -12939,6 +13432,21 @@ default is off. @item show debug expression Displays the current state of displaying @value{GDBN} expression debugging info. +@kindex set debug frame +@item set debug frame +Turns on or off display of @value{GDBN} frame debugging info. The +default is off. +@kindex show debug frame +@item show debug frame +Displays the current state of displaying @value{GDBN} frame debugging +info. +@kindex set debug observer +@item set debug observer +Turns on or off display of @value{GDBN} observer debugging. This +includes info such as the notification of observable events. +@kindex show debug observer +@item show debug observer +Displays the current state of observer debugging. @kindex set debug overload @item set debug overload Turns on or off display of @value{GDBN} C@t{++} overload debugging @@ -12970,7 +13478,9 @@ info. @item set debug target Turns on or off display of @value{GDBN} target debugging info. This info includes what is going on at the target level of GDB, as it happens. The -default is off. +default is 0. Set it to 1 to track events, and to 2 to also track the +value of large memory transfers. Changes to this flag do not take effect +until the next time you connect to a target or use the @code{run} command. @kindex show debug target @item show debug target Displays the current state of displaying @value{GDBN} target debugging @@ -13154,7 +13664,7 @@ end @end smallexample As a further example, to hook at the begining and end of the @code{echo} -command, and to add extra text to the beginning and end of the message, +command, and to add extra text to the beginning and end of the message, you could define: @smallexample @@ -13356,9 +13866,73 @@ string are the simple ones that consist of backslash followed by a letter. @end table +@node Interpreters +@chapter Command Interpreters +@cindex command interpreters + +@value{GDBN} supports multiple command interpreters, and some command +infrastructure to allow users or user interface writers to switch +between interpreters or run commands in other interpreters. + +@value{GDBN} currently supports two command interpreters, the console +interpreter (sometimes called the command-line interpreter or @sc{cli}) +and the machine interface interpreter (or @sc{gdb/mi}). This manual +describes both of these interfaces in great detail. + +By default, @value{GDBN} will start with the console interpreter. +However, the user may choose to start @value{GDBN} with another +interpreter by specifying the @option{-i} or @option{--interpreter} +startup options. Defined interpreters include: + +@table @code +@item console +@cindex console interpreter +The traditional console or command-line interpreter. This is the most often +used interpreter with @value{GDBN}. With no interpreter specified at runtime, +@value{GDBN} will use this interpreter. + +@item mi +@cindex mi interpreter +The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily +by programs wishing to use @value{GDBN} as a backend for a debugger GUI +or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi} +Interface}. + +@item mi2 +@cindex mi2 interpreter +The current @sc{gdb/mi} interface. + +@item mi1 +@cindex mi1 interpreter +The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3. + +@end table + +@cindex invoke another interpreter +The interpreter being used by @value{GDBN} may not be dynamically +switched at runtime. Although possible, this could lead to a very +precarious situation. Consider an IDE using @sc{gdb/mi}. If a user +enters the command "interpreter-set console" in a console view, +@value{GDBN} would switch to using the console interpreter, rendering +the IDE inoperable! + +@kindex interpreter-exec +Although you may only choose a single interpreter at startup, you may execute +commands in any interpreter from the current interpreter using the appropriate +command. If you are running the console interpreter, simply use the +@code{interpreter-exec} command: + +@smallexample +interpreter-exec mi "-data-list-register-names" +@end smallexample + +@sc{gdb/mi} has a similar command, although it is only available in versions of +@value{GDBN} which support @sc{gdb/mi} version 2 (or greater). + @node TUI @chapter @value{GDBN} Text User Interface @cindex TUI +@cindex Text User Interface @menu * TUI Overview:: TUI overview @@ -13368,12 +13942,14 @@ letter. * TUI Configuration:: TUI configuration variables @end menu -The @value{GDBN} Text User Interface, TUI in short, -is a terminal interface which uses the @code{curses} library -to show the source file, the assembly output, the program registers -and @value{GDBN} commands in separate text windows. -The TUI is available only when @value{GDBN} is configured -with the @code{--enable-tui} configure option (@pxref{Configure Options}). +The @value{GDBN} Text User Interface, TUI in short, is a terminal +interface which uses the @code{curses} library to show the source +file, the assembly output, the program registers and @value{GDBN} +commands in separate text windows. + +The TUI is enabled by invoking @value{GDBN} using either +@pindex gdbtui +@samp{gdbtui} or @samp{gdb -tui}. @node TUI Overview @section TUI overview @@ -13411,7 +13987,7 @@ The assembly window shows the disassembly output of the program. @item 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. +changed are highlighted. @end table @@ -13542,6 +14118,14 @@ previous layout and the new one. Think of it as the Emacs @kbd{C-x 2} binding. +@kindex C-x o +@item C-x o +Change the active window. The TUI associates several key bindings +(like scrolling and arrow keys) to the active window. This command +gives the focus to the next TUI window. + +Think of it as the Emacs @kbd{C-x o} binding. + @kindex C-x s @item C-x s Use the TUI @emph{SingleKey} keymap that binds single key to gdb commands @@ -13583,9 +14167,10 @@ Refresh the screen. @end table 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 @key{C-p}, @key{C-n}, -@key{C-b} and @key{C-f}. +for scrolling. This means they are available for readline when the +active window is the command window. When the command window +does not have the focus, it is necessary to use other readline +key bindings such as @key{C-p}, @key{C-n}, @key{C-b} and @key{C-f}. @node TUI Single Key Mode @section TUI Single Key Mode @@ -13593,7 +14178,7 @@ necessary to use other readline key bindings such as @key{C-p}, @key{C-n}, The TUI provides a @emph{SingleKey} mode in which it installs a particular key binding in the readline keymaps to connect single keys to -some gdb commands. +some gdb commands. @table @kbd @kindex c @r{(SingleKey TUI key)} @@ -13695,6 +14280,22 @@ can be affected to another window. @kindex refresh Refresh the screen. This is similar to using @key{C-L} key. +@item tui reg float +@kindex tui reg +Show the floating point registers in the register window. + +@item tui reg general +Show the general registers in the register window. + +@item tui reg next +Show the next register group. The list of register groups as well as +their order is target specific. The predefined register groups are the +following: @code{general}, @code{float}, @code{system}, @code{vector}, +@code{all}, @code{save}, @code{restore}. + +@item tui reg system +Show the system registers in the register window. + @item update @kindex update Update the source window and the current execution point. @@ -13818,36 +14419,26 @@ and the source. Explicit @value{GDBN} @code{list} or search commands still produce output as usual, but you probably have no reason to use them from Emacs. -@quotation -@emph{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. @value{GDBN} can find programs by searching your -environment's @code{PATH} variable, so the @value{GDBN} input and output -session proceeds normally; but Emacs does not get enough information -back from @value{GDBN} to locate the source files in this situation. To -avoid this problem, either start @value{GDBN} mode from the directory where -your program resides, or specify an absolute file name when prompted for the -@kbd{M-x gdb} argument. - -A similar confusion can result if you use the @value{GDBN} @code{file} command to -switch to debugging a program in some other location, from an existing -@value{GDBN} buffer in Emacs. -@end quotation - -By default, @kbd{M-x gdb} calls the program called @file{gdb}. If -you need to call @value{GDBN} by a different name (for example, if you keep -several configurations around, with different names) you can set the -Emacs variable @code{gdb-command-name}; for example, - -@smallexample -(setq gdb-command-name "mygdb") -@end smallexample - -@noindent -(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or -in your @file{.emacs} file) makes Emacs call the program named -``@code{mygdb}'' instead. +If you specify an absolute file name when prompted for the @kbd{M-x +gdb} argument, then Emacs sets your current working directory to where +your program resides. If you only specify the file name, then Emacs +sets your current working directory to to the directory associated +with the previous buffer. In this case, @value{GDBN} may find your +program by searching your environment's @code{PATH} variable, but on +some operating systems it might not find the source. So, although the +@value{GDBN} input and output session proceeds normally, the auxiliary +buffer does not display the current source and line of execution. + +The initial working directory of @value{GDBN} is printed on the top +line of the @value{GDBN} I/O buffer and this serves as a default for +the commands that specify files for @value{GDBN} to operate +on. @xref{Files, ,Commands to specify files}. + +By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you +need to call @value{GDBN} by a different name (for example, if you +keep several configurations around, with different names) you can +customize the Emacs variable @code{gud-gdb-command-name} to run the +one you want. In the @value{GDBN} I/O buffer, you can use these special Emacs commands in addition to the standard Shell mode commands: @@ -13856,66 +14447,47 @@ addition to the standard Shell mode commands: @item C-h m Describe the features of Emacs' @value{GDBN} Mode. -@item M-s +@item C-c C-s Execute to another source line, like the @value{GDBN} @code{step} command; also update the display window to show the current file and location. -@item M-n +@item C-c C-n Execute to next source line in this function, skipping all function calls, like the @value{GDBN} @code{next} command. Then update the display window to show the current file and location. -@item M-i +@item C-c C-i Execute one instruction, like the @value{GDBN} @code{stepi} command; update display window accordingly. -@item M-x gdb-nexti -Execute to next instruction, using the @value{GDBN} @code{nexti} command; update -display window accordingly. - @item C-c C-f Execute until exit from the selected stack frame, like the @value{GDBN} @code{finish} command. -@item M-c +@item C-c C-r Continue execution of your program, like the @value{GDBN} @code{continue} command. -@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}. - -@item M-u +@item C-c < Go up the number of frames indicated by the numeric argument (@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), like the @value{GDBN} @code{up} command. -@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}. - -@item M-d +@item C-c > Go down the number of frames indicated by the numeric argument, like the @value{GDBN} @code{down} command. - -@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}. - -@item C-x & -Read the number where the cursor is positioned, and insert it at the end -of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code -around an address that was displayed earlier, type @kbd{disassemble}; -then move the cursor to the address display, and pick up the -argument for @code{disassemble} by typing @kbd{C-x &}. - -You can customize this further by defining elements of the list -@code{gdb-print-command}; once it is defined, you can format or -otherwise process numbers picked up by @kbd{C-x &} before they are -inserted. A numeric argument to @kbd{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 @code{format}; otherwise the number -is passed as an argument to the corresponding list element. @end table -In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break}) +In any source file, the Emacs command @kbd{C-x SPC} (@code{gud-break}) tells @value{GDBN} to set a breakpoint on the source line point is on. +If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which +shows a backtrace when the @value{GDBN} I/O buffer is current. Move +point to any frame in the stack and type @key{RET} to make it become the +current frame and display the associated source in the source buffer. +Alternatively, click @kbd{Mouse-2} to make the selected frame become the +current one. + If you accidentally delete the source-display buffer, an easy way to get it back is to type the command @code{f} in the @value{GDBN} buffer, to request a frame display; when you run under Emacs, this recreates @@ -13929,6 +14501,10 @@ communicates with Emacs in terms of line numbers. If you add or delete lines from the text, the line numbers that @value{GDBN} knows cease to correspond properly with the code. +The description given here is for GNU Emacs version 21.3 and a more +detailed description of its interaction with @value{GDBN} is given in +the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}). + @c The following dropped because Epoch is nonstandard. Reactivate @c if/when v19 does something similar. ---doc@cygnus.com 19dec1990 @ignore @@ -13943,1707 +14519,7297 @@ environment. Users of this environment can use a new command, each value is printed in its own window. @end ignore -@include annotate.texi -@include gdbmi.texinfo -@node GDB Bugs -@chapter Reporting Bugs in @value{GDBN} -@cindex bugs in @value{GDBN} -@cindex reporting bugs in @value{GDBN} +@node GDB/MI +@chapter The @sc{gdb/mi} Interface -Your bug reports play an essential role in making @value{GDBN} reliable. +@unnumberedsec Function and Purpose -Reporting a bug may help you by bringing a solution to your problem, or it -may not. But in any case the principal function of a bug report is to help -the entire community by making the next version of @value{GDBN} work better. Bug -reports are your contribution to the maintenance of @value{GDBN}. +@cindex @sc{gdb/mi}, its purpose +@sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is +specifically intended to support the development of systems which use +the debugger as just one small component of a larger system. -In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. +This chapter is a specification of the @sc{gdb/mi} interface. It is written +in the form of a reference manual. -@menu -* Bug Criteria:: Have you found a bug? -* Bug Reporting:: How to report bugs -@end menu +Note that @sc{gdb/mi} is still under construction, so some of the +features described below are incomplete and subject to change. -@node Bug Criteria -@section Have you found a bug? -@cindex bug criteria +@unnumberedsec Notation and Terminology -If you are not sure whether you have found a bug, here are some guidelines: +@cindex notational conventions, for @sc{gdb/mi} +This chapter uses the following notation: @itemize @bullet -@cindex fatal signal -@cindex debugger crash -@cindex crash of debugger @item -If the debugger gets a fatal signal, for any input whatever, that is a -@value{GDBN} bug. Reliable debuggers never crash. +@code{|} separates two alternatives. -@cindex error on valid input @item -If @value{GDBN} produces an error message for valid input, that is a -bug. (Note that if you're cross debugging, the problem may also be -somewhere in the connection to the target.) +@code{[ @var{something} ]} indicates that @var{something} is optional: +it may or may not be given. -@cindex invalid input @item -If @value{GDBN} does not produce an error message for invalid input, -that is a bug. However, you should note that your idea of -``invalid input'' might be our idea of ``an extension'' or ``support -for traditional practice''. +@code{( @var{group} )*} means that @var{group} inside the parentheses +may repeat zero or more times. @item -If you are an experienced user of debugging tools, your suggestions -for improvement of @value{GDBN} are welcome in any case. +@code{( @var{group} )+} means that @var{group} inside the parentheses +may repeat one or more times. + +@item +@code{"@var{string}"} means a literal @var{string}. @end itemize -@node Bug Reporting -@section How to report bugs -@cindex bug reports -@cindex @value{GDBN} bugs, reporting +@ignore +@heading Dependencies +@end ignore -A number of companies and individuals offer support for @sc{gnu} products. -If you obtained @value{GDBN} from a support organization, we recommend you -contact that organization first. +@heading Acknowledgments -You can find contact information for many support companies and -individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs -distribution. -@c should add a web page ref... +In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and +Elena Zannoni. -In any event, we also recommend that you submit bug reports for -@value{GDBN}. The prefered method is to submit them directly using -@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web -page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can -be used. +@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:: +@ignore +* GDB/MI Kod Commands:: +* GDB/MI Memory Overlay Commands:: +* GDB/MI Signal Handling Commands:: +@end ignore +* GDB/MI Stack Manipulation:: +* GDB/MI Symbol Query:: +* GDB/MI Target Manipulation:: +* GDB/MI Thread Commands:: +* GDB/MI Tracepoint Commands:: +* GDB/MI Variable Objects:: +@end menu -@strong{Do not send bug reports to @samp{info-gdb}, or to -@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do -not want to receive bug reports. Those that do have arranged to receive -@samp{bug-gdb}. +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Command Syntax +@section @sc{gdb/mi} Command Syntax -The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which -serves as a repeater. The mailing list and the newsgroup carry exactly -the same messages. Often people think of posting bug reports to the -newsgroup instead of mailing them. This appears to work, but it has one -problem which can be crucial: a newsgroup posting often lacks a mail -path back to the sender. Thus, if we need to ask for more information, -we may be unable to reach you. For this reason, it is better to send -bug reports to the mailing list. +@menu +* GDB/MI Input Syntax:: +* GDB/MI Output Syntax:: +* GDB/MI Simple Examples:: +@end menu -The fundamental principle of reporting bugs usefully is this: -@strong{report all the facts}. If you are not sure whether to state a -fact or leave it out, state it! +@node GDB/MI Input Syntax +@subsection @sc{gdb/mi} Input Syntax -Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of the variable you use in an example does not matter. -Well, probably it does not, but one cannot be sure. Perhaps the bug is a -stray memory reference which happens to fetch from the location where that -name is stored in memory; perhaps, if the name were different, the contents -of that location would fool the debugger into doing the right thing despite -the bug. Play it safe and give a specific, complete example. That is the -easiest thing for you to do, and the most helpful. +@cindex input syntax for @sc{gdb/mi} +@cindex @sc{gdb/mi}, input syntax +@table @code +@item @var{command} @expansion{} +@code{@var{cli-command} | @var{mi-command}} -Keep in mind that the purpose of a bug report is to enable us to fix the -bug. It may be that the bug has been reported previously, but neither -you nor we can know that unless your bug report is complete and -self-contained. +@item @var{cli-command} @expansion{} +@code{[ @var{token} ] @var{cli-command} @var{nl}}, where +@var{cli-command} is any existing @value{GDBN} CLI command. -Sometimes people give a few sketchy facts and ask, ``Does this ring a -bell?'' Those bug reports are useless, and we urge everyone to -@emph{refuse to respond to them} except to chide the sender to report -bugs properly. +@item @var{mi-command} @expansion{} +@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* +@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} -To enable us to fix the bug, you should include all these things: +@item @var{token} @expansion{} +"any sequence of digits" -@itemize @bullet -@item -The version of @value{GDBN}. @value{GDBN} announces it if you start -with no arguments; you can also print it at any time using @code{show -version}. +@item @var{option} @expansion{} +@code{"-" @var{parameter} [ " " @var{parameter} ]} -Without this, we will not know whether there is any point in looking for -the bug in the current version of @value{GDBN}. +@item @var{parameter} @expansion{} +@code{@var{non-blank-sequence} | @var{c-string}} -@item -The type of machine you are using, and the operating system name and -version number. +@item @var{operation} @expansion{} +@emph{any of the operations described in this chapter} + +@item @var{non-blank-sequence} @expansion{} +@emph{anything, provided it doesn't contain special characters such as +"-", @var{nl}, """ and of course " "} + +@item @var{c-string} @expansion{} +@code{""" @var{seven-bit-iso-c-string-content} """} + +@item @var{nl} @expansion{} +@code{CR | CR-LF} +@end table +@noindent +Notes: + +@itemize @bullet @item -What compiler (and its version) was used to compile @value{GDBN}---e.g. -``@value{GCC}--2.8.1''. +The CLI commands are still handled by the @sc{mi} interpreter; their +output is described below. @item -What compiler (and its version) was used to compile the program you are -debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP -C Compiler''. For GCC, you can say @code{gcc --version} to get this -information; for other compilers, see the documentation for those -compilers. +The @code{@var{token}}, when present, is passed back when the command +finishes. @item -The command arguments you gave the compiler to compile your example and -observe the bug. For example, did you use @samp{-O}? To guarantee -you will not omit something important, list them all. A copy of the -Makefile (or the output from make) is sufficient. +Some @sc{mi} commands accept optional arguments as part of the parameter +list. Each option is identified by a leading @samp{-} (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 +@samp{--} (this is useful when some parameters begin with a dash). +@end itemize -If we were to try to guess the arguments, we would probably guess wrong -and then we might not encounter the bug. +Pragmatics: +@itemize @bullet @item -A complete input script, and all necessary source files, that will -reproduce the bug. +We want easy access to the existing CLI syntax (for debugging). @item -A description of what behavior you observe that you believe is -incorrect. For example, ``It gets a fatal signal.'' +We want it to be easy to spot a @sc{mi} operation. +@end itemize -Of course, if the bug is that @value{GDBN} gets a fatal signal, then we -will certainly notice it. But if the bug is incorrect output, we might -not notice unless it is glaringly wrong. You might as well not give us -a chance to make a mistake. +@node GDB/MI Output Syntax +@subsection @sc{gdb/mi} Output Syntax -Even if the problem you experience is a fatal signal, you should still -say so explicitly. Suppose something strange is going on, such as, your -copy of @value{GDBN} is out of synch, or you have encountered a bug in -the C library on your system. (This has happened!) Your copy might -crash and ours would not. If you told us to expect a crash, then when -ours fails to crash, we would know that the bug was not happening for -us. If you had not told us to expect a crash, then we would not be able -to draw any conclusion from our observations. +@cindex output syntax of @sc{gdb/mi} +@cindex @sc{gdb/mi}, output syntax +The output from @sc{gdb/mi} consists of zero or more out-of-band records +followed, optionally, by a single result record. This result record +is for the most recent command. The sequence of output records is +terminated by @samp{(@value{GDBP})}. -@item -If you wish to suggest changes to the @value{GDBN} source, send us context -diffs. If you even discuss something in the @value{GDBN} source, refer to -it by context, not by line number. +If an input command was prefixed with a @code{@var{token}} then the +corresponding output for that command will also be prefixed by that same +@var{token}. -The line numbers in our development sources will not match those in your -sources. Your line numbers would convey no useful information to us. +@table @code +@item @var{output} @expansion{} +@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} -@end itemize +@item @var{result-record} @expansion{} +@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} -Here are some things that are not necessary: +@item @var{out-of-band-record} @expansion{} +@code{@var{async-record} | @var{stream-record}} + +@item @var{async-record} @expansion{} +@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} + +@item @var{exec-async-output} @expansion{} +@code{[ @var{token} ] "*" @var{async-output}} + +@item @var{status-async-output} @expansion{} +@code{[ @var{token} ] "+" @var{async-output}} + +@item @var{notify-async-output} @expansion{} +@code{[ @var{token} ] "=" @var{async-output}} + +@item @var{async-output} @expansion{} +@code{@var{async-class} ( "," @var{result} )* @var{nl}} + +@item @var{result-class} @expansion{} +@code{"done" | "running" | "connected" | "error" | "exit"} + +@item @var{async-class} @expansion{} +@code{"stopped" | @var{others}} (where @var{others} will be added +depending on the needs---this is still in development). + +@item @var{result} @expansion{} +@code{ @var{variable} "=" @var{value}} + +@item @var{variable} @expansion{} +@code{ @var{string} } + +@item @var{value} @expansion{} +@code{ @var{const} | @var{tuple} | @var{list} } + +@item @var{const} @expansion{} +@code{@var{c-string}} + +@item @var{tuple} @expansion{} +@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } + +@item @var{list} @expansion{} +@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" +@var{result} ( "," @var{result} )* "]" } + +@item @var{stream-record} @expansion{} +@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} + +@item @var{console-stream-output} @expansion{} +@code{"~" @var{c-string}} + +@item @var{target-stream-output} @expansion{} +@code{"@@" @var{c-string}} + +@item @var{log-stream-output} @expansion{} +@code{"&" @var{c-string}} + +@item @var{nl} @expansion{} +@code{CR | CR-LF} + +@item @var{token} @expansion{} +@emph{any sequence of digits}. +@end table + +@noindent +Notes: @itemize @bullet @item -A description of the envelope of the bug. - -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. +All output sequences end in a single line containing a period. -This is often time consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger -with breakpoints, not by pure deduction from a series of examples. -We recommend that you save your time for something else. +@item +The @code{@var{token}} is from the corresponding request. If an execution +command is interrupted by the @samp{-exec-interrupt} command, the +@var{token} associated with the @samp{*stopped} message is the one of the +original execution command, not the one of the interrupt command. -Of course, if you can find a simpler example to report @emph{instead} -of the original one, that is a convenience for us. Errors in the -output will be easier to spot, running under the debugger will take -less time, and so on. +@item +@cindex status output in @sc{gdb/mi} +@var{status-async-output} contains on-going status information about the +progress of a slow operation. It can be discarded. All status output is +prefixed by @samp{+}. -However, simplification is not vital; if you do not want to do this, -report the bug anyway and send us the entire test case you used. +@item +@cindex async output in @sc{gdb/mi} +@var{exec-async-output} contains asynchronous state change on the target +(stopped, started, disappeared). All async output is prefixed by +@samp{*}. @item -A patch for the bug. +@cindex notify output in @sc{gdb/mi} +@var{notify-async-output} contains supplementary information that the +client should handle (e.g., a new breakpoint information). All notify +output is prefixed by @samp{=}. -A patch for the bug does help us if it is a good one. But do not omit -the necessary information, such as the test case, on the assumption that -a patch is all we need. We might see problems with your patch and decide -to fix the problem another way, or we might not understand it at all. +@item +@cindex console output in @sc{gdb/mi} +@var{console-stream-output} is output that should be displayed as is in the +console. It is the textual response to a CLI command. All the console +output is prefixed by @samp{~}. -Sometimes with a program as complicated as @value{GDBN} it is very hard to -construct an example that will make the program follow a certain path -through the code. If you do not send us the example, we will not be able -to construct one, so we will not be able to verify that the bug is fixed. +@item +@cindex target output in @sc{gdb/mi} +@var{target-stream-output} is the output produced by the target program. +All the target output is prefixed by @samp{@@}. -And if we cannot understand what bug you are trying to fix, or why your -patch should be an improvement, we will not install it. A test case will -help us to understand. +@item +@cindex log output in @sc{gdb/mi} +@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for +instance messages that should be displayed as part of an error log. All +the log output is prefixed by @samp{&}. @item -A guess about what the bug is or what it depends on. +@cindex list output in @sc{gdb/mi} +New @sc{gdb/mi} commands should only output @var{lists} containing +@var{values}. -Such guesses are usually wrong. Even we cannot guess right about such -things without first using the debugger to find the facts. -@end itemize -@c The readline documentation is distributed with the readline code -@c and consists of the two following files: -@c rluser.texinfo -@c inc-hist.texinfo -@c Use -I with makeinfo to point to the appropriate directory, -@c environment var TEXINPUTS with TeX. -@include rluser.texinfo -@include inc-hist.texinfo +@end itemize +@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more +details about the various output records. -@node Formatting Documentation -@appendix Formatting Documentation +@node GDB/MI Simple Examples +@subsection Simple Examples of @sc{gdb/mi} Interaction +@cindex @sc{gdb/mi}, simple examples -@cindex @value{GDBN} reference card -@cindex reference card -The @value{GDBN} 4 release includes an already-formatted reference card, ready -for printing with PostScript or Ghostscript, in the @file{gdb} -subdirectory of the main source directory@footnote{In -@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} -release.}. If you can use PostScript or Ghostscript with your printer, -you can print the reference card immediately with @file{refcard.ps}. +This subsection presents several simple examples of interaction using +the @sc{gdb/mi} interface. In these examples, @samp{->} means that the +following line is passed to @sc{gdb/mi} as input, while @samp{<-} means +the output received from @sc{gdb/mi}. -The release also includes the source for the reference card. You -can format it, using @TeX{}, by typing: +@subsubheading Target Stop +@c Ummm... There is no "-stop" command. This assumes async, no? +Here's an example of stopping the inferior process: @smallexample -make refcard.dvi +-> -stop +<- (@value{GDBP}) @end smallexample -The @value{GDBN} reference card is designed to print in @dfn{landscape} -mode on US ``letter'' size paper; -that is, on a sheet 11 inches wide by 8.5 inches -high. You will need to specify this form of printing as an option to -your @sc{dvi} output program. - -@cindex documentation - -All the documentation for @value{GDBN} comes as part of the machine-readable -distribution. The documentation is written in Texinfo format, which is -a documentation system that uses a single source file to produce both -on-line information and a printed manual. You can use one of the Info -formatting commands to create the on-line version of the documentation -and @TeX{} (or @code{texi2roff}) to typeset the printed version. +@noindent +and later: -@value{GDBN} includes an already formatted copy of the on-line Info -version of this manual in the @file{gdb} subdirectory. The main Info -file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to -subordinate files matching @samp{gdb.info*} in the same directory. If -necessary, you can print out these files, or read them with any editor; -but they are easier to read using the @code{info} subsystem in @sc{gnu} -Emacs or the standalone @code{info} program, available as part of the -@sc{gnu} Texinfo distribution. +@smallexample +<- *stop,reason="stop",address="0x123",source="a.c:123" +<- (@value{GDBP}) +@end smallexample -If you want to format these Info files yourself, you need one of the -Info formatting programs, such as @code{texinfo-format-buffer} or -@code{makeinfo}. +@subsubheading Simple CLI Command -If you have @code{makeinfo} installed, and are in the top level -@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of -version @value{GDBVN}), you can make the Info file by typing: +Here's an example of a simple CLI command being passed through +@sc{gdb/mi} and on to the CLI. @smallexample -cd gdb -make gdb.info +-> print 1+2 +<- &"print 1+2\n" +<- ~"$1 = 3\n" +<- ^done +<- (@value{GDBP}) @end smallexample -If you want to typeset and print copies of this manual, you need @TeX{}, -a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the -Texinfo definitions file. +@subsubheading Command With Side Effects -@TeX{} is a typesetting program; it does not print files directly, but -produces output files called @sc{dvi} files. To print a typeset -document, you need a program to print @sc{dvi} files. If your system -has @TeX{} installed, chances are it has such a program. The precise -command to use depends on your system; @kbd{lpr -d} is common; another -(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may -require a file name without any extension or a @samp{.dvi} extension. +@smallexample +-> -symbol-file xyz.exe +<- *breakpoint,nr="3",address="0x123",source="a.c:123" +<- (@value{GDBP}) +@end smallexample -@TeX{} also requires a macro definitions file called -@file{texinfo.tex}. This file tells @TeX{} how to typeset a document -written in Texinfo format. On its own, @TeX{} cannot either read or -typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB -and is located in the @file{gdb-@var{version-number}/texinfo} -directory. +@subsubheading A Bad Command -If you have @TeX{} and a @sc{dvi} printer program installed, you can -typeset and print this manual. First switch to the the @file{gdb} -subdirectory of the main source directory (for example, to -@file{gdb-@value{GDBVN}/gdb}) and type: +Here's what happens if you pass a non-existent command: @smallexample -make gdb.dvi +-> -rubbish +<- ^error,msg="Undefined MI command: rubbish" +<- (@value{GDBP}) @end smallexample -Then give @file{gdb.dvi} to your @sc{dvi} printing program. +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Compatibility with CLI +@section @sc{gdb/mi} Compatibility with CLI -@node Installing GDB -@appendix Installing @value{GDBN} -@cindex configuring @value{GDBN} -@cindex installation -@cindex configuring @value{GDBN}, and source tree subdirectories +@cindex compatibility, @sc{gdb/mi} and CLI +@cindex @sc{gdb/mi}, compatibility with CLI +To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi} +accepts existing CLI commands. As specified by the syntax, such +commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will +respond. -@value{GDBN} comes with a @code{configure} script that automates the process -of preparing @value{GDBN} for installation; you can then use @code{make} to -build the @code{gdb} program. -@iftex -@c irrelevant in info file; it's as current as the code it lives with. -@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, -look at the @file{README} file in the sources; we may have improved the -installation procedures since publishing this manual.} -@end iftex +This mechanism is provided as an aid to developers of @sc{gdb/mi} +clients and not as a reliable interface into the CLI. Since the command +is being interpreteted in an environment that assumes @sc{gdb/mi} +behaviour, the exact output of such commands is likely to end up being +an un-supported hybrid of @sc{gdb/mi} and CLI output. -The @value{GDBN} distribution includes all the source code you need for -@value{GDBN} in a single directory, whose name is usually composed by -appending the version number to @samp{gdb}. +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Output Records +@section @sc{gdb/mi} Output Records -For example, the @value{GDBN} version @value{GDBVN} distribution is in the -@file{gdb-@value{GDBVN}} directory. That directory contains: +@menu +* GDB/MI Result Records:: +* GDB/MI Stream Records:: +* GDB/MI Out-of-band Records:: +@end menu -@table @code -@item gdb-@value{GDBVN}/configure @r{(and supporting files)} -script for configuring @value{GDBN} and all its supporting libraries +@node GDB/MI Result Records +@subsection @sc{gdb/mi} Result Records -@item gdb-@value{GDBVN}/gdb -the source specific to @value{GDBN} itself +@cindex result records in @sc{gdb/mi} +@cindex @sc{gdb/mi}, result records +In addition to a number of out-of-band notifications, the response to a +@sc{gdb/mi} command includes one of the following result indications: -@item gdb-@value{GDBVN}/bfd -source for the Binary File Descriptor library +@table @code +@findex ^done +@item "^done" [ "," @var{results} ] +The synchronous operation was successful, @code{@var{results}} are the return +values. + +@item "^running" +@findex ^running +@c Is this one correct? Should it be an out-of-band notification? +The asynchronous operation was successfully started. The target is +running. -@item gdb-@value{GDBVN}/include -@sc{gnu} include files +@item "^error" "," @var{c-string} +@findex ^error +The operation failed. The @code{@var{c-string}} contains the corresponding +error message. +@end table -@item gdb-@value{GDBVN}/libiberty -source for the @samp{-liberty} free software library +@node GDB/MI Stream Records +@subsection @sc{gdb/mi} Stream Records -@item gdb-@value{GDBVN}/opcodes -source for the library of opcode tables and disassemblers +@cindex @sc{gdb/mi}, stream records +@cindex stream records in @sc{gdb/mi} +@value{GDBN} internally maintains a number of output streams: the console, the +target, and the log. The output intended for each of these streams is +funneled through the @sc{gdb/mi} interface using @dfn{stream records}. -@item gdb-@value{GDBVN}/readline -source for the @sc{gnu} command-line interface +Each stream record begins with a unique @dfn{prefix character} which +identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output +Syntax}). In addition to the prefix, each stream record contains a +@code{@var{string-output}}. This is either raw text (with an implicit new +line) or a quoted C string (which does not contain an implicit newline). -@item gdb-@value{GDBVN}/glob -source for the @sc{gnu} filename pattern-matching subroutine +@table @code +@item "~" @var{string-output} +The console output stream contains text that should be displayed in the +CLI console window. It contains the textual responses to CLI commands. -@item gdb-@value{GDBVN}/mmalloc -source for the @sc{gnu} memory-mapped malloc package -@end table +@item "@@" @var{string-output} +The target output stream contains any textual output from the running +target. -The simplest way to configure and build @value{GDBN} is to run @code{configure} -from the @file{gdb-@var{version-number}} source directory, which in -this example is the @file{gdb-@value{GDBVN}} directory. +@item "&" @var{string-output} +The log stream contains debugging messages being produced by @value{GDBN}'s +internals. +@end table -First switch to the @file{gdb-@var{version-number}} source directory -if you are not already in it; then run @code{configure}. Pass the -identifier for the platform on which @value{GDBN} will run as an -argument. +@node GDB/MI Out-of-band Records +@subsection @sc{gdb/mi} Out-of-band Records -For example: +@cindex out-of-band records in @sc{gdb/mi} +@cindex @sc{gdb/mi}, out-of-band records +@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of +additional changes that have occurred. Those changes can either be a +consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of +target activity (e.g., target stopped). -@smallexample -cd gdb-@value{GDBVN} -./configure @var{host} -make -@end smallexample +The following is a preliminary list of possible out-of-band records. -@noindent -where @var{host} is an identifier such as @samp{sun4} or -@samp{decstation}, that identifies the platform where @value{GDBN} will run. -(You can often leave off @var{host}; @code{configure} tries to guess the -correct value by examining your system.) +@table @code +@item "*" "stop" +@end table -Running @samp{configure @var{host}} and then running @code{make} builds the -@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty} -libraries, then @code{gdb} itself. The configured source files, and the -binaries, are left in the corresponding source directories. -@need 750 -@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your -system does not recognize this automatically when you run a different -shell, you may need to run @code{sh} on it explicitly: +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Command Description Format +@section @sc{gdb/mi} Command Description Format -@smallexample -sh configure @var{host} -@end smallexample +The remaining sections describe blocks of commands. Each block of +commands is laid out in a fashion similar to this section. -If you run @code{configure} from a directory that contains source -directories for multiple libraries or programs, such as the -@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure} -creates configuration files for every directory level underneath (unless -you tell it not to, with the @samp{--norecursion} option). +Note the the line breaks shown in the examples are here only for +readability. They don't appear in the real output. +Also note that the commands with a non-available example (N.A.@:) are +not yet implemented. -You should run the @code{configure} script from the top directory in the -source tree, the @file{gdb-@var{version-number}} directory. If you run -@code{configure} from one of the subdirectories, you will configure only -that subdirectory. That is usually not what you want. In particular, -if you run the first @code{configure} from the @file{gdb} subdirectory -of the @file{gdb-@var{version-number}} directory, you will omit the -configuration of @file{bfd}, @file{readline}, and other sibling -directories of the @file{gdb} subdirectory. This leads to build errors -about missing include files such as @file{bfd/bfd.h}. +@subheading Motivation -You can install @code{@value{GDBP}} anywhere; it has no hardwired paths. -However, you should make sure that the shell on your path (named by -the @samp{SHELL} environment variable) is publicly readable. Remember -that @value{GDBN} uses the shell to start your program---some systems refuse to -let @value{GDBN} debug child processes whose programs are not readable. +The motivation for this collection of commands. -@menu -* Separate Objdir:: Compiling @value{GDBN} in another directory -* Config Names:: Specifying names for hosts and targets -* Configure Options:: Summary of options for configure -@end menu +@subheading Introduction -@node Separate Objdir -@section Compiling @value{GDBN} in another directory +A brief introduction to this collection of commands as a whole. -If you want to run @value{GDBN} versions for several host or target machines, -you need a different @code{gdb} compiled for each combination of -host and target. @code{configure} is designed to make this easy by -allowing you to generate each configuration in a separate subdirectory, -rather than in the source directory. If your @code{make} program -handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running -@code{make} in each of these directories builds the @code{gdb} -program specified there. +@subheading Commands -To build @code{gdb} in a separate directory, run @code{configure} -with the @samp{--srcdir} option to specify where to find the source. -(You also need to specify a path to find @code{configure} -itself from your working directory. If the path to @code{configure} -would be the same as the argument to @samp{--srcdir}, you can leave out -the @samp{--srcdir} option; it is assumed.) +For each command in the block, the following is described: -For example, with version @value{GDBVN}, you can build @value{GDBN} in a -separate directory for a Sun 4 like this: +@subsubheading Synopsis @smallexample -@group -cd gdb-@value{GDBVN} -mkdir ../gdb-sun4 -cd ../gdb-sun4 -../gdb-@value{GDBVN}/configure sun4 -make -@end group + -command @var{args}@dots{} @end smallexample -When @code{configure} builds a configuration using a remote source -directory, it creates a tree for the binaries with the same structure -(and using the same names) as the tree under the source directory. In -the example, you'd find the Sun 4 library @file{libiberty.a} in the -directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in -@file{gdb-sun4/gdb}. +@subsubheading @value{GDBN} Command -Make sure that your path to the @file{configure} script has just one -instance of @file{gdb} in it. If your path to @file{configure} looks -like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only -one subdirectory of @value{GDBN}, not the whole package. This leads to -build errors about missing include files such as @file{bfd/bfd.h}. +The corresponding @value{GDBN} CLI command. -One popular reason to build several @value{GDBN} configurations in separate -directories is to configure @value{GDBN} for cross-compiling (where -@value{GDBN} runs on one machine---the @dfn{host}---while debugging -programs that run on another machine---the @dfn{target}). -You specify a cross-debugging target by -giving the @samp{--target=@var{target}} option to @code{configure}. +@subsubheading Result -When you run @code{make} to build a program or library, you must run -it in a configured directory---whatever directory you were in when you -called @code{configure} (or one of its subdirectories). +@subsubheading Out-of-band -The @code{Makefile} that @code{configure} generates in each source -directory also runs recursively. If you type @code{make} in a source -directory such as @file{gdb-@value{GDBVN}} (or in a separate configured -directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you -will build all the required libraries, and then build GDB. +@subsubheading Notes -When you have multiple hosts or targets configured in separate -directories, you can run @code{make} on them in parallel (for example, -if they are NFS-mounted on each of the hosts); they will not interfere -with each other. +@subsubheading Example -@node Config Names -@section Specifying names for hosts and targets -The specifications used for hosts and targets in the @code{configure} -script are based on a three-part naming scheme, but some short predefined -aliases are also supported. The full naming scheme encodes three pieces -of information in the following pattern: +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Breakpoint Table Commands +@section @sc{gdb/mi} Breakpoint table commands -@smallexample -@var{architecture}-@var{vendor}-@var{os} -@end smallexample +@cindex breakpoint commands for @sc{gdb/mi} +@cindex @sc{gdb/mi}, breakpoint commands +This section documents @sc{gdb/mi} commands for manipulating +breakpoints. -For example, you can use the alias @code{sun4} as a @var{host} argument, -or as the value for @var{target} in a @code{--target=@var{target}} -option. The equivalent full name is @samp{sparc-sun-sunos4}. +@subheading The @code{-break-after} Command +@findex -break-after -The @code{configure} script accompanying @value{GDBN} does not provide -any query facility to list all supported host and target names or -aliases. @code{configure} calls the Bourne shell script -@code{config.sub} to map abbreviations to full names; you can read the -script, if you wish, or you can use it to test your guesses on -abbreviations---for example: +@subsubheading Synopsis @smallexample -% sh config.sub i386-linux -i386-pc-linux-gnu -% sh config.sub alpha-linux -alpha-unknown-linux-gnu -% sh config.sub hp9k700 -hppa1.1-hp-hpux -% sh config.sub sun4 -sparc-sun-sunos4.1.1 -% sh config.sub sun3 -m68k-sun-sunos4.1.1 -% sh config.sub i986v -Invalid configuration `i986v': machine `i986v' not recognized + -break-after @var{number} @var{count} @end smallexample -@noindent -@code{config.sub} is also distributed in the @value{GDBN} source -directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). +The breakpoint number @var{number} is not in effect until it has been +hit @var{count} times. To see how this is reflected in the output of +the @samp{-break-list} command, see the description of the +@samp{-break-list} command below. -@node Configure Options -@section @code{configure} options +@subsubheading @value{GDBN} Command -Here is a summary of the @code{configure} options and arguments that -are most often useful for building @value{GDBN}. @code{configure} also has -several other options not listed here. @inforef{What Configure -Does,,configure.info}, for a full explanation of @code{configure}. +The corresponding @value{GDBN} command is @samp{ignore}. + +@subsubheading Example @smallexample -configure @r{[}--help@r{]} - @r{[}--prefix=@var{dir}@r{]} - @r{[}--exec-prefix=@var{dir}@r{]} - @r{[}--srcdir=@var{dirname}@r{]} - @r{[}--norecursion@r{]} @r{[}--rm@r{]} - @r{[}--target=@var{target}@r{]} - @var{host} +(@value{GDBP}) +-break-insert main +^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@} +(@value{GDBP}) +-break-after 1 3 +~ +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",line="5",times="0", +ignore="3"@}]@} +(@value{GDBP}) @end smallexample -@noindent -You may introduce options with a single @samp{-} rather than -@samp{--} if you prefer; but you may abbreviate option names if you use -@samp{--}. +@ignore +@subheading The @code{-break-catch} Command +@findex -break-catch -@table @code -@item --help -Display a quick summary of how to invoke @code{configure}. +@subheading The @code{-break-commands} Command +@findex -break-commands +@end ignore -@item --prefix=@var{dir} -Configure the source to install programs and files under directory -@file{@var{dir}}. -@item --exec-prefix=@var{dir} -Configure the source to install programs under directory -@file{@var{dir}}. +@subheading The @code{-break-condition} Command +@findex -break-condition -@c avoid splitting the warning from the explanation: -@need 2000 -@item --srcdir=@var{dirname} -@strong{Warning: using this option requires @sc{gnu} @code{make}, or another -@code{make} that implements the @code{VPATH} feature.}@* -Use this option to make configurations in directories separate from the -@value{GDBN} source directories. Among other things, you can use this to -build (or maintain) several configurations simultaneously, in separate -directories. @code{configure} writes configuration specific files in -the current directory, but arranges for them to use the source in the -directory @var{dirname}. @code{configure} creates directories under -the working directory in parallel to the source directories below -@var{dirname}. +@subsubheading Synopsis -@item --norecursion -Configure only the directory level where @code{configure} is executed; do not -propagate configuration to subdirectories. +@smallexample + -break-condition @var{number} @var{expr} +@end smallexample -@item --target=@var{target} -Configure @value{GDBN} for cross-debugging programs running on the specified -@var{target}. Without this option, @value{GDBN} is configured to debug -programs that run on the same machine (@var{host}) as @value{GDBN} itself. +Breakpoint @var{number} will stop the program only if the condition in +@var{expr} is true. The condition becomes part of the +@samp{-break-list} output (see the description of the @samp{-break-list} +command below). -There is no convenient way to generate a list of all available targets. +@subsubheading @value{GDBN} Command -@item @var{host} @dots{} -Configure @value{GDBN} to run on the specified @var{host}. +The corresponding @value{GDBN} command is @samp{condition}. -There is no convenient way to generate a list of all available hosts. -@end table +@subsubheading Example -There are many other options available as well, but they are generally -needed for special purposes only. +@smallexample +(@value{GDBP}) +-break-condition 1 1 +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",line="5",cond="1", +times="0",ignore="3"@}]@} +(@value{GDBP}) +@end smallexample -@node Maintenance Commands -@appendix Maintenance Commands -@cindex maintenance commands -@cindex internal commands +@subheading The @code{-break-delete} Command +@findex -break-delete -In addition to commands intended for @value{GDBN} users, @value{GDBN} -includes a number of commands intended for @value{GDBN} developers. -These commands are provided here for reference. +@subsubheading Synopsis -@table @code -@kindex maint info breakpoints -@item @anchor{maint info breakpoints}maint info breakpoints -Using the same format as @samp{info breakpoints}, display both the -breakpoints you've set explicitly, and those @value{GDBN} is using for -internal purposes. Internal breakpoints are shown with negative -breakpoint numbers. The type column identifies what kind of breakpoint -is shown: +@smallexample + -break-delete ( @var{breakpoint} )+ +@end smallexample -@table @code -@item breakpoint -Normal, explicitly set breakpoint. +Delete the breakpoint(s) whose number(s) are specified in the argument +list. This is obviously reflected in the breakpoint list. -@item watchpoint -Normal, explicitly set watchpoint. +@subsubheading @value{GDBN} command -@item longjmp -Internal breakpoint, used to handle correctly stepping through -@code{longjmp} calls. +The corresponding @value{GDBN} command is @samp{delete}. -@item longjmp resume -Internal breakpoint at the target of a @code{longjmp}. +@subsubheading Example -@item until -Temporary internal breakpoint used by the @value{GDBN} @code{until} command. +@smallexample +(@value{GDBP}) +-break-delete 1 +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="0",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[]@} +(@value{GDBP}) +@end smallexample -@item finish -Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. +@subheading The @code{-break-disable} Command +@findex -break-disable -@item shlib events -Shared library events. +@subsubheading Synopsis -@end table +@smallexample + -break-disable ( @var{breakpoint} )+ +@end smallexample -@kindex maint internal-error -@kindex maint internal-warning -@item maint internal-error -@itemx maint internal-warning -Cause @value{GDBN} to call the internal function @code{internal_error} -or @code{internal_warning} and hence behave as though an internal error -or internal warning has been detected. In addition to reporting the -internal problem, these functions give the user the opportunity to -either quit @value{GDBN} or create a core file of the current -@value{GDBN} session. +Disable the named @var{breakpoint}(s). The field @samp{enabled} in the +break list is now set to @samp{n} for the named @var{breakpoint}(s). + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{disable}. + +@subsubheading Example @smallexample -(gdb) @kbd{maint internal-error testing, 1, 2} -@dots{}/maint.c:121: internal-error: testing, 1, 2 -A problem internal to GDB has been detected. Further -debugging may prove unreliable. -Quit this debugging session? (y or n) @kbd{n} -Create a core file? (y or n) @kbd{n} -(gdb) +(@value{GDBP}) +-break-disable 2 +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", +addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} +(@value{GDBP}) @end smallexample -Takes an optional parameter that is used as the text of the error or -warning message. +@subheading The @code{-break-enable} Command +@findex -break-enable -@kindex maint print registers -@kindex maint print raw-registers -@kindex maint print cooked-registers -@item maint print registers -@itemx maint print raw-registers -@itemx maint print cooked-registers -Print @value{GDBN}'s internal register data structures. +@subsubheading Synopsis -The command @samp{maint print raw-registers} includes the contents of -the raw register cache; and the command @samp{maint print -cooked-registers} includes the (cooked) value of all registers. -@xref{Registers,, Registers, gdbint, @value{GDBN} Internals}. +@smallexample + -break-enable ( @var{breakpoint} )+ +@end smallexample -Takes an optional file parameter. +Enable (previously disabled) @var{breakpoint}(s). -@kindex maint set profile -@kindex maint show profile -@cindex profiling GDB -@item maint set profile -@itemx maint show profile -Control profiling of @value{GDBN}. +@subsubheading @value{GDBN} Command -Profiling will be disabled until you use the @samp{maint set profile} -command to enable it. When you enable profiling, the system will begin -collecting timing and execution count data; when you disable profiling or -exit @value{GDBN}, the results will be written to a log file. Remember that -if you use profiling, @value{GDBN} will overwrite the profiling log file -(often called @file{gmon.out}). If you have a record of important profiling -data in a @file{gmon.out} file, be sure to move it to a safe location. +The corresponding @value{GDBN} command is @samp{enable}. -Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be -compiled with the @samp{-pg} compiler option. +@subsubheading Example -@end table +@smallexample +(@value{GDBP}) +-break-enable 2 +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} +(@value{GDBP}) +@end smallexample +@subheading The @code{-break-info} Command +@findex -break-info -@node Remote Protocol -@appendix @value{GDBN} Remote Serial Protocol +@subsubheading Synopsis -@menu -* Overview:: -* Packets:: -* Stop Reply Packets:: -* General Query Packets:: -* Register Packet Format:: -* Examples:: -@end menu +@smallexample + -break-info @var{breakpoint} +@end smallexample -@node Overview -@section Overview +@c REDUNDANT??? +Get information about a single breakpoint. -There may be occasions when you need to know something about the -protocol---for example, if there is only one serial port to your target -machine, you might want your program to do something special if it -recognizes a packet meant for @value{GDBN}. +@subsubheading @value{GDBN} command -In the examples below, @samp{->} and @samp{<-} are used to indicate -transmitted and received data respectfully. +The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. -@cindex protocol, @value{GDBN} remote serial -@cindex serial protocol, @value{GDBN} remote -@cindex remote serial protocol -All @value{GDBN} commands and responses (other than acknowledgments) are -sent as a @var{packet}. A @var{packet} is introduced with the character -@samp{$}, the actual @var{packet-data}, and the terminating character -@samp{#} followed by a two-digit @var{checksum}: +@subsubheading Example +N.A. + +@subheading The @code{-break-insert} Command +@findex -break-insert + +@subsubheading Synopsis @smallexample -@code{$}@var{packet-data}@code{#}@var{checksum} + -break-insert [ -t ] [ -h ] [ -r ] + [ -c @var{condition} ] [ -i @var{ignore-count} ] + [ -p @var{thread} ] [ @var{line} | @var{addr} ] @end smallexample -@noindent -@cindex checksum, for @value{GDBN} remote @noindent -The two-digit @var{checksum} is computed as the modulo 256 sum of all -characters between the leading @samp{$} and the trailing @samp{#} (an -eight bit unsigned checksum). +If specified, @var{line}, can be one of: -Implementors should note that prior to @value{GDBN} 5.0 the protocol -specification also included an optional two-digit @var{sequence-id}: +@itemize @bullet +@item function +@c @item +offset +@c @item -offset +@c @item linenum +@item filename:linenum +@item filename:function +@item *address +@end itemize + +The possible optional parameters of this command are: + +@table @samp +@item -t +Insert a tempoary breakpoint. +@item -h +Insert a hardware breakpoint. +@item -c @var{condition} +Make the breakpoint conditional on @var{condition}. +@item -i @var{ignore-count} +Initialize the @var{ignore-count}. +@item -r +Insert a regular breakpoint in all the functions whose names match the +given regular expression. Other flags are not applicable to regular +expresson. +@end table + +@subsubheading Result + +The result is in the form: @smallexample -@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} + ^done,bkptno="@var{number}",func="@var{funcname}", + file="@var{filename}",line="@var{lineno}" @end smallexample -@cindex sequence-id, for @value{GDBN} remote @noindent -That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} -has never output @var{sequence-id}s. Stubs that handle packets added -since @value{GDBN} 5.0 must not accept @var{sequence-id}. +where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname} +is the name of the function where the breakpoint was inserted, +@var{filename} is the name of the source file which contains this +function, and @var{lineno} is the source line number within that file. -@cindex acknowledgment, for @value{GDBN} remote -When either the host or the target machine receives a packet, the first -response expected is an acknowledgment: either @samp{+} (to indicate -the package was received correctly) or @samp{-} (to request -retransmission): +Note: this format is open to change. +@c An out-of-band breakpoint instead of part of the result? + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, +@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}. + +@subsubheading Example @smallexample --> @code{$}@var{packet-data}@code{#}@var{checksum} -<- @code{+} +(@value{GDBP}) +-break-insert main +^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} +(@value{GDBP}) +-break-insert -t foo +^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@} +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@}, +bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", +addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@} +(@value{GDBP}) +-break-insert -r foo.* +~int foo(int, int); +^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@} +(@value{GDBP}) +@end smallexample + +@subheading The @code{-break-list} Command +@findex -break-list + +@subsubheading Synopsis + +@smallexample + -break-list +@end smallexample + +Displays the list of inserted breakpoints, showing the following fields: + +@table @samp +@item Number +number of the breakpoint +@item Type +type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} +@item Disposition +should the breakpoint be deleted or disabled when it is hit: @samp{keep} +or @samp{nokeep} +@item Enabled +is the breakpoint enabled or no: @samp{y} or @samp{n} +@item Address +memory location at which the breakpoint is set +@item What +logical location of the breakpoint, expressed by function name, file +name, line number +@item Times +number of times the breakpoint has been hit +@end table + +If there are no breakpoints or watchpoints, the @code{BreakpointTable} +@code{body} field is an empty list. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info break}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}, +bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", +addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@} +(@value{GDBP}) +@end smallexample + +Here's an example of the result when there are no breakpoints: + +@smallexample +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="0",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[]@} +(@value{GDBP}) +@end smallexample + +@subheading The @code{-break-watch} Command +@findex -break-watch + +@subsubheading Synopsis + +@smallexample + -break-watch [ -a | -r ] +@end smallexample + +Create a watchpoint. With the @samp{-a} option it will create an +@dfn{access} watchpoint, i.e. a watchpoint that triggers either on a +read from or on a write to the memory location. With the @samp{-r} +option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will +trigger only when the memory location is accessed for reading. Without +either of the options, the watchpoint created is a regular watchpoint, +i.e. it will trigger when the memory location is accessed for writing. +@xref{Set Watchpoints, , Setting watchpoints}. + +Note that @samp{-break-list} will report a single list of watchpoints and +breakpoints inserted. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and +@samp{rwatch}. + +@subsubheading Example + +Setting a watchpoint on a variable in the @code{main} function: + +@smallexample +(@value{GDBP}) +-break-watch x +^done,wpt=@{number="2",exp="x"@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, +value=@{old="-268439212",new="55"@}, +frame=@{func="main",args=[],file="recursive2.c",line="5"@} +(@value{GDBP}) +@end smallexample + +Setting a watchpoint on a variable local to a function. @value{GDBN} will stop +the program execution twice: first for the variable changing value, then +for the watchpoint going out of scope. + +@smallexample +(@value{GDBP}) +-break-watch C +^done,wpt=@{number="5",exp="C"@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-trigger", +wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, +frame=@{func="callee4",args=[], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-scope",wpnum="5", +frame=@{func="callee3",args=[@{name="strarg", +value="0x11940 \"A string argument.\""@}], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} +(@value{GDBP}) +@end smallexample + +Listing breakpoints and watchpoints, at different points in the program +execution. Note that once the watchpoint goes out of scope, it is +deleted. + +@smallexample +(@value{GDBP}) +-break-watch C +^done,wpt=@{number="2",exp="C"@} +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, +bkpt=@{number="2",type="watchpoint",disp="keep", +enabled="y",addr="",what="C",times="0"@}]@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, +value=@{old="-276895068",new="3"@}, +frame=@{func="callee4",args=[], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, +bkpt=@{number="2",type="watchpoint",disp="keep", +enabled="y",addr="",what="C",times="-5"@}]@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-scope",wpnum="2", +frame=@{func="callee3",args=[@{name="strarg", +value="0x11940 \"A string argument.\""@}], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@} +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Data Manipulation +@section @sc{gdb/mi} Data Manipulation + +@cindex data manipulation, in @sc{gdb/mi} +@cindex @sc{gdb/mi}, data manipulation +This section describes the @sc{gdb/mi} commands that manipulate data: +examine memory and registers, evaluate expressions, etc. + +@c REMOVED FROM THE INTERFACE. +@c @subheading -data-assign +@c Change the value of a program variable. Plenty of side effects. +@c @subsubheading GDB command +@c set variable +@c @subsubheading Example +@c N.A. + +@subheading The @code{-data-disassemble} Command +@findex -data-disassemble + +@subsubheading Synopsis + +@smallexample + -data-disassemble + [ -s @var{start-addr} -e @var{end-addr} ] + | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ] + -- @var{mode} @end smallexample + @noindent +Where: -The host (@value{GDBN}) sends @var{command}s, and the target (the -debugging stub incorporated in your program) sends a @var{response}. In -the case of step and continue @var{command}s, the response is only sent -when the operation has completed (the target has again stopped). +@table @samp +@item @var{start-addr} +is the beginning address (or @code{$pc}) +@item @var{end-addr} +is the end address +@item @var{filename} +is the name of the file to disassemble +@item @var{linenum} +is the line number to disassemble around +@item @var{lines} +is the the number of disassembly lines to be produced. If it is -1, +the whole function will be disassembled, in case no @var{end-addr} is +specified. If @var{end-addr} is specified as a non-zero value, and +@var{lines} is lower than the number of disassembly lines between +@var{start-addr} and @var{end-addr}, only @var{lines} lines are +displayed; if @var{lines} is higher than the number of lines between +@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} +are displayed. +@item @var{mode} +is either 0 (meaning only disassembly) or 1 (meaning mixed source and +disassembly). +@end table -@var{packet-data} consists of a sequence of characters with the -exception of @samp{#} and @samp{$} (see @samp{X} packet for additional -exceptions). +@subsubheading Result -Fields within the packet should be separated using @samp{,} @samp{;} or -@cindex remote protocol, field separator -@samp{:}. Except where otherwise noted all numbers are represented in -@sc{hex} with leading zeros suppressed. +The output for each instruction is composed of four fields: -Implementors should note that prior to @value{GDBN} 5.0, the character -@samp{:} could not appear as the third character in a packet (as it -would potentially conflict with the @var{sequence-id}). +@itemize @bullet +@item Address +@item Func-name +@item Offset +@item Instruction +@end itemize -Response @var{data} can be run-length encoded to save space. A @samp{*} -means that the next character is an @sc{ascii} encoding giving a repeat count -which stands for that many repetitions of the character preceding the -@samp{*}. The encoding is @code{n+29}, yielding a printable character -where @code{n >=3} (which is where rle starts to win). The printable -characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric -value greater than 126 should not be used. +Note that whatever included in the instruction field, is not manipulated +directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format. + +@subsubheading @value{GDBN} Command + +There's no direct mapping from this command to the CLI. + +@subsubheading Example + +Disassemble from the current value of @code{$pc} to @code{$pc + 20}: + +@smallexample +(@value{GDBP}) +-data-disassemble -s $pc -e "$pc + 20" -- 0 +^done, +asm_insns=[ +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}, +@{address="0x000107c8",func-name="main",offset="12", +inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, +@{address="0x000107cc",func-name="main",offset="16", +inst="sethi %hi(0x11800), %o2"@}, +@{address="0x000107d0",func-name="main",offset="20", +inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] +(@value{GDBP}) +@end smallexample + +Disassemble the whole @code{main} function. Line 32 is part of +@code{main}. + +@smallexample +-data-disassemble -f basics.c -l 32 -- 0 +^done,asm_insns=[ +@{address="0x000107bc",func-name="main",offset="0", +inst="save %sp, -112, %sp"@}, +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}, +[@dots{}] +@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, +@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] +(@value{GDBP}) +@end smallexample + +Disassemble 3 instructions from the start of @code{main}: + +@smallexample +(@value{GDBP}) +-data-disassemble -f basics.c -l 32 -n 3 -- 0 +^done,asm_insns=[ +@{address="0x000107bc",func-name="main",offset="0", +inst="save %sp, -112, %sp"@}, +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}] +(@value{GDBP}) +@end smallexample + +Disassemble 3 instructions from the start of @code{main} in mixed mode: + +@smallexample +(@value{GDBP}) +-data-disassemble -f basics.c -l 32 -n 3 -- 1 +^done,asm_insns=[ +src_and_asm_line=@{line="31", +file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ + testsuite/gdb.mi/basics.c",line_asm_insn=[ +@{address="0x000107bc",func-name="main",offset="0", +inst="save %sp, -112, %sp"@}]@}, +src_and_asm_line=@{line="32", +file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ + testsuite/gdb.mi/basics.c",line_asm_insn=[ +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}]@}] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-data-evaluate-expression} Command +@findex -data-evaluate-expression + +@subsubheading Synopsis + +@smallexample + -data-evaluate-expression @var{expr} +@end smallexample + +Evaluate @var{expr} as an expression. The expression could contain an +inferior function call. The function call will execute synchronously. +If the expression contains spaces, it must be enclosed in double quotes. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and +@samp{call}. In @code{gdbtk} only, there's a corresponding +@samp{gdb_eval} command. + +@subsubheading Example + +In the following example, the numbers that precede the commands are the +@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi} +Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its +output. + +@smallexample +211-data-evaluate-expression A +211^done,value="1" +(@value{GDBP}) +311-data-evaluate-expression &A +311^done,value="0xefffeb7c" +(@value{GDBP}) +411-data-evaluate-expression A+3 +411^done,value="4" +(@value{GDBP}) +511-data-evaluate-expression "A + 3" +511^done,value="4" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-data-list-changed-registers} Command +@findex -data-list-changed-registers + +@subsubheading Synopsis + +@smallexample + -data-list-changed-registers +@end smallexample + +Display a list of the registers that have changed. + +@subsubheading @value{GDBN} Command + +@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} +has the corresponding command @samp{gdb_changed_register_list}. + +@subsubheading Example + +On a PPC MBX board: + +@smallexample +(@value{GDBP}) +-exec-continue +^running + +(@value{GDBP}) +*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main", +args=[],file="try.c",line="5"@} +(@value{GDBP}) +-data-list-changed-registers +^done,changed-registers=["0","1","2","4","5","6","7","8","9", +"10","11","13","14","15","16","17","18","19","20","21","22","23", +"24","25","26","27","28","30","31","64","65","66","67","69"] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-data-list-register-names} Command +@findex -data-list-register-names + +@subsubheading Synopsis + +@smallexample + -data-list-register-names [ ( @var{regno} )+ ] +@end smallexample + +Show a list of register names for the current target. If no arguments +are given, it shows a list of the names of all the registers. If +integer numbers are given as arguments, it will print a list of the +names of the registers corresponding to the arguments. To ensure +consistency between a register name and its number, the output list may +include empty register names. + +@subsubheading @value{GDBN} Command + +@value{GDBN} does not have a command which corresponds to +@samp{-data-list-register-names}. In @code{gdbtk} there is a +corresponding command @samp{gdb_regnames}. + +@subsubheading Example + +For the PPC MBX board: +@smallexample +(@value{GDBP}) +-data-list-register-names +^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", +"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", +"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", +"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", +"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", +"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", +"", "pc","ps","cr","lr","ctr","xer"] +(@value{GDBP}) +-data-list-register-names 1 2 3 +^done,register-names=["r1","r2","r3"] +(@value{GDBP}) +@end smallexample + +@subheading The @code{-data-list-register-values} Command +@findex -data-list-register-values + +@subsubheading Synopsis + +@smallexample + -data-list-register-values @var{fmt} [ ( @var{regno} )*] +@end smallexample + +Display the registers' contents. @var{fmt} is the format according to +which the registers' contents are to be returned, followed by an optional +list of numbers specifying the registers to display. A missing list of +numbers indicates that the contents of all the registers must be returned. + +Allowed formats for @var{fmt} are: + +@table @code +@item x +Hexadecimal +@item o +Octal +@item t +Binary +@item d +Decimal +@item r +Raw +@item N +Natural +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info +all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}. + +@subsubheading Example + +For a PPC MBX board (note: line breaks are for readability only, they +don't appear in the actual output): + +@smallexample +(@value{GDBP}) +-data-list-register-values r 64 65 +^done,register-values=[@{number="64",value="0xfe00a300"@}, +@{number="65",value="0x00029002"@}] +(@value{GDBP}) +-data-list-register-values x +^done,register-values=[@{number="0",value="0xfe0043c8"@}, +@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, +@{number="3",value="0x0"@},@{number="4",value="0xa"@}, +@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, +@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, +@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, +@{number="11",value="0x1"@},@{number="12",value="0x0"@}, +@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, +@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, +@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, +@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, +@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, +@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, +@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, +@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, +@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, +@{number="31",value="0x0"@},@{number="32",value="0x0"@}, +@{number="33",value="0x0"@},@{number="34",value="0x0"@}, +@{number="35",value="0x0"@},@{number="36",value="0x0"@}, +@{number="37",value="0x0"@},@{number="38",value="0x0"@}, +@{number="39",value="0x0"@},@{number="40",value="0x0"@}, +@{number="41",value="0x0"@},@{number="42",value="0x0"@}, +@{number="43",value="0x0"@},@{number="44",value="0x0"@}, +@{number="45",value="0x0"@},@{number="46",value="0x0"@}, +@{number="47",value="0x0"@},@{number="48",value="0x0"@}, +@{number="49",value="0x0"@},@{number="50",value="0x0"@}, +@{number="51",value="0x0"@},@{number="52",value="0x0"@}, +@{number="53",value="0x0"@},@{number="54",value="0x0"@}, +@{number="55",value="0x0"@},@{number="56",value="0x0"@}, +@{number="57",value="0x0"@},@{number="58",value="0x0"@}, +@{number="59",value="0x0"@},@{number="60",value="0x0"@}, +@{number="61",value="0x0"@},@{number="62",value="0x0"@}, +@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, +@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, +@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, +@{number="69",value="0x20002b03"@}] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-data-read-memory} Command +@findex -data-read-memory + +@subsubheading Synopsis + +@smallexample + -data-read-memory [ -o @var{byte-offset} ] + @var{address} @var{word-format} @var{word-size} + @var{nr-rows} @var{nr-cols} [ @var{aschar} ] +@end smallexample + +@noindent +where: + +@table @samp +@item @var{address} +An expression specifying the address of the first memory word to be +read. Complex expressions containing embedded white space should be +quoted using the C convention. + +@item @var{word-format} +The format to be used to print the memory words. The notation is the +same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats, +,Output formats}). + +@item @var{word-size} +The size of each memory word in bytes. + +@item @var{nr-rows} +The number of rows in the output table. + +@item @var{nr-cols} +The number of columns in the output table. + +@item @var{aschar} +If present, indicates that each row should include an @sc{ascii} dump. The +value of @var{aschar} is used as a padding character when a byte is not a +member of the printable @sc{ascii} character set (printable @sc{ascii} +characters are those whose code is between 32 and 126, inclusively). + +@item @var{byte-offset} +An offset to add to the @var{address} before fetching memory. +@end table + +This command displays memory contents as a table of @var{nr-rows} by +@var{nr-cols} words, each word being @var{word-size} bytes. In total, +@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read +(returned as @samp{total-bytes}). Should less than the requested number +of bytes be returned by the target, the missing words are identified +using @samp{N/A}. The number of bytes read from the target is returned +in @samp{nr-bytes} and the starting address used to read memory in +@samp{addr}. + +The address of the next/previous row or page is available in +@samp{next-row} and @samp{prev-row}, @samp{next-page} and +@samp{prev-page}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has +@samp{gdb_get_mem} memory read command. + +@subsubheading Example + +Read six bytes of memory starting at @code{bytes+6} but then offset by +@code{-6} bytes. Format as three rows of two columns. One byte per +word. Display each word in hex. + +@smallexample +(@value{GDBP}) +9-data-read-memory -o -6 -- bytes+6 x 1 3 2 +9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", +next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", +prev-page="0x0000138a",memory=[ +@{addr="0x00001390",data=["0x00","0x01"]@}, +@{addr="0x00001392",data=["0x02","0x03"]@}, +@{addr="0x00001394",data=["0x04","0x05"]@}] +(@value{GDBP}) +@end smallexample + +Read two bytes of memory starting at address @code{shorts + 64} and +display as a single word formatted in decimal. + +@smallexample +(@value{GDBP}) +5-data-read-memory shorts+64 d 2 1 1 +5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", +next-row="0x00001512",prev-row="0x0000150e", +next-page="0x00001512",prev-page="0x0000150e",memory=[ +@{addr="0x00001510",data=["128"]@}] +(@value{GDBP}) +@end smallexample + +Read thirty two bytes of memory starting at @code{bytes+16} and format +as eight rows of four columns. Include a string encoding with @samp{x} +used as the non-printable character. + +@smallexample +(@value{GDBP}) +4-data-read-memory bytes+16 x 1 8 4 x +4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", +next-row="0x000013c0",prev-row="0x0000139c", +next-page="0x000013c0",prev-page="0x00001380",memory=[ +@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, +@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, +@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, +@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, +@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, +@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, +@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, +@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] +(@value{GDBP}) +@end smallexample + +@subheading The @code{-display-delete} Command +@findex -display-delete + +@subsubheading Synopsis + +@smallexample + -display-delete @var{number} +@end smallexample + +Delete the display @var{number}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{delete display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-display-disable} Command +@findex -display-disable + +@subsubheading Synopsis + +@smallexample + -display-disable @var{number} +@end smallexample + +Disable display @var{number}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{disable display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-display-enable} Command +@findex -display-enable + +@subsubheading Synopsis + +@smallexample + -display-enable @var{number} +@end smallexample + +Enable display @var{number}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{enable display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-display-insert} Command +@findex -display-insert + +@subsubheading Synopsis + +@smallexample + -display-insert @var{expression} +@end smallexample + +Display @var{expression} every time the program stops. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-display-list} Command +@findex -display-list + +@subsubheading Synopsis + +@smallexample + -display-list +@end smallexample + +List the displays. Do not show the current values. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-environment-cd} Command +@findex -environment-cd + +@subsubheading Synopsis + +@smallexample + -environment-cd @var{pathdir} +@end smallexample + +Set @value{GDBN}'s working directory. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{cd}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-environment-directory} Command +@findex -environment-directory + +@subsubheading Synopsis + +@smallexample + -environment-directory [ -r ] [ @var{pathdir} ]+ +@end smallexample + +Add directories @var{pathdir} to beginning of search path for source files. +If the @samp{-r} option is used, the search path is reset to the default +search path. If directories @var{pathdir} are supplied in addition to the +@samp{-r} option, the search path is first reset and then addition +occurs as normal. +Multiple directories may be specified, separated by blanks. Specifying +multiple directories in a single command +results in the directories added to the beginning of the +search path in the same order they were presented in the command. +If blanks are needed as +part of a directory name, double-quotes should be used around +the name. In the command output, the path will show up separated +by the system directory-separator character. The directory-seperator +character must not be used +in any directory name. +If no directories are specified, the current search path is displayed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{dir}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb +^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" +(@value{GDBP}) +-environment-directory "" +^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" +(@value{GDBP}) +-environment-directory -r /home/jjohnstn/src/gdb /usr/src +^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" +(@value{GDBP}) +-environment-directory -r +^done,source-path="$cdir:$cwd" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-environment-path} Command +@findex -environment-path + +@subsubheading Synopsis + +@smallexample + -environment-path [ -r ] [ @var{pathdir} ]+ +@end smallexample + +Add directories @var{pathdir} to beginning of search path for object files. +If the @samp{-r} option is used, the search path is reset to the original +search path that existed at gdb start-up. If directories @var{pathdir} are +supplied in addition to the +@samp{-r} option, the search path is first reset and then addition +occurs as normal. +Multiple directories may be specified, separated by blanks. Specifying +multiple directories in a single command +results in the directories added to the beginning of the +search path in the same order they were presented in the command. +If blanks are needed as +part of a directory name, double-quotes should be used around +the name. In the command output, the path will show up separated +by the system directory-separator character. The directory-seperator +character must not be used +in any directory name. +If no directories are specified, the current path is displayed. + + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{path}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-environment-path +^done,path="/usr/bin" +(@value{GDBP}) +-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin +^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" +(@value{GDBP}) +-environment-path -r /usr/local/bin +^done,path="/usr/local/bin:/usr/bin" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-environment-pwd} Command +@findex -environment-pwd + +@subsubheading Synopsis + +@smallexample + -environment-pwd +@end smallexample + +Show the current working directory. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{pwd}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-environment-pwd +^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Program Control +@section @sc{gdb/mi} Program control + +@subsubheading Program termination + +As a result of execution, the inferior program can run to completion, if +it doesn't encounter any breakpoints. In this case the output will +include an exit code, if the program has exited exceptionally. + +@subsubheading Examples + +@noindent +Program exited normally: + +@smallexample +(@value{GDBP}) +-exec-run +^running +(@value{GDBP}) +x = 55 +*stopped,reason="exited-normally" +(@value{GDBP}) +@end smallexample + +@noindent +Program exited exceptionally: + +@smallexample +(@value{GDBP}) +-exec-run +^running +(@value{GDBP}) +x = 55 +*stopped,reason="exited",exit-code="01" +(@value{GDBP}) +@end smallexample + +Another way the program can terminate is if it receives a signal such as +@code{SIGINT}. In this case, @sc{gdb/mi} displays this: + +@smallexample +(@value{GDBP}) +*stopped,reason="exited-signalled",signal-name="SIGINT", +signal-meaning="Interrupt" +@end smallexample + + +@subheading The @code{-exec-abort} Command +@findex -exec-abort + +@subsubheading Synopsis + +@smallexample + -exec-abort +@end smallexample + +Kill the inferior running program. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{kill}. + +@subsubheading Example +N.A. + + +@subheading The @code{-exec-arguments} Command +@findex -exec-arguments + +@subsubheading Synopsis + +@smallexample + -exec-arguments @var{args} +@end smallexample + +Set the inferior program arguments, to be used in the next +@samp{-exec-run}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{set args}. + +@subsubheading Example + +@c FIXME! +Don't have one around. + + +@subheading The @code{-exec-continue} Command +@findex -exec-continue + +@subsubheading Synopsis + +@smallexample + -exec-continue +@end smallexample + +Asynchronous command. Resumes the execution of the inferior program +until a breakpoint is encountered, or until the inferior exits. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} corresponding is @samp{continue}. + +@subsubheading Example + +@smallexample +-exec-continue +^running +(@value{GDBP}) +@@Hello world +*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[], +file="hello.c",line="13"@} +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-finish} Command +@findex -exec-finish + +@subsubheading Synopsis + +@smallexample + -exec-finish +@end smallexample + +Asynchronous command. Resumes the execution of the inferior program +until the current function is exited. Displays the results returned by +the function. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{finish}. + +@subsubheading Example + +Function returning @code{void}. + +@smallexample +-exec-finish +^running +(@value{GDBP}) +@@hello from foo +*stopped,reason="function-finished",frame=@{func="main",args=[], +file="hello.c",line="7"@} +(@value{GDBP}) +@end smallexample + +Function returning other than @code{void}. The name of the internal +@value{GDBN} variable storing the result is printed, together with the +value itself. + +@smallexample +-exec-finish +^running +(@value{GDBP}) +*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", +args=[@{name="a",value="1"],@{name="b",value="9"@}@}, +file="recursive2.c",line="14"@}, +gdb-result-var="$1",return-value="0" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-interrupt} Command +@findex -exec-interrupt + +@subsubheading Synopsis + +@smallexample + -exec-interrupt +@end smallexample + +Asynchronous command. Interrupts the background execution of the target. +Note how the token associated with the stop message is the one for the +execution command that has been interrupted. The token for the interrupt +itself only appears in the @samp{^done} output. If the user is trying to +interrupt a non-running program, an error message will be printed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{interrupt}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +111-exec-continue +111^running + +(@value{GDBP}) +222-exec-interrupt +222^done +(@value{GDBP}) +111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", +frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@} +(@value{GDBP}) + +(@value{GDBP}) +-exec-interrupt +^error,msg="mi_cmd_exec_interrupt: Inferior not executing." +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-next} Command +@findex -exec-next + +@subsubheading Synopsis + +@smallexample + -exec-next +@end smallexample + +Asynchronous command. Resumes execution of the inferior program, stopping +when the beginning of the next source line is reached. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{next}. + +@subsubheading Example + +@smallexample +-exec-next +^running +(@value{GDBP}) +*stopped,reason="end-stepping-range",line="8",file="hello.c" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-next-instruction} Command +@findex -exec-next-instruction + +@subsubheading Synopsis + +@smallexample + -exec-next-instruction +@end smallexample + +Asynchronous command. Executes one machine instruction. If the +instruction is a function call continues until the function returns. If +the program stops at an instruction in the middle of a source line, the +address will be printed as well. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{nexti}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-exec-next-instruction +^running + +(@value{GDBP}) +*stopped,reason="end-stepping-range", +addr="0x000100d4",line="5",file="hello.c" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-return} Command +@findex -exec-return + +@subsubheading Synopsis + +@smallexample + -exec-return +@end smallexample + +Makes current function return immediately. Doesn't execute the inferior. +Displays the new current frame. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{return}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +200-break-insert callee4 +200^done,bkpt=@{number="1",addr="0x00010734", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} +(@value{GDBP}) +000-exec-run +000^running +(@value{GDBP}) +000*stopped,reason="breakpoint-hit",bkptno="1", +frame=@{func="callee4",args=[], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} +(@value{GDBP}) +205-break-delete +205^done +(@value{GDBP}) +111-exec-return +111^done,frame=@{level="0",func="callee3", +args=[@{name="strarg", +value="0x11940 \"A string argument.\""@}], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-run} Command +@findex -exec-run + +@subsubheading Synopsis + +@smallexample + -exec-run +@end smallexample + +Asynchronous command. Starts execution of the inferior from the +beginning. The inferior executes until either a breakpoint is +encountered or the program exits. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{run}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-insert main +^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} +(@value{GDBP}) +-exec-run +^running +(@value{GDBP}) +*stopped,reason="breakpoint-hit",bkptno="1", +frame=@{func="main",args=[],file="recursive2.c",line="4"@} +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-show-arguments} Command +@findex -exec-show-arguments + +@subsubheading Synopsis + +@smallexample + -exec-show-arguments +@end smallexample + +Print the arguments of the program. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{show args}. + +@subsubheading Example +N.A. + +@c @subheading -exec-signal + +@subheading The @code{-exec-step} Command +@findex -exec-step + +@subsubheading Synopsis + +@smallexample + -exec-step +@end smallexample + +Asynchronous command. Resumes execution of the inferior program, stopping +when the beginning of the next source line is reached, if the next +source line is not a function call. If it is, stop at the first +instruction of the called function. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{step}. + +@subsubheading Example + +Stepping into a function: + +@smallexample +-exec-step +^running +(@value{GDBP}) +*stopped,reason="end-stepping-range", +frame=@{func="foo",args=[@{name="a",value="10"@}, +@{name="b",value="0"@}],file="recursive2.c",line="11"@} +(@value{GDBP}) +@end smallexample + +Regular stepping: + +@smallexample +-exec-step +^running +(@value{GDBP}) +*stopped,reason="end-stepping-range",line="14",file="recursive2.c" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-step-instruction} Command +@findex -exec-step-instruction + +@subsubheading Synopsis + +@smallexample + -exec-step-instruction +@end smallexample + +Asynchronous command. Resumes the inferior which executes one machine +instruction. The output, once @value{GDBN} has stopped, will vary depending on +whether we have stopped in the middle of a source line or not. In the +former case, the address at which the program stopped will be printed as +well. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{stepi}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-exec-step-instruction +^running + +(@value{GDBP}) +*stopped,reason="end-stepping-range", +frame=@{func="foo",args=[],file="try.c",line="10"@} +(@value{GDBP}) +-exec-step-instruction +^running + +(@value{GDBP}) +*stopped,reason="end-stepping-range", +frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@} +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-until} Command +@findex -exec-until + +@subsubheading Synopsis + +@smallexample + -exec-until [ @var{location} ] +@end smallexample + +Asynchronous command. Executes the inferior until the @var{location} +specified in the argument is reached. If there is no argument, the inferior +executes until a source line greater than the current one is reached. +The reason for stopping in this case will be @samp{location-reached}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{until}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-exec-until recursive2.c:6 +^running +(@value{GDBP}) +x = 55 +*stopped,reason="location-reached",frame=@{func="main",args=[], +file="recursive2.c",line="6"@} +(@value{GDBP}) +@end smallexample + +@ignore +@subheading -file-clear +Is this going away???? +@end ignore + + +@subheading The @code{-file-exec-and-symbols} Command +@findex -file-exec-and-symbols + +@subsubheading Synopsis + +@smallexample + -file-exec-and-symbols @var{file} +@end smallexample + +Specify the executable file to be debugged. This file is the one from +which the symbol table is also read. If no file is specified, the +command clears the executable and symbol information. If breakpoints +are set when using this command with no arguments, @value{GDBN} will produce +error messages. Otherwise, no output is produced, except a completion +notification. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{file}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-file-exec-file} Command +@findex -file-exec-file + +@subsubheading Synopsis + +@smallexample + -file-exec-file @var{file} +@end smallexample + +Specify the executable file to be debugged. Unlike +@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read +from this file. If used without argument, @value{GDBN} clears the information +about the executable file. No output is produced, except a completion +notification. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{exec-file}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-file-list-exec-sections} Command +@findex -file-list-exec-sections + +@subsubheading Synopsis + +@smallexample + -file-list-exec-sections +@end smallexample + +List the sections of the current executable file. + +@subsubheading @value{GDBN} Command + +The @value{GDBN} command @samp{info file} shows, among the rest, the same +information as this command. @code{gdbtk} has a corresponding command +@samp{gdb_load_info}. + +@subsubheading Example +N.A. + + +@subheading The @code{-file-list-exec-source-file} Command +@findex -file-list-exec-source-file + +@subsubheading Synopsis + +@smallexample + -file-list-exec-source-file +@end smallexample + +List the line number, the current source file, and the absolute path +to the current source file for the current executable. + +@subsubheading @value{GDBN} Command + +There's no @value{GDBN} command which directly corresponds to this one. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +123-file-list-exec-source-file +123^done,line="1",file="foo.c",fullname="/home/bar/foo.c" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-file-list-exec-source-files} Command +@findex -file-list-exec-source-files + +@subsubheading Synopsis + +@smallexample + -file-list-exec-source-files +@end smallexample + +List the source files for the current executable. + +It will always output the filename, but only when GDB can find the absolute +file name of a source file, will it output the fullname. + +@subsubheading @value{GDBN} Command + +There's no @value{GDBN} command which directly corresponds to this one. +@code{gdbtk} has an analogous command @samp{gdb_listfiles}. + +@subsubheading Example +@smallexample +(@value{GDBP}) +-file-list-exec-source-files +^done,files=[ +@{file=foo.c,fullname=/home/foo.c@}, +@{file=/home/bar.c,fullname=/home/bar.c@}, +@{file=gdb_could_not_find_fullpath.c@}] +(@value{GDBP}) +@end smallexample + +@subheading The @code{-file-list-shared-libraries} Command +@findex -file-list-shared-libraries + +@subsubheading Synopsis + +@smallexample + -file-list-shared-libraries +@end smallexample + +List the shared libraries in the program. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info shared}. + +@subsubheading Example +N.A. + + +@subheading The @code{-file-list-symbol-files} Command +@findex -file-list-symbol-files + +@subsubheading Synopsis + +@smallexample + -file-list-symbol-files +@end smallexample + +List symbol files. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info file} (part of it). + +@subsubheading Example +N.A. + + +@subheading The @code{-file-symbol-file} Command +@findex -file-symbol-file + +@subsubheading Synopsis + +@smallexample + -file-symbol-file @var{file} +@end smallexample + +Read symbol table info from the specified @var{file} argument. When +used without arguments, clears @value{GDBN}'s symbol table info. No output is +produced, except for a completion notification. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{symbol-file}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx +^done +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Miscellaneous Commands +@section Miscellaneous @value{GDBN} commands in @sc{gdb/mi} + +@c @subheading -gdb-complete + +@subheading The @code{-gdb-exit} Command +@findex -gdb-exit + +@subsubheading Synopsis + +@smallexample + -gdb-exit +@end smallexample + +Exit @value{GDBN} immediately. + +@subsubheading @value{GDBN} Command + +Approximately corresponds to @samp{quit}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-gdb-exit +@end smallexample + +@subheading The @code{-gdb-set} Command +@findex -gdb-set + +@subsubheading Synopsis + +@smallexample + -gdb-set +@end smallexample + +Set an internal @value{GDBN} variable. +@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{set}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-gdb-set $foo=3 +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-gdb-show} Command +@findex -gdb-show + +@subsubheading Synopsis + +@smallexample + -gdb-show +@end smallexample + +Show the current value of a @value{GDBN} variable. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{show}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-gdb-show annotate +^done,value="0" +(@value{GDBP}) +@end smallexample + +@c @subheading -gdb-source + + +@subheading The @code{-gdb-version} Command +@findex -gdb-version + +@subsubheading Synopsis + +@smallexample + -gdb-version +@end smallexample + +Show version information for @value{GDBN}. Used mostly in testing. + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this +information when you start an interactive session. + +@subsubheading Example + +@c This example modifies the actual output from GDB to avoid overfull +@c box in TeX. +@smallexample +(@value{GDBP}) +-gdb-version +~GNU gdb 5.2.1 +~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 + "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". +^done +(@value{GDBP}) +@end smallexample + +@subheading The @code{-interpreter-exec} Command +@findex -interpreter-exec + +@subheading Synopsis + +@smallexample +-interpreter-exec @var{interpreter} @var{command} +@end smallexample + +Execute the specified @var{command} in the given @var{interpreter}. + +@subheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{interpreter-exec}. + +@subheading Example + +@smallexample +(@value{GDBP}) +-interpreter-exec console "break main" +&"During symbol reading, couldn't parse type; debugger out of date?.\n" +&"During symbol reading, bad structure-type format.\n" +~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" +^done +(@value{GDBP}) +@end smallexample + +@ignore +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Kod Commands +@section @sc{gdb/mi} Kod Commands + +The Kod commands are not implemented. + +@c @subheading -kod-info + +@c @subheading -kod-list + +@c @subheading -kod-list-object-types + +@c @subheading -kod-show + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Memory Overlay Commands +@section @sc{gdb/mi} Memory Overlay Commands + +The memory overlay commands are not implemented. + +@c @subheading -overlay-auto + +@c @subheading -overlay-list-mapping-state + +@c @subheading -overlay-list-overlays + +@c @subheading -overlay-map + +@c @subheading -overlay-off + +@c @subheading -overlay-on + +@c @subheading -overlay-unmap + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Signal Handling Commands +@section @sc{gdb/mi} Signal Handling Commands + +Signal handling commands are not implemented. + +@c @subheading -signal-handle + +@c @subheading -signal-list-handle-actions + +@c @subheading -signal-list-signal-types +@end ignore + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Stack Manipulation +@section @sc{gdb/mi} Stack Manipulation Commands + + +@subheading The @code{-stack-info-frame} Command +@findex -stack-info-frame + +@subsubheading Synopsis + +@smallexample + -stack-info-frame +@end smallexample + +Get info on the current frame. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} +(without arguments). + +@subsubheading Example +N.A. + +@subheading The @code{-stack-info-depth} Command +@findex -stack-info-depth + +@subsubheading Synopsis + +@smallexample + -stack-info-depth [ @var{max-depth} ] +@end smallexample + +Return the depth of the stack. If the integer argument @var{max-depth} +is specified, do not count beyond @var{max-depth} frames. + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. + +@subsubheading Example + +For a stack with frame levels 0 through 11: + +@smallexample +(@value{GDBP}) +-stack-info-depth +^done,depth="12" +(@value{GDBP}) +-stack-info-depth 4 +^done,depth="4" +(@value{GDBP}) +-stack-info-depth 12 +^done,depth="12" +(@value{GDBP}) +-stack-info-depth 11 +^done,depth="11" +(@value{GDBP}) +-stack-info-depth 13 +^done,depth="12" +(@value{GDBP}) +@end smallexample + +@subheading The @code{-stack-list-arguments} Command +@findex -stack-list-arguments + +@subsubheading Synopsis + +@smallexample + -stack-list-arguments @var{show-values} + [ @var{low-frame} @var{high-frame} ] +@end smallexample + +Display a list of the arguments for the frames between @var{low-frame} +and @var{high-frame} (inclusive). If @var{low-frame} and +@var{high-frame} are not provided, list the arguments for the whole call +stack. + +The @var{show-values} argument must have a value of 0 or 1. A value of +0 means that only the names of the arguments are listed, a value of 1 +means that both names and values of the arguments are printed. + +@subsubheading @value{GDBN} Command + +@value{GDBN} does not have an equivalent command. @code{gdbtk} has a +@samp{gdb_get_args} command which partially overlaps with the +functionality of @samp{-stack-list-arguments}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-stack-list-frames +^done, +stack=[ +frame=@{level="0",addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}, +frame=@{level="1",addr="0x0001076c",func="callee3", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}, +frame=@{level="2",addr="0x0001078c",func="callee2", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@}, +frame=@{level="3",addr="0x000107b4",func="callee1", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@}, +frame=@{level="4",addr="0x000107e0",func="main", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}] +(@value{GDBP}) +-stack-list-arguments 0 +^done, +stack-args=[ +frame=@{level="0",args=[]@}, +frame=@{level="1",args=[name="strarg"]@}, +frame=@{level="2",args=[name="intarg",name="strarg"]@}, +frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, +frame=@{level="4",args=[]@}] +(@value{GDBP}) +-stack-list-arguments 1 +^done, +stack-args=[ +frame=@{level="0",args=[]@}, +frame=@{level="1", + args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, +frame=@{level="2",args=[ +@{name="intarg",value="2"@}, +@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, +@{frame=@{level="3",args=[ +@{name="intarg",value="2"@}, +@{name="strarg",value="0x11940 \"A string argument.\""@}, +@{name="fltarg",value="3.5"@}]@}, +frame=@{level="4",args=[]@}] +(@value{GDBP}) +-stack-list-arguments 0 2 2 +^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] +(@value{GDBP}) +-stack-list-arguments 1 2 2 +^done,stack-args=[frame=@{level="2", +args=[@{name="intarg",value="2"@}, +@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] +(@value{GDBP}) +@end smallexample + +@c @subheading -stack-list-exception-handlers + + +@subheading The @code{-stack-list-frames} Command +@findex -stack-list-frames + +@subsubheading Synopsis + +@smallexample + -stack-list-frames [ @var{low-frame} @var{high-frame} ] +@end smallexample + +List the frames currently on the stack. For each frame it displays the +following info: + +@table @samp +@item @var{level} +The frame number, 0 being the topmost frame, i.e. the innermost function. +@item @var{addr} +The @code{$pc} value for that frame. +@item @var{func} +Function name. +@item @var{file} +File name of the source file where the function lives. +@item @var{line} +Line number corresponding to the @code{$pc}. +@end table + +If invoked without arguments, this command prints a backtrace for the +whole stack. If given two integer arguments, it shows the frames whose +levels are between the two arguments (inclusive). If the two arguments +are equal, it shows the single frame at the corresponding level. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. + +@subsubheading Example + +Full stack backtrace: + +@smallexample +(@value{GDBP}) +-stack-list-frames +^done,stack= +[frame=@{level="0",addr="0x0001076c",func="foo", + file="recursive2.c",line="11"@}, +frame=@{level="1",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="2",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="3",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="4",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="5",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="6",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="7",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="8",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="9",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="10",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="11",addr="0x00010738",func="main", + file="recursive2.c",line="4"@}] +(@value{GDBP}) +@end smallexample + +Show frames between @var{low_frame} and @var{high_frame}: + +@smallexample +(@value{GDBP}) +-stack-list-frames 3 5 +^done,stack= +[frame=@{level="3",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="4",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="5",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}] +(@value{GDBP}) +@end smallexample + +Show a single frame: + +@smallexample +(@value{GDBP}) +-stack-list-frames 3 3 +^done,stack= +[frame=@{level="3",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-stack-list-locals} Command +@findex -stack-list-locals + +@subsubheading Synopsis + +@smallexample + -stack-list-locals @var{print-values} +@end smallexample + +Display the local variable names for the current frame. With an +argument of 0 or @code{--no-values}, prints only the names of the variables. +With argument of 1 or @code{--all-values}, prints also their values. With +argument of 2 or @code{--simple-values}, prints the name, type and value for +simple data types and the name and type for arrays, structures and +unions. In this last case, the idea is that the user can see the +value of simple data types immediately and he can create variable +objects for other data types if he wishes to explore their values in +more detail. + +@subsubheading @value{GDBN} Command + +@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-stack-list-locals 0 +^done,locals=[name="A",name="B",name="C"] +(@value{GDBP}) +-stack-list-locals --all-values +^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, + @{name="C",value="@{1, 2, 3@}"@}] +-stack-list-locals --simple-values +^done,locals=[@{name="A",type="int",value="1"@}, + @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-stack-select-frame} Command +@findex -stack-select-frame + +@subsubheading Synopsis + +@smallexample + -stack-select-frame @var{framenum} +@end smallexample + +Change the current frame. Select a different frame @var{framenum} on +the stack. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, +@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-stack-select-frame 2 +^done +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Symbol Query +@section @sc{gdb/mi} Symbol Query Commands + + +@subheading The @code{-symbol-info-address} Command +@findex -symbol-info-address + +@subsubheading Synopsis + +@smallexample + -symbol-info-address @var{symbol} +@end smallexample + +Describe where @var{symbol} is stored. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info address}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-info-file} Command +@findex -symbol-info-file + +@subsubheading Synopsis + +@smallexample + -symbol-info-file +@end smallexample + +Show the file for the symbol. + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. @code{gdbtk} has +@samp{gdb_find_file}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-info-function} Command +@findex -symbol-info-function + +@subsubheading Synopsis + +@smallexample + -symbol-info-function +@end smallexample + +Show which function the symbol lives in. + +@subsubheading @value{GDBN} Command + +@samp{gdb_get_function} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-info-line} Command +@findex -symbol-info-line + +@subsubheading Synopsis + +@smallexample + -symbol-info-line +@end smallexample + +Show the core addresses of the code for a source line. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info line}. +@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-info-symbol} Command +@findex -symbol-info-symbol + +@subsubheading Synopsis + +@smallexample + -symbol-info-symbol @var{addr} +@end smallexample + +Describe what symbol is at location @var{addr}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info symbol}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-list-functions} Command +@findex -symbol-list-functions + +@subsubheading Synopsis + +@smallexample + -symbol-list-functions +@end smallexample + +List the functions in the executable. + +@subsubheading @value{GDBN} Command + +@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and +@samp{gdb_search} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-list-lines} Command +@findex -symbol-list-lines + +@subsubheading Synopsis + +@smallexample + -symbol-list-lines @var{filename} +@end smallexample + +Print the list of lines that contain code and their associated program +addresses for the given source filename. The entries are sorted in +ascending PC order. + +@subsubheading @value{GDBN} Command + +There is no corresponding @value{GDBN} command. + +@subsubheading Example +@smallexample +(@value{GDBP}) +-symbol-list-lines basics.c +^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-symbol-list-types} Command +@findex -symbol-list-types + +@subsubheading Synopsis + +@smallexample + -symbol-list-types +@end smallexample + +List all the type names. + +@subsubheading @value{GDBN} Command + +The corresponding commands are @samp{info types} in @value{GDBN}, +@samp{gdb_search} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-list-variables} Command +@findex -symbol-list-variables + +@subsubheading Synopsis + +@smallexample + -symbol-list-variables +@end smallexample + +List all the global and static variable names. + +@subsubheading @value{GDBN} Command + +@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-locate} Command +@findex -symbol-locate + +@subsubheading Synopsis + +@smallexample + -symbol-locate +@end smallexample + +@subsubheading @value{GDBN} Command + +@samp{gdb_loc} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-type} Command +@findex -symbol-type + +@subsubheading Synopsis + +@smallexample + -symbol-type @var{variable} +@end smallexample + +Show type of @var{variable}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has +@samp{gdb_obj_variable}. + +@subsubheading Example +N.A. + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Target Manipulation +@section @sc{gdb/mi} Target Manipulation Commands + + +@subheading The @code{-target-attach} Command +@findex -target-attach + +@subsubheading Synopsis + +@smallexample + -target-attach @var{pid} | @var{file} +@end smallexample + +Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{attach}. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-compare-sections} Command +@findex -target-compare-sections + +@subsubheading Synopsis + +@smallexample + -target-compare-sections [ @var{section} ] +@end smallexample + +Compare data of section @var{section} on target to the exec file. +Without the argument, all sections are compared. + +@subsubheading @value{GDBN} Command + +The @value{GDBN} equivalent is @samp{compare-sections}. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-detach} Command +@findex -target-detach + +@subsubheading Synopsis + +@smallexample + -target-detach +@end smallexample + +Disconnect from the remote target. There's no output. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{detach}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-target-detach +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-target-disconnect} Command +@findex -target-disconnect + +@subsubheading Synopsis + +@example + -target-disconnect +@end example + +Disconnect from the remote target. There's no output. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{disconnect}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-target-disconnect +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-target-download} Command +@findex -target-download + +@subsubheading Synopsis + +@smallexample + -target-download +@end smallexample + +Loads the executable onto the remote target. +It prints out an update message every half second, which includes the fields: + +@table @samp +@item section +The name of the section. +@item section-sent +The size of what has been sent so far for that section. +@item section-size +The size of the section. +@item total-sent +The total size of what was sent so far (the current and the previous sections). +@item total-size +The size of the overall executable to download. +@end table + +@noindent +Each message is sent as status record (@pxref{GDB/MI Output Syntax, , +@sc{gdb/mi} Output Syntax}). + +In addition, it prints the name and size of the sections, as they are +downloaded. These messages include the following fields: + +@table @samp +@item section +The name of the section. +@item section-size +The size of the section. +@item total-size +The size of the overall executable to download. +@end table + +@noindent +At the end, a summary is printed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{load}. + +@subsubheading Example + +Note: each status message appears on a single line. Here the messages +have been broken down so that they can fit onto a page. + +@smallexample +(@value{GDBP}) +-target-download ++download,@{section=".text",section-size="6668",total-size="9880"@} ++download,@{section=".text",section-sent="512",section-size="6668", +total-sent="512",total-size="9880"@} ++download,@{section=".text",section-sent="1024",section-size="6668", +total-sent="1024",total-size="9880"@} ++download,@{section=".text",section-sent="1536",section-size="6668", +total-sent="1536",total-size="9880"@} ++download,@{section=".text",section-sent="2048",section-size="6668", +total-sent="2048",total-size="9880"@} ++download,@{section=".text",section-sent="2560",section-size="6668", +total-sent="2560",total-size="9880"@} ++download,@{section=".text",section-sent="3072",section-size="6668", +total-sent="3072",total-size="9880"@} ++download,@{section=".text",section-sent="3584",section-size="6668", +total-sent="3584",total-size="9880"@} ++download,@{section=".text",section-sent="4096",section-size="6668", +total-sent="4096",total-size="9880"@} ++download,@{section=".text",section-sent="4608",section-size="6668", +total-sent="4608",total-size="9880"@} ++download,@{section=".text",section-sent="5120",section-size="6668", +total-sent="5120",total-size="9880"@} ++download,@{section=".text",section-sent="5632",section-size="6668", +total-sent="5632",total-size="9880"@} ++download,@{section=".text",section-sent="6144",section-size="6668", +total-sent="6144",total-size="9880"@} ++download,@{section=".text",section-sent="6656",section-size="6668", +total-sent="6656",total-size="9880"@} ++download,@{section=".init",section-size="28",total-size="9880"@} ++download,@{section=".fini",section-size="28",total-size="9880"@} ++download,@{section=".data",section-size="3156",total-size="9880"@} ++download,@{section=".data",section-sent="512",section-size="3156", +total-sent="7236",total-size="9880"@} ++download,@{section=".data",section-sent="1024",section-size="3156", +total-sent="7748",total-size="9880"@} ++download,@{section=".data",section-sent="1536",section-size="3156", +total-sent="8260",total-size="9880"@} ++download,@{section=".data",section-sent="2048",section-size="3156", +total-sent="8772",total-size="9880"@} ++download,@{section=".data",section-sent="2560",section-size="3156", +total-sent="9284",total-size="9880"@} ++download,@{section=".data",section-sent="3072",section-size="3156", +total-sent="9796",total-size="9880"@} +^done,address="0x10004",load-size="9880",transfer-rate="6586", +write-rate="429" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-target-exec-status} Command +@findex -target-exec-status + +@subsubheading Synopsis + +@smallexample + -target-exec-status +@end smallexample + +Provide information on the state of the target (whether it is running or +not, for instance). + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-list-available-targets} Command +@findex -target-list-available-targets + +@subsubheading Synopsis + +@smallexample + -target-list-available-targets +@end smallexample + +List the possible targets to connect to. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{help target}. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-list-current-targets} Command +@findex -target-list-current-targets + +@subsubheading Synopsis + +@smallexample + -target-list-current-targets +@end smallexample + +Describe the current target. + +@subsubheading @value{GDBN} Command + +The corresponding information is printed by @samp{info file} (among +other things). + +@subsubheading Example +N.A. + + +@subheading The @code{-target-list-parameters} Command +@findex -target-list-parameters + +@subsubheading Synopsis + +@smallexample + -target-list-parameters +@end smallexample + +@c ???? + +@subsubheading @value{GDBN} Command + +No equivalent. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-select} Command +@findex -target-select + +@subsubheading Synopsis + +@smallexample + -target-select @var{type} @var{parameters @dots{}} +@end smallexample + +Connect @value{GDBN} to the remote target. This command takes two args: + +@table @samp +@item @var{type} +The type of target, for instance @samp{async}, @samp{remote}, etc. +@item @var{parameters} +Device names, host names and the like. @xref{Target Commands, , +Commands for managing targets}, for more details. +@end table + +The output is a connection notification, followed by the address at +which the target program is, in the following form: + +@smallexample +^connected,addr="@var{address}",func="@var{function name}", + args=[@var{arg list}] +@end smallexample + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{target}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-target-select async /dev/ttya +^connected,addr="0xfe00a300",func="??",args=[] +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Thread Commands +@section @sc{gdb/mi} Thread Commands + + +@subheading The @code{-thread-info} Command +@findex -thread-info + +@subsubheading Synopsis + +@smallexample + -thread-info +@end smallexample + +@subsubheading @value{GDBN} command + +No equivalent. + +@subsubheading Example +N.A. + + +@subheading The @code{-thread-list-all-threads} Command +@findex -thread-list-all-threads + +@subsubheading Synopsis + +@smallexample + -thread-list-all-threads +@end smallexample + +@subsubheading @value{GDBN} Command + +The equivalent @value{GDBN} command is @samp{info threads}. + +@subsubheading Example +N.A. + + +@subheading The @code{-thread-list-ids} Command +@findex -thread-list-ids + +@subsubheading Synopsis + +@smallexample + -thread-list-ids +@end smallexample + +Produces a list of the currently known @value{GDBN} thread ids. At the +end of the list it also prints the total number of such threads. + +@subsubheading @value{GDBN} Command + +Part of @samp{info threads} supplies the same information. + +@subsubheading Example + +No threads present, besides the main process: + +@smallexample +(@value{GDBP}) +-thread-list-ids +^done,thread-ids=@{@},number-of-threads="0" +(@value{GDBP}) +@end smallexample + + +Several threads: + +@smallexample +(@value{GDBP}) +-thread-list-ids +^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, +number-of-threads="3" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-thread-select} Command +@findex -thread-select + +@subsubheading Synopsis + +@smallexample + -thread-select @var{threadnum} +@end smallexample + +Make @var{threadnum} the current thread. It prints the number of the new +current thread, and the topmost frame for that thread. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{thread}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-exec-next +^running +(@value{GDBP}) +*stopped,reason="end-stepping-range",thread-id="2",line="187", +file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" +(@value{GDBP}) +-thread-list-ids +^done, +thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, +number-of-threads="3" +(@value{GDBP}) +-thread-select 3 +^done,new-thread-id="3", +frame=@{level="0",func="vprintf", +args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, +@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@} +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Tracepoint Commands +@section @sc{gdb/mi} Tracepoint Commands + +The tracepoint commands are not yet implemented. + +@c @subheading -trace-actions + +@c @subheading -trace-delete + +@c @subheading -trace-disable + +@c @subheading -trace-dump + +@c @subheading -trace-enable + +@c @subheading -trace-exists + +@c @subheading -trace-find + +@c @subheading -trace-frame-number + +@c @subheading -trace-info + +@c @subheading -trace-insert + +@c @subheading -trace-list + +@c @subheading -trace-pass-count + +@c @subheading -trace-save + +@c @subheading -trace-start + +@c @subheading -trace-stop + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Variable Objects +@section @sc{gdb/mi} Variable Objects + + +@subheading Motivation for Variable Objects in @sc{gdb/mi} + +For the implementation of a variable debugger window (locals, watched +expressions, etc.), we are proposing the adaptation of the existing code +used by @code{Insight}. + +The two main reasons for that are: + +@enumerate 1 +@item +It has been proven in practice (it is already on its second generation). + +@item +It will shorten development time (needless to say how important it is +now). +@end enumerate + +The original interface was designed to be used by Tcl code, so it was +slightly changed so it could be used through @sc{gdb/mi}. This section +describes the @sc{gdb/mi} operations that will be available and gives some +hints about their use. + +@emph{Note}: In addition to the set of operations described here, we +expect the @sc{gui} implementation of a variable window to require, at +least, the following operations: + +@itemize @bullet +@item @code{-gdb-show} @code{output-radix} +@item @code{-stack-list-arguments} +@item @code{-stack-list-locals} +@item @code{-stack-select-frame} +@end itemize + +@subheading Introduction to Variable Objects in @sc{gdb/mi} + +@cindex variable objects in @sc{gdb/mi} +The basic idea behind variable objects is the creation of a named object +to represent a variable, an expression, a memory location or even a CPU +register. For each object created, a set of operations is available for +examining or changing its properties. + +Furthermore, complex data types, such as C structures, are represented +in a tree format. For instance, the @code{struct} type variable is the +root and the children will represent the struct members. If a child +is itself of a complex type, it will also have children of its own. +Appropriate language differences are handled for C, C@t{++} and Java. + +When returning the actual values of the objects, this facility allows +for the individual selection of the display format used in the result +creation. It can be chosen among: binary, decimal, hexadecimal, octal +and natural. Natural refers to a default format automatically +chosen based on the variable type (like decimal for an @code{int}, hex +for pointers, etc.). + +The following is the complete set of @sc{gdb/mi} operations defined to +access this functionality: + +@multitable @columnfractions .4 .6 +@item @strong{Operation} +@tab @strong{Description} + +@item @code{-var-create} +@tab create a variable object +@item @code{-var-delete} +@tab delete the variable object and its children +@item @code{-var-set-format} +@tab set the display format of this variable +@item @code{-var-show-format} +@tab show the display format of this variable +@item @code{-var-info-num-children} +@tab tells how many children this object has +@item @code{-var-list-children} +@tab return a list of the object's children +@item @code{-var-info-type} +@tab show the type of this variable object +@item @code{-var-info-expression} +@tab print what this variable object represents +@item @code{-var-show-attributes} +@tab is this variable editable? does it exist here? +@item @code{-var-evaluate-expression} +@tab get the value of this variable +@item @code{-var-assign} +@tab set the value of this variable +@item @code{-var-update} +@tab update the variable and its children +@end multitable + +In the next subsection we describe each operation in detail and suggest +how it can be used. + +@subheading Description And Use of Operations on Variable Objects + +@subheading The @code{-var-create} Command +@findex -var-create + +@subsubheading Synopsis + +@smallexample + -var-create @{@var{name} | "-"@} + @{@var{frame-addr} | "*"@} @var{expression} +@end smallexample + +This operation creates a variable object, which allows the monitoring of +a variable, the result of an expression, a memory cell or a CPU +register. + +The @var{name} parameter is the string by which the object can be +referenced. It must be unique. If @samp{-} is specified, the varobj +system will generate a string ``varNNNNNN'' automatically. It will be +unique provided that one does not specify @var{name} on that format. +The command fails if a duplicate name is found. + +The frame under which the expression should be evaluated can be +specified by @var{frame-addr}. A @samp{*} indicates that the current +frame should be used. + +@var{expression} is any expression valid on the current language set (must not +begin with a @samp{*}), or one of the following: + +@itemize @bullet +@item +@samp{*@var{addr}}, where @var{addr} is the address of a memory cell + +@item +@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) + +@item +@samp{$@var{regname}} --- a CPU register name +@end itemize + +@subsubheading Result + +This operation returns the name, number of children and the type of the +object created. Type is returned as a string as the ones generated by +the @value{GDBN} CLI: + +@smallexample + name="@var{name}",numchild="N",type="@var{type}" +@end smallexample + + +@subheading The @code{-var-delete} Command +@findex -var-delete + +@subsubheading Synopsis + +@smallexample + -var-delete @var{name} +@end smallexample + +Deletes a previously created variable object and all of its children. + +Returns an error if the object @var{name} is not found. + + +@subheading The @code{-var-set-format} Command +@findex -var-set-format + +@subsubheading Synopsis + +@smallexample + -var-set-format @var{name} @var{format-spec} +@end smallexample + +Sets the output format for the value of the object @var{name} to be +@var{format-spec}. + +The syntax for the @var{format-spec} is as follows: + +@smallexample + @var{format-spec} @expansion{} + @{binary | decimal | hexadecimal | octal | natural@} +@end smallexample + + +@subheading The @code{-var-show-format} Command +@findex -var-show-format + +@subsubheading Synopsis + +@smallexample + -var-show-format @var{name} +@end smallexample + +Returns the format used to display the value of the object @var{name}. + +@smallexample + @var{format} @expansion{} + @var{format-spec} +@end smallexample + + +@subheading The @code{-var-info-num-children} Command +@findex -var-info-num-children + +@subsubheading Synopsis + +@smallexample + -var-info-num-children @var{name} +@end smallexample + +Returns the number of children of a variable object @var{name}: + +@smallexample + numchild=@var{n} +@end smallexample + + +@subheading The @code{-var-list-children} Command +@findex -var-list-children + +@subsubheading Synopsis + +@smallexample + -var-list-children [@var{print-values}] @var{name} +@end smallexample + +Returns a list of the children of the specified variable object. With +just the variable object name as an argument or with an optional +preceding argument of 0 or @code{--no-values}, prints only the names of the +variables. With an optional preceding argument of 1 or @code{--all-values}, +also prints their values. + +@subsubheading Example + +@smallexample +(@value{GDBP}) + -var-list-children n + numchild=@var{n},children=[@{name=@var{name}, + numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] +(@value{GDBP}) + -var-list-children --all-values n + numchild=@var{n},children=[@{name=@var{name}, + numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}] +@end smallexample + + +@subheading The @code{-var-info-type} Command +@findex -var-info-type + +@subsubheading Synopsis + +@smallexample + -var-info-type @var{name} +@end smallexample + +Returns the type of the specified variable @var{name}. The type is +returned as a string in the same format as it is output by the +@value{GDBN} CLI: + +@smallexample + type=@var{typename} +@end smallexample + + +@subheading The @code{-var-info-expression} Command +@findex -var-info-expression + +@subsubheading Synopsis + +@smallexample + -var-info-expression @var{name} +@end smallexample + +Returns what is represented by the variable object @var{name}: + +@smallexample + lang=@var{lang-spec},exp=@var{expression} +@end smallexample + +@noindent +where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}. + +@subheading The @code{-var-show-attributes} Command +@findex -var-show-attributes + +@subsubheading Synopsis + +@smallexample + -var-show-attributes @var{name} +@end smallexample + +List attributes of the specified variable object @var{name}: + +@smallexample + status=@var{attr} [ ( ,@var{attr} )* ] +@end smallexample + +@noindent +where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. + +@subheading The @code{-var-evaluate-expression} Command +@findex -var-evaluate-expression + +@subsubheading Synopsis + +@smallexample + -var-evaluate-expression @var{name} +@end smallexample + +Evaluates the expression that is represented by the specified variable +object and returns its value as a string in the current format specified +for the object: + +@smallexample + value=@var{value} +@end smallexample + +Note that one must invoke @code{-var-list-children} for a variable +before the value of a child variable can be evaluated. + +@subheading The @code{-var-assign} Command +@findex -var-assign + +@subsubheading Synopsis + +@smallexample + -var-assign @var{name} @var{expression} +@end smallexample + +Assigns the value of @var{expression} to the variable object specified +by @var{name}. The object must be @samp{editable}. If the variable's +value is altered by the assign, the variable will show up in any +subsequent @code{-var-update} list. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-var-assign var1 3 +^done,value="3" +(@value{GDBP}) +-var-update * +^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] +(@value{GDBP}) +@end smallexample + +@subheading The @code{-var-update} Command +@findex -var-update + +@subsubheading Synopsis + +@smallexample + -var-update @{@var{name} | "*"@} +@end smallexample + +Update the value of the variable object @var{name} by evaluating its +expression after fetching all the new values from memory or registers. +A @samp{*} causes all existing variable objects to be updated. + + +@node Annotations +@chapter @value{GDBN} Annotations + +This chapter describes annotations in @value{GDBN}. Annotations were +designed to interface @value{GDBN} to graphical user interfaces or other +similar programs which want to interact with @value{GDBN} at a +relatively high level. + +The annotation mechanism has largely been superseeded by @sc{gdb/mi} +(@pxref{GDB/MI}). + +@ignore +This is Edition @value{EDITION}, @value{DATE}. +@end ignore + +@menu +* Annotations Overview:: What annotations are; the general syntax. +* Server Prefix:: Issuing a command without affecting user state. +* Prompting:: Annotations marking @value{GDBN}'s need for input. +* Errors:: Annotations for error messages. +* 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. +@end menu + +@node Annotations Overview +@section What is an Annotation? +@cindex annotations + +Annotations start with a newline character, two @samp{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 @samp{control-z} +characters denotes literal output from @value{GDBN}. Currently there is +no need for @value{GDBN} to output a newline followed by two +@samp{control-z} characters, but if there was such a need, the +annotations could be extended with an @samp{escape} annotation which +means those three characters as output. + +The annotation @var{level}, which is specified using the +@option{--annotate} command line option (@pxref{Mode Options}), controls +how much information @value{GDBN} prints together with its prompt, +values of expressions, source lines, and other types of output. Level 0 +is for no anntations, level 1 is for use when @value{GDBN} is run as a +subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable +for programs that control @value{GDBN}, and level 2 annotations have +been made obsolete (@pxref{Limitations, , Limitations of the Annotation +Interface, annotate, GDB's Obsolete Annotations}). This chapter +describes level 3 annotations. + +A simple example of starting up @value{GDBN} with annotations is: + +@smallexample +$ @kbd{gdb --annotate=3} +GNU gdb 6.0 +Copyright 2003 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 "i386-pc-linux-gnu" + +^Z^Zpre-prompt +(gdb) +^Z^Zprompt +@kbd{quit} + +^Z^Zpost-prompt +$ +@end smallexample + +Here @samp{quit} is input to @value{GDBN}; the rest is output from +@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} +denotes a @samp{control-z} character) are annotations; the rest is +output from @value{GDBN}. + +@node Server Prefix +@section The Server Prefix +@cindex server prefix for annotations + +To issue a command to @value{GDBN} without affecting certain aspects of +the state which is seen by users, prefix it with @samp{server }. This +means that this command will not affect the command history, nor will it +affect @value{GDBN}'s notion of which command to repeat if @key{RET} 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 @code{output} command instead of the @code{print} command. + +@node Prompting +@section Annotation for @value{GDBN} Input + +@cindex annotations for prompts +When @value{GDBN} 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 @dfn{input type}. Each +input type has three annotations: a @code{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 @code{post-} +annotation which denotes the end of any echo which may (or may not) be +associated with the input. For example, the @code{prompt} input type +features the following annotations: + +@smallexample +^Z^Zpre-prompt +^Z^Zprompt +^Z^Zpost-prompt +@end smallexample + +The input types are + +@table @code +@findex pre-prompt +@findex prompt +@findex post-prompt +@item prompt +When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). + +@findex pre-commands +@findex commands +@findex post-commands +@item commands +When @value{GDBN} prompts for a set of commands, like in the @code{commands} +command. The annotations are repeated for each command which is input. + +@findex pre-overload-choice +@findex overload-choice +@findex post-overload-choice +@item overload-choice +When @value{GDBN} wants the user to select between various overloaded functions. + +@findex pre-query +@findex query +@findex post-query +@item query +When @value{GDBN} wants the user to confirm a potentially dangerous operation. + +@findex pre-prompt-for-continue +@findex prompt-for-continue +@findex post-prompt-for-continue +@item prompt-for-continue +When @value{GDBN} is asking the user to press return to continue. Note: Don't +expect this to work well; instead use @code{set height 0} to disable +prompting. This is because the counting of lines is buggy in the +presence of annotations. +@end table + +@node Errors +@section Errors +@cindex annotations for errors, warnings and interrupts + +@findex quit +@smallexample +^Z^Zquit +@end smallexample + +This annotation occurs right before @value{GDBN} responds to an interrupt. + +@findex error +@smallexample +^Z^Zerror +@end smallexample + +This annotation occurs right before @value{GDBN} responds to an error. + +Quit and error annotations indicate that any annotations which @value{GDBN} was +in the middle of may end abruptly. For example, if a +@code{value-history-begin} annotation is followed by a @code{error}, one +cannot expect to receive the matching @code{value-history-end}. One +cannot expect not to receive it either, however; an error annotation +does not necessarily mean that @value{GDBN} is immediately returning all the way +to the top level. + +@findex error-begin +A quit or error annotation may be preceded by + +@smallexample +^Z^Zerror-begin +@end smallexample + +Any output between that and the quit or error annotation is the error +message. + +Warning messages are not yet annotated. +@c If we want to change that, need to fix warning(), type_error(), +@c range_error(), and possibly other places. + +@node Invalidation +@section Invalidation Notices + +@cindex annotations for invalidation messages +The following annotations say that certain pieces of state may have +changed. + +@table @code +@findex frames-invalid +@item ^Z^Zframes-invalid + +The frames (for example, output from the @code{backtrace} command) may +have changed. + +@findex breakpoints-invalid +@item ^Z^Zbreakpoints-invalid + +The breakpoints may have changed. For example, the user just added or +deleted a breakpoint. +@end table + +@node Annotations for Running +@section Running the Program +@cindex annotations for running programs + +@findex starting +@findex stopping +When the program starts executing due to a @value{GDBN} command such as +@code{step} or @code{continue}, + +@smallexample +^Z^Zstarting +@end smallexample + +is output. When the program stops, + +@smallexample +^Z^Zstopped +@end smallexample + +is output. Before the @code{stopped} annotation, a variety of +annotations describe how the program stopped. + +@table @code +@findex exited +@item ^Z^Zexited @var{exit-status} +The program exited, and @var{exit-status} is the exit status (zero for +successful exit, otherwise nonzero). + +@findex signalled +@findex signal-name +@findex signal-name-end +@findex signal-string +@findex signal-string-end +@item ^Z^Zsignalled +The program exited with a signal. After the @code{^Z^Zsignalled}, the +annotation continues: + +@smallexample +@var{intro-text} +^Z^Zsignal-name +@var{name} +^Z^Zsignal-name-end +@var{middle-text} +^Z^Zsignal-string +@var{string} +^Z^Zsignal-string-end +@var{end-text} +@end smallexample + +@noindent +where @var{name} is the name of the signal, such as @code{SIGILL} or +@code{SIGSEGV}, and @var{string} is the explanation of the signal, such +as @code{Illegal Instruction} or @code{Segmentation fault}. +@var{intro-text}, @var{middle-text}, and @var{end-text} are for the +user's benefit and have no particular format. + +@findex signal +@item ^Z^Zsignal +The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is +just saying that the program received the signal, not that it was +terminated with it. + +@findex breakpoint +@item ^Z^Zbreakpoint @var{number} +The program hit breakpoint number @var{number}. + +@findex watchpoint +@item ^Z^Zwatchpoint @var{number} +The program hit watchpoint number @var{number}. +@end table + +@node Source Annotations +@section Displaying Source +@cindex annotations for source display + +@findex source +The following annotation is used instead of displaying source code: + +@smallexample +^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} +@end smallexample + +where @var{filename} is an absolute file name indicating which source +file, @var{line} is the line number within that file (where 1 is the +first line in the file), @var{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), +@var{middle} is @samp{middle} if @var{addr} is in the middle of the +line, or @samp{beg} if @var{addr} is at the beginning of the line, and +@var{addr} is the address in the target program associated with the +source which is being displayed. @var{addr} is in the form @samp{0x} +followed by one or more lowercase hex digits (note that this does not +depend on the language). + +@node GDB Bugs +@chapter Reporting Bugs in @value{GDBN} +@cindex bugs in @value{GDBN} +@cindex reporting bugs in @value{GDBN} + +Your bug reports play an essential role in making @value{GDBN} reliable. + +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of @value{GDBN} work better. Bug +reports are your contribution to the maintenance of @value{GDBN}. + +In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +@menu +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs +@end menu + +@node Bug Criteria +@section Have you found a bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@cindex fatal signal +@cindex debugger crash +@cindex crash of debugger +@item +If the debugger gets a fatal signal, for any input whatever, that is a +@value{GDBN} bug. Reliable debuggers never crash. + +@cindex error on valid input +@item +If @value{GDBN} produces an error message for valid input, that is a +bug. (Note that if you're cross debugging, the problem may also be +somewhere in the connection to the target.) + +@cindex invalid input +@item +If @value{GDBN} does not produce an error message for invalid input, +that is a bug. However, you should note that your idea of +``invalid input'' might be our idea of ``an extension'' or ``support +for traditional practice''. + +@item +If you are an experienced user of debugging tools, your suggestions +for improvement of @value{GDBN} are welcome in any case. +@end itemize + +@node Bug Reporting +@section How to report bugs +@cindex bug reports +@cindex @value{GDBN} bugs, reporting + +A number of companies and individuals offer support for @sc{gnu} products. +If you obtained @value{GDBN} from a support organization, we recommend you +contact that organization first. + +You can find contact information for many support companies and +individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs +distribution. +@c should add a web page ref... + +In any event, we also recommend that you submit bug reports for +@value{GDBN}. The prefered method is to submit them directly using +@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web +page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can +be used. + +@strong{Do not send bug reports to @samp{info-gdb}, or to +@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do +not want to receive bug reports. Those that do have arranged to receive +@samp{bug-gdb}. + +The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which +serves as a repeater. The mailing list and the newsgroup carry exactly +the same messages. Often people think of posting bug reports to the +newsgroup instead of mailing them. This appears to work, but it has one +problem which can be crucial: a newsgroup posting often lacks a mail +path back to the sender. Thus, if we need to ask for more information, +we may be unable to reach you. For this reason, it is better to send +bug reports to the mailing list. + +The fundamental principle of reporting bugs usefully is this: +@strong{report all the facts}. If you are not sure whether to state a +fact or leave it out, state it! + +Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of the variable you use in an example does not matter. +Well, probably it does not, but one cannot be sure. Perhaps the bug is a +stray memory reference which happens to fetch from the location where that +name is stored in memory; perhaps, if the name were different, the contents +of that location would fool the debugger into doing the right thing despite +the bug. Play it safe and give a specific, complete example. That is the +easiest thing for you to do, and the most helpful. + +Keep in mind that the purpose of a bug report is to enable us to fix the +bug. It may be that the bug has been reported previously, but neither +you nor we can know that unless your bug report is complete and +self-contained. + +Sometimes people give a few sketchy facts and ask, ``Does this ring a +bell?'' Those bug reports are useless, and we urge everyone to +@emph{refuse to respond to them} except to chide the sender to report +bugs properly. + +To enable us to fix the bug, you should include all these things: + +@itemize @bullet +@item +The version of @value{GDBN}. @value{GDBN} announces it if you start +with no arguments; you can also print it at any time using @code{show +version}. + +Without this, we will not know whether there is any point in looking for +the bug in the current version of @value{GDBN}. + +@item +The type of machine you are using, and the operating system name and +version number. + +@item +What compiler (and its version) was used to compile @value{GDBN}---e.g. +``@value{GCC}--2.8.1''. + +@item +What compiler (and its version) was used to compile the program you are +debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP +C Compiler''. For GCC, you can say @code{gcc --version} to get this +information; for other compilers, see the documentation for those +compilers. + +@item +The command arguments you gave the compiler to compile your example and +observe the bug. For example, did you use @samp{-O}? To guarantee +you will not omit something important, list them all. A copy of the +Makefile (or the output from make) is sufficient. + +If we were to try to guess the arguments, we would probably guess wrong +and then we might not encounter the bug. + +@item +A complete input script, and all necessary source files, that will +reproduce the bug. + +@item +A description of what behavior you observe that you believe is +incorrect. For example, ``It gets a fatal signal.'' + +Of course, if the bug is that @value{GDBN} gets a fatal signal, then we +will certainly notice it. But if the bug is incorrect output, we might +not notice unless it is glaringly wrong. You might as well not give us +a chance to make a mistake. + +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of @value{GDBN} is out of synch, or you have encountered a bug in +the C library on your system. (This has happened!) Your copy might +crash and ours would not. If you told us to expect a crash, then when +ours fails to crash, we would know that the bug was not happening for +us. If you had not told us to expect a crash, then we would not be able +to draw any conclusion from our observations. + +@item +If you wish to suggest changes to the @value{GDBN} source, send us context +diffs. If you even discuss something in the @value{GDBN} source, refer to +it by context, not by line number. + +The line numbers in our development sources will not match those in your +sources. Your line numbers would convey no useful information to us. + +@end itemize + +Here are some things that are not necessary: + +@itemize @bullet +@item +A description of the envelope of the bug. + +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. + +This is often time consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger +with breakpoints, not by pure deduction from a series of examples. +We recommend that you save your time for something else. + +Of course, if you can find a simpler example to report @emph{instead} +of the original one, that is a convenience for us. Errors in the +output will be easier to spot, running under the debugger will take +less time, and so on. + +However, simplification is not vital; if you do not want to do this, +report the bug anyway and send us the entire test case you used. + +@item +A patch for the bug. + +A patch for the bug does help us if it is a good one. But do not omit +the necessary information, such as the test case, on the assumption that +a patch is all we need. We might see problems with your patch and decide +to fix the problem another way, or we might not understand it at all. + +Sometimes with a program as complicated as @value{GDBN} it is very hard to +construct an example that will make the program follow a certain path +through the code. If you do not send us the example, we will not be able +to construct one, so we will not be able to verify that the bug is fixed. + +And if we cannot understand what bug you are trying to fix, or why your +patch should be an improvement, we will not install it. A test case will +help us to understand. + +@item +A guess about what the bug is or what it depends on. + +Such guesses are usually wrong. Even we cannot guess right about such +things without first using the debugger to find the facts. +@end itemize + +@c The readline documentation is distributed with the readline code +@c and consists of the two following files: +@c rluser.texinfo +@c inc-hist.texinfo +@c Use -I with makeinfo to point to the appropriate directory, +@c environment var TEXINPUTS with TeX. +@include rluser.texinfo +@include inc-hist.texinfo + + +@node Formatting Documentation +@appendix Formatting Documentation + +@cindex @value{GDBN} reference card +@cindex reference card +The @value{GDBN} 4 release includes an already-formatted reference card, ready +for printing with PostScript or Ghostscript, in the @file{gdb} +subdirectory of the main source directory@footnote{In +@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} +release.}. If you can use PostScript or Ghostscript with your printer, +you can print the reference card immediately with @file{refcard.ps}. + +The release also includes the source for the reference card. You +can format it, using @TeX{}, by typing: + +@smallexample +make refcard.dvi +@end smallexample + +The @value{GDBN} reference card is designed to print in @dfn{landscape} +mode on US ``letter'' size paper; +that is, on a sheet 11 inches wide by 8.5 inches +high. You will need to specify this form of printing as an option to +your @sc{dvi} output program. + +@cindex documentation + +All the documentation for @value{GDBN} comes as part of the machine-readable +distribution. The documentation is written in Texinfo format, which is +a documentation system that uses a single source file to produce both +on-line information and a printed manual. You can use one of the Info +formatting commands to create the on-line version of the documentation +and @TeX{} (or @code{texi2roff}) to typeset the printed version. + +@value{GDBN} includes an already formatted copy of the on-line Info +version of this manual in the @file{gdb} subdirectory. The main Info +file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to +subordinate files matching @samp{gdb.info*} in the same directory. If +necessary, you can print out these files, or read them with any editor; +but they are easier to read using the @code{info} subsystem in @sc{gnu} +Emacs or the standalone @code{info} program, available as part of the +@sc{gnu} Texinfo distribution. + +If you want to format these Info files yourself, you need one of the +Info formatting programs, such as @code{texinfo-format-buffer} or +@code{makeinfo}. + +If you have @code{makeinfo} installed, and are in the top level +@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of +version @value{GDBVN}), you can make the Info file by typing: + +@smallexample +cd gdb +make gdb.info +@end smallexample + +If you want to typeset and print copies of this manual, you need @TeX{}, +a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the +Texinfo definitions file. + +@TeX{} is a typesetting program; it does not print files directly, but +produces output files called @sc{dvi} files. To print a typeset +document, you need a program to print @sc{dvi} files. If your system +has @TeX{} installed, chances are it has such a program. The precise +command to use depends on your system; @kbd{lpr -d} is common; another +(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may +require a file name without any extension or a @samp{.dvi} extension. + +@TeX{} also requires a macro definitions file called +@file{texinfo.tex}. This file tells @TeX{} how to typeset a document +written in Texinfo format. On its own, @TeX{} cannot either read or +typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB +and is located in the @file{gdb-@var{version-number}/texinfo} +directory. + +If you have @TeX{} and a @sc{dvi} printer program installed, you can +typeset and print this manual. First switch to the the @file{gdb} +subdirectory of the main source directory (for example, to +@file{gdb-@value{GDBVN}/gdb}) and type: + +@smallexample +make gdb.dvi +@end smallexample + +Then give @file{gdb.dvi} to your @sc{dvi} printing program. + +@node Installing GDB +@appendix Installing @value{GDBN} +@cindex configuring @value{GDBN} +@cindex installation +@cindex configuring @value{GDBN}, and source tree subdirectories + +@value{GDBN} comes with a @code{configure} script that automates the process +of preparing @value{GDBN} for installation; you can then use @code{make} to +build the @code{gdb} program. +@iftex +@c irrelevant in info file; it's as current as the code it lives with. +@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, +look at the @file{README} file in the sources; we may have improved the +installation procedures since publishing this manual.} +@end iftex + +The @value{GDBN} distribution includes all the source code you need for +@value{GDBN} in a single directory, whose name is usually composed by +appending the version number to @samp{gdb}. + +For example, the @value{GDBN} version @value{GDBVN} distribution is in the +@file{gdb-@value{GDBVN}} directory. That directory contains: + +@table @code +@item gdb-@value{GDBVN}/configure @r{(and supporting files)} +script for configuring @value{GDBN} and all its supporting libraries + +@item gdb-@value{GDBVN}/gdb +the source specific to @value{GDBN} itself + +@item gdb-@value{GDBVN}/bfd +source for the Binary File Descriptor library + +@item gdb-@value{GDBVN}/include +@sc{gnu} include files + +@item gdb-@value{GDBVN}/libiberty +source for the @samp{-liberty} free software library + +@item gdb-@value{GDBVN}/opcodes +source for the library of opcode tables and disassemblers + +@item gdb-@value{GDBVN}/readline +source for the @sc{gnu} command-line interface + +@item gdb-@value{GDBVN}/glob +source for the @sc{gnu} filename pattern-matching subroutine + +@item gdb-@value{GDBVN}/mmalloc +source for the @sc{gnu} memory-mapped malloc package +@end table + +The simplest way to configure and build @value{GDBN} is to run @code{configure} +from the @file{gdb-@var{version-number}} source directory, which in +this example is the @file{gdb-@value{GDBVN}} directory. + +First switch to the @file{gdb-@var{version-number}} source directory +if you are not already in it; then run @code{configure}. Pass the +identifier for the platform on which @value{GDBN} will run as an +argument. + +For example: + +@smallexample +cd gdb-@value{GDBVN} +./configure @var{host} +make +@end smallexample + +@noindent +where @var{host} is an identifier such as @samp{sun4} or +@samp{decstation}, that identifies the platform where @value{GDBN} will run. +(You can often leave off @var{host}; @code{configure} tries to guess the +correct value by examining your system.) + +Running @samp{configure @var{host}} and then running @code{make} builds the +@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty} +libraries, then @code{gdb} itself. The configured source files, and the +binaries, are left in the corresponding source directories. + +@need 750 +@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your +system does not recognize this automatically when you run a different +shell, you may need to run @code{sh} on it explicitly: + +@smallexample +sh configure @var{host} +@end smallexample + +If you run @code{configure} from a directory that contains source +directories for multiple libraries or programs, such as the +@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure} +creates configuration files for every directory level underneath (unless +you tell it not to, with the @samp{--norecursion} option). + +You should run the @code{configure} script from the top directory in the +source tree, the @file{gdb-@var{version-number}} directory. If you run +@code{configure} from one of the subdirectories, you will configure only +that subdirectory. That is usually not what you want. In particular, +if you run the first @code{configure} from the @file{gdb} subdirectory +of the @file{gdb-@var{version-number}} directory, you will omit the +configuration of @file{bfd}, @file{readline}, and other sibling +directories of the @file{gdb} subdirectory. This leads to build errors +about missing include files such as @file{bfd/bfd.h}. + +You can install @code{@value{GDBP}} anywhere; it has no hardwired paths. +However, you should make sure that the shell on your path (named by +the @samp{SHELL} environment variable) is publicly readable. Remember +that @value{GDBN} uses the shell to start your program---some systems refuse to +let @value{GDBN} debug child processes whose programs are not readable. + +@menu +* Separate Objdir:: Compiling @value{GDBN} in another directory +* Config Names:: Specifying names for hosts and targets +* Configure Options:: Summary of options for configure +@end menu + +@node Separate Objdir +@section Compiling @value{GDBN} in another directory + +If you want to run @value{GDBN} versions for several host or target machines, +you need a different @code{gdb} compiled for each combination of +host and target. @code{configure} is designed to make this easy by +allowing you to generate each configuration in a separate subdirectory, +rather than in the source directory. If your @code{make} program +handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running +@code{make} in each of these directories builds the @code{gdb} +program specified there. + +To build @code{gdb} in a separate directory, run @code{configure} +with the @samp{--srcdir} option to specify where to find the source. +(You also need to specify a path to find @code{configure} +itself from your working directory. If the path to @code{configure} +would be the same as the argument to @samp{--srcdir}, you can leave out +the @samp{--srcdir} option; it is assumed.) + +For example, with version @value{GDBVN}, you can build @value{GDBN} in a +separate directory for a Sun 4 like this: + +@smallexample +@group +cd gdb-@value{GDBVN} +mkdir ../gdb-sun4 +cd ../gdb-sun4 +../gdb-@value{GDBVN}/configure sun4 +make +@end group +@end smallexample + +When @code{configure} builds a configuration using a remote source +directory, it creates a tree for the binaries with the same structure +(and using the same names) as the tree under the source directory. In +the example, you'd find the Sun 4 library @file{libiberty.a} in the +directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in +@file{gdb-sun4/gdb}. + +Make sure that your path to the @file{configure} script has just one +instance of @file{gdb} in it. If your path to @file{configure} looks +like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only +one subdirectory of @value{GDBN}, not the whole package. This leads to +build errors about missing include files such as @file{bfd/bfd.h}. + +One popular reason to build several @value{GDBN} configurations in separate +directories is to configure @value{GDBN} for cross-compiling (where +@value{GDBN} runs on one machine---the @dfn{host}---while debugging +programs that run on another machine---the @dfn{target}). +You specify a cross-debugging target by +giving the @samp{--target=@var{target}} option to @code{configure}. + +When you run @code{make} to build a program or library, you must run +it in a configured directory---whatever directory you were in when you +called @code{configure} (or one of its subdirectories). + +The @code{Makefile} that @code{configure} generates in each source +directory also runs recursively. If you type @code{make} in a source +directory such as @file{gdb-@value{GDBVN}} (or in a separate configured +directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you +will build all the required libraries, and then build GDB. + +When you have multiple hosts or targets configured in separate +directories, you can run @code{make} on them in parallel (for example, +if they are NFS-mounted on each of the hosts); they will not interfere +with each other. + +@node Config Names +@section Specifying names for hosts and targets + +The specifications used for hosts and targets in the @code{configure} +script are based on a three-part naming scheme, but some short predefined +aliases are also supported. The full naming scheme encodes three pieces +of information in the following pattern: + +@smallexample +@var{architecture}-@var{vendor}-@var{os} +@end smallexample + +For example, you can use the alias @code{sun4} as a @var{host} argument, +or as the value for @var{target} in a @code{--target=@var{target}} +option. The equivalent full name is @samp{sparc-sun-sunos4}. + +The @code{configure} script accompanying @value{GDBN} does not provide +any query facility to list all supported host and target names or +aliases. @code{configure} calls the Bourne shell script +@code{config.sub} to map abbreviations to full names; you can read the +script, if you wish, or you can use it to test your guesses on +abbreviations---for example: + +@smallexample +% sh config.sub i386-linux +i386-pc-linux-gnu +% sh config.sub alpha-linux +alpha-unknown-linux-gnu +% sh config.sub hp9k700 +hppa1.1-hp-hpux +% sh config.sub sun4 +sparc-sun-sunos4.1.1 +% sh config.sub sun3 +m68k-sun-sunos4.1.1 +% sh config.sub i986v +Invalid configuration `i986v': machine `i986v' not recognized +@end smallexample + +@noindent +@code{config.sub} is also distributed in the @value{GDBN} source +directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). + +@node Configure Options +@section @code{configure} options + +Here is a summary of the @code{configure} options and arguments that +are most often useful for building @value{GDBN}. @code{configure} also has +several other options not listed here. @inforef{What Configure +Does,,configure.info}, for a full explanation of @code{configure}. + +@smallexample +configure @r{[}--help@r{]} + @r{[}--prefix=@var{dir}@r{]} + @r{[}--exec-prefix=@var{dir}@r{]} + @r{[}--srcdir=@var{dirname}@r{]} + @r{[}--norecursion@r{]} @r{[}--rm@r{]} + @r{[}--target=@var{target}@r{]} + @var{host} +@end smallexample + +@noindent +You may introduce options with a single @samp{-} rather than +@samp{--} if you prefer; but you may abbreviate option names if you use +@samp{--}. + +@table @code +@item --help +Display a quick summary of how to invoke @code{configure}. + +@item --prefix=@var{dir} +Configure the source to install programs and files under directory +@file{@var{dir}}. + +@item --exec-prefix=@var{dir} +Configure the source to install programs under directory +@file{@var{dir}}. + +@c avoid splitting the warning from the explanation: +@need 2000 +@item --srcdir=@var{dirname} +@strong{Warning: using this option requires @sc{gnu} @code{make}, or another +@code{make} that implements the @code{VPATH} feature.}@* +Use this option to make configurations in directories separate from the +@value{GDBN} source directories. Among other things, you can use this to +build (or maintain) several configurations simultaneously, in separate +directories. @code{configure} writes configuration specific files in +the current directory, but arranges for them to use the source in the +directory @var{dirname}. @code{configure} creates directories under +the working directory in parallel to the source directories below +@var{dirname}. + +@item --norecursion +Configure only the directory level where @code{configure} is executed; do not +propagate configuration to subdirectories. + +@item --target=@var{target} +Configure @value{GDBN} for cross-debugging programs running on the specified +@var{target}. Without this option, @value{GDBN} is configured to debug +programs that run on the same machine (@var{host}) as @value{GDBN} itself. + +There is no convenient way to generate a list of all available targets. + +@item @var{host} @dots{} +Configure @value{GDBN} to run on the specified @var{host}. + +There is no convenient way to generate a list of all available hosts. +@end table + +There are many other options available as well, but they are generally +needed for special purposes only. + +@node Maintenance Commands +@appendix Maintenance Commands +@cindex maintenance commands +@cindex internal commands + +In addition to commands intended for @value{GDBN} users, @value{GDBN} +includes a number of commands intended for @value{GDBN} developers. +These commands are provided here for reference. + +@table @code +@kindex maint info breakpoints +@item @anchor{maint info breakpoints}maint info breakpoints +Using the same format as @samp{info breakpoints}, display both the +breakpoints you've set explicitly, and those @value{GDBN} is using for +internal purposes. Internal breakpoints are shown with negative +breakpoint numbers. The type column identifies what kind of breakpoint +is shown: + +@table @code +@item breakpoint +Normal, explicitly set breakpoint. + +@item watchpoint +Normal, explicitly set watchpoint. + +@item longjmp +Internal breakpoint, used to handle correctly stepping through +@code{longjmp} calls. + +@item longjmp resume +Internal breakpoint at the target of a @code{longjmp}. + +@item until +Temporary internal breakpoint used by the @value{GDBN} @code{until} command. + +@item finish +Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. + +@item shlib events +Shared library events. + +@end table + +@kindex maint internal-error +@kindex maint internal-warning +@item maint internal-error +@itemx maint internal-warning +Cause @value{GDBN} to call the internal function @code{internal_error} +or @code{internal_warning} and hence behave as though an internal error +or internal warning has been detected. In addition to reporting the +internal problem, these functions give the user the opportunity to +either quit @value{GDBN} or create a core file of the current +@value{GDBN} session. + +@smallexample +(gdb) @kbd{maint internal-error testing, 1, 2} +@dots{}/maint.c:121: internal-error: testing, 1, 2 +A problem internal to GDB has been detected. Further +debugging may prove unreliable. +Quit this debugging session? (y or n) @kbd{n} +Create a core file? (y or n) @kbd{n} +(gdb) +@end smallexample + +Takes an optional parameter that is used as the text of the error or +warning message. + +@kindex maint print dummy-frames +@item maint print dummy-frames + +Prints the contents of @value{GDBN}'s internal dummy-frame stack. + +@smallexample +(gdb) @kbd{b add} +@dots{} +(gdb) @kbd{print add(2,3)} +Breakpoint 2, add (a=2, b=3) at @dots{} +58 return (a + b); +The program being debugged stopped while in a function called from GDB. +@dots{} +(gdb) @kbd{maint print dummy-frames} +0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 + top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@} + call_lo=0x01014000 call_hi=0x01014001 +(gdb) +@end smallexample + +Takes an optional file parameter. + +@kindex maint print registers +@kindex maint print raw-registers +@kindex maint print cooked-registers +@kindex maint print register-groups +@item maint print registers +@itemx maint print raw-registers +@itemx maint print cooked-registers +@itemx maint print register-groups +Print @value{GDBN}'s internal register data structures. + +The command @code{maint print raw-registers} includes the contents of +the raw register cache; the command @code{maint print cooked-registers} +includes the (cooked) value of all registers; and the command +@code{maint print register-groups} includes the groups that each +register is a member of. @xref{Registers,, Registers, gdbint, +@value{GDBN} Internals}. + +Takes an optional file parameter. + +@kindex maint print reggroups +@item maint print reggroups +Print @value{GDBN}'s internal register group data structures. + +Takes an optional file parameter. + +@smallexample +(gdb) @kbd{maint print reggroups} + Group Type + general user + float user + all user + vector user + system user + save internal + restore internal +@end smallexample + +@kindex maint set profile +@kindex maint show profile +@cindex profiling GDB +@item maint set profile +@itemx maint show profile +Control profiling of @value{GDBN}. + +Profiling will be disabled until you use the @samp{maint set profile} +command to enable it. When you enable profiling, the system will begin +collecting timing and execution count data; when you disable profiling or +exit @value{GDBN}, the results will be written to a log file. Remember that +if you use profiling, @value{GDBN} will overwrite the profiling log file +(often called @file{gmon.out}). If you have a record of important profiling +data in a @file{gmon.out} file, be sure to move it to a safe location. + +Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be +compiled with the @samp{-pg} compiler option. + +@end table + + +@node Remote Protocol +@appendix @value{GDBN} Remote Serial Protocol + +@menu +* Overview:: +* Packets:: +* Stop Reply Packets:: +* General Query Packets:: +* Register Packet Format:: +* Examples:: +* File-I/O remote protocol extension:: +@end menu + +@node Overview +@section Overview + +There may be occasions when you need to know something about the +protocol---for example, if there is only one serial port to your target +machine, you might want your program to do something special if it +recognizes a packet meant for @value{GDBN}. + +In the examples below, @samp{->} and @samp{<-} are used to indicate +transmitted and received data respectfully. + +@cindex protocol, @value{GDBN} remote serial +@cindex serial protocol, @value{GDBN} remote +@cindex remote serial protocol +All @value{GDBN} commands and responses (other than acknowledgments) are +sent as a @var{packet}. A @var{packet} is introduced with the character +@samp{$}, the actual @var{packet-data}, and the terminating character +@samp{#} followed by a two-digit @var{checksum}: + +@smallexample +@code{$}@var{packet-data}@code{#}@var{checksum} +@end smallexample +@noindent + +@cindex checksum, for @value{GDBN} remote +@noindent +The two-digit @var{checksum} is computed as the modulo 256 sum of all +characters between the leading @samp{$} and the trailing @samp{#} (an +eight bit unsigned checksum). + +Implementors should note that prior to @value{GDBN} 5.0 the protocol +specification also included an optional two-digit @var{sequence-id}: + +@smallexample +@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} +@end smallexample + +@cindex sequence-id, for @value{GDBN} remote +@noindent +That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} +has never output @var{sequence-id}s. Stubs that handle packets added +since @value{GDBN} 5.0 must not accept @var{sequence-id}. + +@cindex acknowledgment, for @value{GDBN} remote +When either the host or the target machine receives a packet, the first +response expected is an acknowledgment: either @samp{+} (to indicate +the package was received correctly) or @samp{-} (to request +retransmission): + +@smallexample +-> @code{$}@var{packet-data}@code{#}@var{checksum} +<- @code{+} +@end smallexample +@noindent + +The host (@value{GDBN}) sends @var{command}s, and the target (the +debugging stub incorporated in your program) sends a @var{response}. In +the case of step and continue @var{command}s, the response is only sent +when the operation has completed (the target has again stopped). + +@var{packet-data} consists of a sequence of characters with the +exception of @samp{#} and @samp{$} (see @samp{X} packet for additional +exceptions). + +Fields within the packet should be separated using @samp{,} @samp{;} or +@cindex remote protocol, field separator +@samp{:}. Except where otherwise noted all numbers are represented in +@sc{hex} with leading zeros suppressed. + +Implementors should note that prior to @value{GDBN} 5.0, the character +@samp{:} could not appear as the third character in a packet (as it +would potentially conflict with the @var{sequence-id}). + +Response @var{data} can be run-length encoded to save space. A @samp{*} +means that the next character is an @sc{ascii} encoding giving a repeat count +which stands for that many repetitions of the character preceding the +@samp{*}. The encoding is @code{n+29}, yielding a printable character +where @code{n >=3} (which is where rle starts to win). The printable +characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric +value greater than 126 should not be used. + +So: +@smallexample +"@code{0* }" +@end smallexample +@noindent +means the same as "0000". + +The error response returned for some packets includes a two character +error number. That number is not well defined. + +For any @var{command} not supported by the stub, an empty response +(@samp{$#00}) should be returned. That way it is possible to extend the +protocol. A newer @value{GDBN} can tell if a packet is supported based +on that response. + +A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, +@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are +optional. + +@node Packets +@section Packets + +The following table provides a complete list of all currently defined +@var{command}s and their corresponding response @var{data}. + +@table @r + +@item @code{!} --- extended mode +@cindex @code{!} packet + +Enable extended mode. In extended mode, the remote server is made +persistent. The @samp{R} packet is used to restart the program being +debugged. + +Reply: +@table @samp +@item OK +The remote target both supports and has enabled extended mode. +@end table + +@item @code{?} --- last signal +@cindex @code{?} packet + +Indicate the reason the target halted. The reply is the same as for +step and continue. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item @code{a} --- reserved + +Reserved for future use. + +@item @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,@dots{}} --- set program arguments @strong{(reserved)} +@cindex @code{A} packet + +Initialized @samp{argv[]} array passed into program. @var{arglen} +specifies the number of bytes in the hex encoded byte stream @var{arg}. +See @code{gdbserver} for more details. + +Reply: +@table @samp +@item OK +@item E@var{NN} +@end table + +@item @code{b}@var{baud} --- set baud @strong{(deprecated)} +@cindex @code{b} packet + +Change the serial line speed to @var{baud}. + +JTC: @emph{When does the transport layer state change? When it's +received, or after the ACK is transmitted. In either case, there are +problems if the command or the acknowledgment packet is dropped.} + +Stan: @emph{If people really wanted to add something like this, and get +it working for the first time, they ought to modify ser-unix.c to send +some kind of out-of-band message to a specially-setup stub and have the +switch happen "in between" packets, so that from remote protocol's point +of view, nothing actually happened.} + +@item @code{B}@var{addr},@var{mode} --- set breakpoint @strong{(deprecated)} +@cindex @code{B} packet + +Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a +breakpoint at @var{addr}. + +This packet has been replaced by the @samp{Z} and @samp{z} packets +(@pxref{insert breakpoint or watchpoint packet}). + +@item @code{c}@var{addr} --- continue +@cindex @code{c} packet + +@var{addr} is address to resume. If @var{addr} is omitted, resume at +current address. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item @code{C}@var{sig}@code{;}@var{addr} --- continue with signal +@cindex @code{C} packet + +Continue with signal @var{sig} (hex signal number). If +@code{;}@var{addr} is omitted, resume at same address. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item @code{d} --- toggle debug @strong{(deprecated)} +@cindex @code{d} packet + +Toggle debug flag. + +@item @code{D} --- detach +@cindex @code{D} packet + +Detach @value{GDBN} from the remote system. Sent to the remote target +before @value{GDBN} disconnects via the @code{detach} command. + +Reply: +@table @samp +@item @emph{no response} +@value{GDBN} does not check for any response after sending this packet. +@end table + +@item @code{e} --- reserved + +Reserved for future use. + +@item @code{E} --- reserved + +Reserved for future use. + +@item @code{f} --- reserved + +Reserved for future use. + +@item @code{F}@var{RC}@code{,}@var{EE}@code{,}@var{CF}@code{;}@var{XX} --- Reply to target's F packet. +@cindex @code{F} packet + +This packet is send by @value{GDBN} as reply to a @code{F} request packet +sent by the target. This is part of the File-I/O protocol extension. +@xref{File-I/O remote protocol extension}, for the specification. + +@item @code{g} --- read registers +@anchor{read registers packet} +@cindex @code{g} packet + +Read general registers. + +Reply: +@table @samp +@item @var{XX@dots{}} +Each byte of register data is described by two hex digits. The bytes +with the register are transmitted in target byte order. The size of +each register and their position within the @samp{g} @var{packet} are +determined by the @value{GDBN} internal macros +@var{DEPRECATED_REGISTER_RAW_SIZE} and @var{REGISTER_NAME} macros. The +specification of several standard @code{g} packets is specified below. +@item E@var{NN} +for an error. +@end table + +@item @code{G}@var{XX@dots{}} --- write regs +@cindex @code{G} packet + +@xref{read registers packet}, for a description of the @var{XX@dots{}} +data. + +Reply: +@table @samp +@item OK +for success +@item E@var{NN} +for an error +@end table + +@item @code{h} --- reserved + +Reserved for future use. + +@item @code{H}@var{c}@var{t@dots{}} --- set thread +@cindex @code{H} packet + +Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, +@samp{G}, et.al.). @var{c} depends on the operation to be performed: it +should be @samp{c} for step and continue operations, @samp{g} for other +operations. The thread designator @var{t@dots{}} may be -1, meaning all +the threads, a thread number, or zero which means pick any thread. + +Reply: +@table @samp +@item OK +for success +@item E@var{NN} +for an error +@end table + +@c FIXME: JTC: +@c 'H': How restrictive (or permissive) is the thread model. If a +@c thread is selected and stopped, are other threads allowed +@c to continue to execute? As I mentioned above, I think the +@c semantics of each command when a thread is selected must be +@c described. For example: +@c +@c 'g': If the stub supports threads and a specific thread is +@c selected, returns the register block from that thread; +@c otherwise returns current registers. +@c +@c 'G' If the stub supports threads and a specific thread is +@c selected, sets the registers of the register block of +@c that thread; otherwise sets current registers. + +@item @code{i}@var{addr}@code{,}@var{nnn} --- cycle step @strong{(draft)} +@anchor{cycle step packet} +@cindex @code{i} packet + +Step the remote target by a single clock cycle. If @code{,}@var{nnn} is +present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle +step starting at that address. + +@item @code{I} --- signal then cycle step @strong{(reserved)} +@cindex @code{I} packet + +@xref{step with signal packet}. @xref{cycle step packet}. + +@item @code{j} --- reserved + +Reserved for future use. + +@item @code{J} --- reserved + +Reserved for future use. + +@item @code{k} --- kill request +@cindex @code{k} packet + +FIXME: @emph{There is no description of how to operate when a specific +thread context has been selected (i.e.@: does 'k' kill only that +thread?)}. + +@item @code{K} --- reserved + +Reserved for future use. + +@item @code{l} --- reserved + +Reserved for future use. + +@item @code{L} --- reserved + +Reserved for future use. + +@item @code{m}@var{addr}@code{,}@var{length} --- read memory +@cindex @code{m} packet + +Read @var{length} bytes of memory starting at address @var{addr}. +Neither @value{GDBN} nor the stub assume that sized memory transfers are +assumed using word aligned accesses. FIXME: @emph{A word aligned memory +transfer mechanism is needed.} + +Reply: +@table @samp +@item @var{XX@dots{}} +@var{XX@dots{}} is mem contents. Can be fewer bytes than requested if able +to read only part of the data. Neither @value{GDBN} nor the stub assume +that sized memory transfers are assumed using word aligned +accesses. FIXME: @emph{A word aligned memory transfer mechanism is +needed.} +@item E@var{NN} +@var{NN} is errno +@end table + +@item @code{M}@var{addr},@var{length}@code{:}@var{XX@dots{}} --- write mem +@cindex @code{M} packet + +Write @var{length} bytes of memory starting at address @var{addr}. +@var{XX@dots{}} is the data. + +Reply: +@table @samp +@item OK +for success +@item E@var{NN} +for an error (this includes the case where only part of the data was +written). +@end table + +@item @code{n} --- reserved + +Reserved for future use. + +@item @code{N} --- reserved + +Reserved for future use. + +@item @code{o} --- reserved + +Reserved for future use. + +@item @code{O} --- reserved + +Reserved for future use. + +@item @code{p}@var{n@dots{}} --- read reg @strong{(reserved)} +@cindex @code{p} packet + +@xref{write register packet}. + +Reply: +@table @samp +@item @var{r@dots{}.} +The hex encoded value of the register in target byte order. +@end table + +@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register +@anchor{write register packet} +@cindex @code{P} packet + +Write register @var{n@dots{}} with value @var{r@dots{}}, which contains two hex +digits for each byte in the register (target byte order). + +Reply: +@table @samp +@item OK +for success +@item E@var{NN} +for an error +@end table + +@item @code{q}@var{query} --- general query +@anchor{general query packet} +@cindex @code{q} packet + +Request info about @var{query}. In general @value{GDBN} queries have a +leading upper case letter. Custom vendor queries should use a company +prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may optionally +be followed by a @samp{,} or @samp{;} separated list. Stubs must ensure +that they match the full @var{query} name. + +Reply: +@table @samp +@item @var{XX@dots{}} +Hex encoded data from query. The reply can not be empty. +@item E@var{NN} +error reply +@item +Indicating an unrecognized @var{query}. +@end table + +@item @code{Q}@var{var}@code{=}@var{val} --- general set +@cindex @code{Q} packet + +Set value of @var{var} to @var{val}. + +@xref{general query packet}, for a discussion of naming conventions. + +@item @code{r} --- reset @strong{(deprecated)} +@cindex @code{r} packet + +Reset the entire system. + +@item @code{R}@var{XX} --- remote restart +@cindex @code{R} packet + +Restart the program being debugged. @var{XX}, while needed, is ignored. +This packet is only available in extended mode. + +Reply: +@table @samp +@item @emph{no reply} +The @samp{R} packet has no reply. +@end table + +@item @code{s}@var{addr} --- step +@cindex @code{s} packet + +@var{addr} is address to resume. If @var{addr} is omitted, resume at +same address. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item @code{S}@var{sig}@code{;}@var{addr} --- step with signal +@anchor{step with signal packet} +@cindex @code{S} packet + +Like @samp{C} but step not continue. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search +@cindex @code{t} packet + +Search backwards starting at address @var{addr} for a match with pattern +@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes. +@var{addr} must be at least 3 digits. + +@item @code{T}@var{XX} --- thread alive +@cindex @code{T} packet + +Find out if the thread XX is alive. + +Reply: +@table @samp +@item OK +thread is still alive +@item E@var{NN} +thread is dead +@end table + +@item @code{u} --- reserved + +Reserved for future use. + +@item @code{U} --- reserved + +Reserved for future use. + +@item @code{v} --- verbose packet prefix + +Packets starting with @code{v} are identified by a multi-letter name, +up to the first @code{;} or @code{?} (or the end of the packet). + +@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume +@cindex @code{vCont} packet + +Resume the inferior. Different actions may be specified for each thread. +If an action is specified with no @var{tid}, then it is applied to any +threads that don't have a specific action specified; if no default action is +specified then other threads should remain stopped. Specifying multiple +default actions is an error; specifying no actions is also an error. +Thread IDs are specified in hexadecimal. Currently supported actions are: + +@table @code +@item c +Continue. +@item C@var{sig} +Continue with signal @var{sig}. @var{sig} should be two hex digits. +@item s +Step. +@item S@var{sig} +Step with signal @var{sig}. @var{sig} should be two hex digits. +@end table + +The optional @var{addr} argument normally associated with these packets is +not supported in @code{vCont}. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item @code{vCont?} --- extended resume query +@cindex @code{vCont?} packet + +Query support for the @code{vCont} packet. + +Reply: +@table @samp +@item @code{vCont}[;@var{action}]... +The @code{vCont} packet is supported. Each @var{action} is a supported +command in the @code{vCont} packet. +@item +The @code{vCont} packet is not supported. +@end table + +@item @code{V} --- reserved + +Reserved for future use. + +@item @code{w} --- reserved + +Reserved for future use. + +@item @code{W} --- reserved + +Reserved for future use. + +@item @code{x} --- reserved + +Reserved for future use. + +@item @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX@dots{}} --- write mem (binary) +@cindex @code{X} packet + +@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}} +is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are +escaped using @code{0x7d}. + +Reply: +@table @samp +@item OK +for success +@item E@var{NN} +for an error +@end table + +@item @code{y} --- reserved + +Reserved for future use. + +@item @code{Y} reserved + +Reserved for future use. + +@item @code{z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- remove breakpoint or watchpoint @strong{(draft)} +@itemx @code{Z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- insert breakpoint or watchpoint @strong{(draft)} +@anchor{insert breakpoint or watchpoint packet} +@cindex @code{z} packet +@cindex @code{Z} packets + +Insert (@code{Z}) or remove (@code{z}) a @var{type} breakpoint or +watchpoint starting at address @var{address} and covering the next +@var{length} bytes. + +Each breakpoint and watchpoint packet @var{type} is documented +separately. + +@emph{Implementation notes: A remote target shall return an empty string +for an unrecognized breakpoint or watchpoint packet @var{type}. A +remote target shall support either both or neither of a given +@code{Z}@var{type}@dots{} and @code{z}@var{type}@dots{} packet pair. To +avoid potential problems with duplicate packets, the operations should +be implemented in an idempotent way.} + +@item @code{z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- remove memory breakpoint @strong{(draft)} +@item @code{Z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- insert memory breakpoint @strong{(draft)} +@cindex @code{z0} packet +@cindex @code{Z0} packet + +Insert (@code{Z0}) or remove (@code{z0}) a memory breakpoint at address +@code{addr} of size @code{length}. + +A memory breakpoint is implemented by replacing the instruction at +@var{addr} with a software breakpoint or trap instruction. The +@code{length} is used by targets that indicates the size of the +breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and +@sc{mips} can insert either a 2 or 4 byte breakpoint). + +@emph{Implementation note: It is possible for a target to copy or move +code that contains memory breakpoints (e.g., when implementing +overlays). The behavior of this packet, in the presence of such a +target, is not defined.} + +Reply: +@table @samp +@item OK +success +@item +not supported +@item E@var{NN} +for an error +@end table + +@item @code{z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- remove hardware breakpoint @strong{(draft)} +@item @code{Z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- insert hardware breakpoint @strong{(draft)} +@cindex @code{z1} packet +@cindex @code{Z1} packet + +Insert (@code{Z1}) or remove (@code{z1}) a hardware breakpoint at +address @code{addr} of size @code{length}. + +A hardware breakpoint is implemented using a mechanism that is not +dependant on being able to modify the target's memory. + +@emph{Implementation note: A hardware breakpoint is not affected by code +movement.} + +Reply: +@table @samp +@item OK +success +@item +not supported +@item E@var{NN} +for an error +@end table + +@item @code{z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- remove write watchpoint @strong{(draft)} +@item @code{Z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- insert write watchpoint @strong{(draft)} +@cindex @code{z2} packet +@cindex @code{Z2} packet + +Insert (@code{Z2}) or remove (@code{z2}) a write watchpoint. + +Reply: +@table @samp +@item OK +success +@item +not supported +@item E@var{NN} +for an error +@end table + +@item @code{z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- remove read watchpoint @strong{(draft)} +@item @code{Z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- insert read watchpoint @strong{(draft)} +@cindex @code{z3} packet +@cindex @code{Z3} packet + +Insert (@code{Z3}) or remove (@code{z3}) a read watchpoint. + +Reply: +@table @samp +@item OK +success +@item +not supported +@item E@var{NN} +for an error +@end table + +@item @code{z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- remove access watchpoint @strong{(draft)} +@item @code{Z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- insert access watchpoint @strong{(draft)} +@cindex @code{z4} packet +@cindex @code{Z4} packet + +Insert (@code{Z4}) or remove (@code{z4}) an access watchpoint. + +Reply: +@table @samp +@item OK +success +@item +not supported +@item E@var{NN} +for an error +@end table + +@end table + +@node Stop Reply Packets +@section Stop Reply Packets +@cindex stop reply packets + +The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can +receive any of the below as a reply. In the case of the @samp{C}, +@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned +when the target halts. In the below the exact meaning of @samp{signal +number} is poorly defined. In general one of the UNIX signal numbering +conventions is used. + +@table @samp + +@item S@var{AA} +@var{AA} is the signal number + +@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} +@cindex @code{T} packet reply + +@var{AA} = two hex digit signal number; @var{n...} = register number +(hex), @var{r...} = target byte ordered register contents, size defined +by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, +@var{r...} = thread process ID, this is a hex integer; @var{n...} = +(@samp{watch} | @samp{rwatch} | @samp{awatch}, @var{r...} = data +address, this is a hex integer; @var{n...} = other string not starting +with valid hex digit. @value{GDBN} should ignore this @var{n...}, +@var{r...} pair and go on to the next. This way we can extend the +protocol. + +@item W@var{AA} + +The process exited, and @var{AA} is the exit status. This is only +applicable to certain targets. + +@item X@var{AA} + +The process terminated with signal @var{AA}. + +@item O@var{XX@dots{}} + +@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at +any time while the program is running and the debugger should continue +to wait for @samp{W}, @samp{T}, etc. + +@item F@var{call-id}@code{,}@var{parameter@dots{}} + +@var{call-id} is the identifier which says which host system call should +be called. This is just the name of the function. Translation into the +correct system call is only applicable as it's defined in @value{GDBN}. +@xref{File-I/O remote protocol extension}, for a list of implemented +system calls. + +@var{parameter@dots{}} is a list of parameters as defined for this very +system call. + +The target replies with this packet when it expects @value{GDBN} to call +a host system call on behalf of the target. @value{GDBN} replies with +an appropriate @code{F} packet and keeps up waiting for the next reply +packet from the target. The latest @samp{C}, @samp{c}, @samp{S} or +@samp{s} action is expected to be continued. +@xref{File-I/O remote protocol extension}, for more details. + +@end table + +@node General Query Packets +@section General Query Packets + +The following set and query packets have already been defined. + +@table @r + +@item @code{q}@code{C} --- current thread + +Return the current thread id. + +Reply: +@table @samp +@item @code{QC}@var{pid} +Where @var{pid} is a HEX encoded 16 bit process id. +@item * +Any other reply implies the old pid. +@end table + +@item @code{q}@code{fThreadInfo} -- all thread ids + +@code{q}@code{sThreadInfo} + +Obtain a list of active thread ids from the target (OS). Since there +may be too many active threads to fit into one reply packet, this query +works iteratively: it may require more than one query/reply sequence to +obtain the entire list of threads. The first query of the sequence will +be the @code{qf}@code{ThreadInfo} query; subsequent queries in the +sequence will be the @code{qs}@code{ThreadInfo} query. + +NOTE: replaces the @code{qL} query (see below). + +Reply: +@table @samp +@item @code{m}@var{id} +A single thread id +@item @code{m}@var{id},@var{id}@dots{} +a comma-separated list of thread ids +@item @code{l} +(lower case 'el') denotes end of list. +@end table + +In response to each query, the target will reply with a list of one or +more thread ids, in big-endian hex, separated by commas. @value{GDBN} +will respond to each reply with a request for more thread ids (using the +@code{qs} form of the query), until the target responds with @code{l} +(lower-case el, for @code{'last'}). + +@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info + +Where @var{id} is a thread-id in big-endian hex. Obtain a printable +string description of a thread's attributes from the target OS. This +string may contain anything that the target OS thinks is interesting for +@value{GDBN} to tell the user about the thread. The string is displayed +in @value{GDBN}'s @samp{info threads} display. Some examples of +possible thread extra info strings are ``Runnable'', or ``Blocked on +Mutex''. + +Reply: +@table @samp +@item @var{XX@dots{}} +Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising +the printable string containing the extra information about the thread's +attributes. +@end table + +@item @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} --- query @var{LIST} or @var{threadLIST} @strong{(deprecated)} + +Obtain thread information from RTOS. Where: @var{startflag} (one hex +digit) is one to indicate the first query and zero to indicate a +subsequent query; @var{threadcount} (two hex digits) is the maximum +number of threads the response packet can contain; and @var{nextthread} +(eight hex digits), for subsequent queries (@var{startflag} is zero), is +returned in the response as @var{argthread}. + +NOTE: this query is replaced by the @code{q}@code{fThreadInfo} query +(see above). + +Reply: +@table @samp +@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}} +Where: @var{count} (two hex digits) is the number of threads being +returned; @var{done} (one hex digit) is zero to indicate more threads +and one indicates no further threads; @var{argthreadid} (eight hex +digits) is @var{nextthread} from the request packet; @var{thread@dots{}} +is a sequence of thread IDs from the target. @var{threadid} (eight hex +digits). See @code{remote.c:parse_threadlist_response()}. +@end table + +@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block + +Reply: +@table @samp +@item @code{E}@var{NN} +An error (such as memory fault) +@item @code{C}@var{CRC32} +A 32 bit cyclic redundancy check of the specified memory region. +@end table + +@item @code{q}@code{Offsets} --- query sect offs + +Get section offsets that the target used when re-locating the downloaded +image. @emph{Note: while a @code{Bss} offset is included in the +response, @value{GDBN} ignores this and instead applies the @code{Data} +offset to the @code{Bss} section.} + +Reply: +@table @samp +@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} +@end table + +@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request + +Returns information on @var{threadid}. Where: @var{mode} is a hex +encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. + +Reply: +@table @samp +@item * +@end table + +See @code{remote.c:remote_unpack_thread_info_response()}. + +@item @code{q}@code{Rcmd,}@var{command} --- remote command + +@var{command} (hex encoded) is passed to the local interpreter for +execution. Invalid commands should be reported using the output string. +Before the final result packet, the target may also respond with a +number of intermediate @code{O}@var{output} console output packets. +@emph{Implementors should note that providing access to a stubs's +interpreter may have security implications}. + +Reply: +@table @samp +@item OK +A command response with no output. +@item @var{OUTPUT} +A command response with the hex encoded output string @var{OUTPUT}. +@item @code{E}@var{NN} +Indicate a badly formed request. +@item @samp{} +When @samp{q}@samp{Rcmd} is not recognized. +@end table + +@item @code{qSymbol::} --- symbol lookup + +Notify the target that @value{GDBN} is prepared to serve symbol lookup +requests. Accept requests from the target for the values of symbols. + +Reply: +@table @samp +@item @code{OK} +The target does not need to look up any (more) symbols. +@item @code{qSymbol:}@var{sym_name} +The target requests the value of symbol @var{sym_name} (hex encoded). +@value{GDBN} may provide the value by using the +@code{qSymbol:}@var{sym_value}:@var{sym_name} message, described below. +@end table + +@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value + +Set the value of @var{sym_name} to @var{sym_value}. + +@var{sym_name} (hex encoded) is the name of a symbol whose value the +target has previously requested. + +@var{sym_value} (hex) is the value for symbol @var{sym_name}. If +@value{GDBN} cannot supply a value for @var{sym_name}, then this field +will be empty. + +Reply: +@table @samp +@item @code{OK} +The target does not need to look up any (more) symbols. +@item @code{qSymbol:}@var{sym_name} +The target requests the value of a new symbol @var{sym_name} (hex +encoded). @value{GDBN} will continue to supply the values of symbols +(if available), until the target ceases to request them. +@end table + +@item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data + +Read uninterpreted bytes from the target's special data area +identified by the keyword @code{object}. +Request @var{length} bytes starting at @var{offset} bytes into the data. +The content and encoding of @var{annex} is specific to the object; +it can supply additional details about what data to access. + +Here are the specific requests of this form defined so far. +All @samp{@code{qPart}:@var{object}:@code{read}:@dots{}} +requests use the same reply formats, listed below. + +@table @asis +@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length} +Access the target's @dfn{auxiliary vector}. @xref{Auxiliary Vector}. +Note @var{annex} must be empty. +@end table + +Reply: +@table @asis +@item @code{OK} +The @var{offset} in the request is at the end of the data. +There is no more data to be read. + +@item @var{XX@dots{}} +Hex encoded data bytes read. +This may be fewer bytes than the @var{length} in the request. + +@item @code{E00} +The request was malformed, or @var{annex} was invalid. + +@item @code{E}@var{nn} +The offset was invalid, or there was an error encountered reading the data. +@var{nn} is a hex-encoded @code{errno} value. + +@item @code{""} (empty) +An empty reply indicates the @var{object} or @var{annex} string was not +recognized by the stub. +@end table + +@item @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}} + +Write uninterpreted bytes into the target's special data area +identified by the keyword @code{object}, +starting at @var{offset} bytes into the data. +@var{data@dots{}} is the hex-encoded data to be written. +The content and encoding of @var{annex} is specific to the object; +it can supply additional details about what data to access. + +No requests of this form are presently in use. This specification +serves as a placeholder to document the common format that new +specific request specifications ought to use. + +Reply: +@table @asis +@item @var{nn} +@var{nn} (hex encoded) is the number of bytes written. +This may be fewer bytes than supplied in the request. + +@item @code{E00} +The request was malformed, or @var{annex} was invalid. + +@item @code{E}@var{nn} +The offset was invalid, or there was an error encountered writing the data. +@var{nn} is a hex-encoded @code{errno} value. + +@item @code{""} (empty) +An empty reply indicates the @var{object} or @var{annex} string was not +recognized by the stub, or that the object does not support writing. +@end table + +@item @code{qPart}:@var{object}:@var{operation}:@dots{} +Requests of this form may be added in the future. When a stub does +not recognize the @var{object} keyword, or its support for +@var{object} does not recognize the @var{operation} keyword, +the stub must respond with an empty packet. +@end table + +@node Register Packet Format +@section Register Packet Format + +The following @samp{g}/@samp{G} packets have previously been defined. +In the below, some thirty-two bit registers are transferred as +sixty-four bits. Those registers should be zero/sign extended (which?) +to fill the space allocated. Register bytes are transfered in target +byte order. The two nibbles within a register byte are transfered +most-significant - least-significant. + +@table @r + +@item MIPS32 + +All registers are transfered as thirty-two bit quantities in the order: +32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point +registers; fsr; fir; fp. + +@item MIPS64 + +All registers are transfered as sixty-four bit quantities (including +thirty-two bit registers such as @code{sr}). The ordering is the same +as @code{MIPS32}. + +@end table + +@node Examples +@section Examples + +Example sequence of a target being re-started. Notice how the restart +does not get any direct output: + +@smallexample +-> @code{R00} +<- @code{+} +@emph{target restarts} +-> @code{?} +<- @code{+} +<- @code{T001:1234123412341234} +-> @code{+} +@end smallexample + +Example sequence of a target being stepped by a single instruction: + +@smallexample +-> @code{G1445@dots{}} +<- @code{+} +-> @code{s} +<- @code{+} +@emph{time passes} +<- @code{T001:1234123412341234} +-> @code{+} +-> @code{g} +<- @code{+} +<- @code{1455@dots{}} +-> @code{+} +@end smallexample + +@node File-I/O remote protocol extension +@section File-I/O remote protocol extension +@cindex File-I/O remote protocol extension + +@menu +* File-I/O Overview:: +* Protocol basics:: +* The F request packet:: +* The F reply packet:: +* Memory transfer:: +* The Ctrl-C message:: +* Console I/O:: +* The isatty call:: +* The system call:: +* List of supported calls:: +* Protocol specific representation of datatypes:: +* Constants:: +* File-I/O Examples:: +@end menu + +@node File-I/O Overview +@subsection File-I/O Overview +@cindex file-i/o overview + +The File I/O remote protocol extension (short: File-I/O) allows the +target to use the hosts file system and console I/O when calling various +system calls. System calls on the target system are translated into a +remote protocol packet to the host system which then performs the needed +actions and returns with an adequate response packet to the target system. +This simulates file system operations even on targets that lack file systems. + +The protocol is defined host- and target-system independent. It uses +it's own independent representation of datatypes and values. Both, +@value{GDBN} and the target's @value{GDBN} stub are responsible for +translating the system dependent values into the unified protocol values +when data is transmitted. + +The communication is synchronous. A system call is possible only +when GDB is waiting for the @samp{C}, @samp{c}, @samp{S} or @samp{s} +packets. While @value{GDBN} handles the request for a system call, +the target is stopped to allow deterministic access to the target's +memory. Therefore File-I/O is not interuptible by target signals. It +is possible to interrupt File-I/O by a user interrupt (Ctrl-C), though. + +The target's request to perform a host system call does not finish +the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means, +after finishing the system call, the target returns to continuing the +previous activity (continue, step). No additional continue or step +request from @value{GDBN} is required. + +@smallexample +(gdb) continue + <- target requests 'system call X' + target is stopped, @value{GDBN} executes system call + -> GDB returns result + ... target continues, GDB returns to wait for the target + <- target hits breakpoint and sends a Txx packet +@end smallexample + +The protocol is only used for files on the host file system and +for I/O on the console. Character or block special devices, pipes, +named pipes or sockets or any other communication method on the host +system are not supported by this protocol. + +@node Protocol basics +@subsection Protocol basics +@cindex protocol basics, file-i/o + +The File-I/O protocol uses the @code{F} packet, as request as well +as as reply packet. Since a File-I/O system call can only occur when +@value{GDBN} is waiting for the continuing or stepping target, the +File-I/O request is a reply that @value{GDBN} has to expect as a result +of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. +This @code{F} packet contains all information needed to allow @value{GDBN} +to call the appropriate host system call: + +@itemize @bullet +@item +A unique identifier for the requested system call. + +@item +All parameters to the system call. Pointers are given as addresses +in the target memory address space. Pointers to strings are given as +pointer/length pair. Numerical values are given as they are. +Numerical control values are given in a protocol specific representation. + +@end itemize -Some remote systems have used a different run-length encoding mechanism -loosely refered to as the cisco encoding. Following the @samp{*} -character are two hex digits that indicate the size of the packet. +At that point @value{GDBN} has to perform the following actions. -So: -@smallexample -"@code{0* }" -@end smallexample -@noindent -means the same as "0000". +@itemize @bullet +@item +If parameter pointer values are given, which point to data needed as input +to a system call, @value{GDBN} requests this data from the target with a +standard @code{m} packet request. This additional communication has to be +expected by the target implementation and is handled as any other @code{m} +packet. -The error response returned for some packets includes a two character -error number. That number is not well defined. +@item +@value{GDBN} translates all value from protocol representation to host +representation as needed. Datatypes are coerced into the host types. -For any @var{command} not supported by the stub, an empty response -(@samp{$#00}) should be returned. That way it is possible to extend the -protocol. A newer @value{GDBN} can tell if a packet is supported based -on that response. +@item +@value{GDBN} calls the system call -A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, -@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are -optional. +@item +It then coerces datatypes back to protocol representation. -@node Packets -@section Packets +@item +If pointer parameters in the request packet point to buffer space in which +a system call is expected to copy data to, the data is transmitted to the +target using a @code{M} or @code{X} packet. This packet has to be expected +by the target implementation and is handled as any other @code{M} or @code{X} +packet. -The following table provides a complete list of all currently defined -@var{command}s and their corresponding response @var{data}. +@end itemize -@table @r +Eventually @value{GDBN} replies with another @code{F} packet which contains all +necessary information for the target to continue. This at least contains -@item @code{!} --- extended mode -@cindex @code{!} packet +@itemize @bullet +@item +Return value. -Enable extended mode. In extended mode, the remote server is made -persistent. The @samp{R} packet is used to restart the program being -debugged. +@item +@code{errno}, if has been changed by the system call. -Reply: -@table @samp -@item OK -The remote target both supports and has enabled extended mode. -@end table +@item +``Ctrl-C'' flag. -@item @code{?} --- last signal -@cindex @code{?} packet +@end itemize -Indicate the reason the target halted. The reply is the same as for -step and continue. +After having done the needed type and value coercion, the target continues +the latest continue or step action. -Reply: -@xref{Stop Reply Packets}, for the reply specifications. +@node The F request packet +@subsection The @code{F} request packet +@cindex file-i/o request packet +@cindex @code{F} request packet -@item @code{a} --- reserved +The @code{F} request packet has the following format: -Reserved for future use. +@table @samp -@item @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,@dots{}} --- set program arguments @strong{(reserved)} -@cindex @code{A} packet +@smallexample +@code{F}@var{call-id}@code{,}@var{parameter@dots{}} +@end smallexample -Initialized @samp{argv[]} array passed into program. @var{arglen} -specifies the number of bytes in the hex encoded byte stream @var{arg}. -See @code{gdbserver} for more details. +@var{call-id} is the identifier to indicate the host system call to be called. +This is just the name of the function. + +@var{parameter@dots{}} are the parameters to the system call. -Reply: -@table @samp -@item OK -@item E@var{NN} @end table -@item @code{b}@var{baud} --- set baud @strong{(deprecated)} -@cindex @code{b} packet +Parameters are hexadecimal integer values, either the real values in case +of scalar datatypes, as pointers to target buffer space in case of compound +datatypes and unspecified memory areas or as pointer/length pairs in case +of string parameters. These are appended to the call-id, each separated +from its predecessor by a comma. All values are transmitted in ASCII +string representation, pointer/length pairs separated by a slash. -Change the serial line speed to @var{baud}. +@node The F reply packet +@subsection The @code{F} reply packet +@cindex file-i/o reply packet +@cindex @code{F} reply packet -JTC: @emph{When does the transport layer state change? When it's -received, or after the ACK is transmitted. In either case, there are -problems if the command or the acknowledgment packet is dropped.} +The @code{F} reply packet has the following format: -Stan: @emph{If people really wanted to add something like this, and get -it working for the first time, they ought to modify ser-unix.c to send -some kind of out-of-band message to a specially-setup stub and have the -switch happen "in between" packets, so that from remote protocol's point -of view, nothing actually happened.} +@table @samp -@item @code{B}@var{addr},@var{mode} --- set breakpoint @strong{(deprecated)} -@cindex @code{B} packet +@smallexample +@code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment} +@end smallexample -Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a -breakpoint at @var{addr}. +@var{retcode} is the return code of the system call as hexadecimal value. -This packet has been replaced by the @samp{Z} and @samp{z} packets -(@pxref{insert breakpoint or watchpoint packet}). +@var{errno} is the errno set by the call, in protocol specific representation. +This parameter can be omitted if the call was successful. -@item @code{c}@var{addr} --- continue -@cindex @code{c} packet +@var{Ctrl-C flag} is only send if the user requested a break. In this +case, @var{errno} must be send as well, even if the call was successful. +The @var{Ctrl-C flag} itself consists of the character 'C': -@var{addr} is address to resume. If @var{addr} is omitted, resume at -current address. +@smallexample +F0,0,C +@end smallexample -Reply: -@xref{Stop Reply Packets}, for the reply specifications. +@noindent +or, if the call was interupted before the host call has been performed: -@item @code{C}@var{sig}@code{;}@var{addr} --- continue with signal -@cindex @code{C} packet +@smallexample +F-1,4,C +@end smallexample -Continue with signal @var{sig} (hex signal number). If -@code{;}@var{addr} is omitted, resume at same address. +@noindent +assuming 4 is the protocol specific representation of @code{EINTR}. -Reply: -@xref{Stop Reply Packets}, for the reply specifications. +@end table -@item @code{d} --- toggle debug @strong{(deprecated)} -@cindex @code{d} packet +@node Memory transfer +@subsection Memory transfer +@cindex memory transfer, in file-i/o protocol + +Structured data which is transferred using a memory read or write as e.g.@: +a @code{struct stat} is expected to be in a protocol specific format with +all scalar multibyte datatypes being big endian. This should be done by +the target before the @code{F} packet is sent resp.@: by @value{GDBN} before +it transfers memory to the target. Transferred pointers to structured +data should point to the already coerced data at any time. + +@node The Ctrl-C message +@subsection The Ctrl-C message +@cindex ctrl-c message, in file-i/o protocol + +A special case is, if the @var{Ctrl-C flag} is set in the @value{GDBN} +reply packet. In this case the target should behave, as if it had +gotten a break message. The meaning for the target is ``system call +interupted by @code{SIGINT}''. Consequentially, the target should actually stop +(as with a break message) and return to @value{GDBN} with a @code{T02} +packet. In this case, it's important for the target to know, in which +state the system call was interrupted. Since this action is by design +not an atomic operation, we have to differ between two cases: -Toggle debug flag. +@itemize @bullet +@item +The system call hasn't been performed on the host yet. -@item @code{D} --- detach -@cindex @code{D} packet +@item +The system call on the host has been finished. -Detach @value{GDBN} from the remote system. Sent to the remote target -before @value{GDBN} disconnects. +@end itemize -Reply: -@table @samp -@item @emph{no response} -@value{GDBN} does not check for any response after sending this packet. -@end table +These two states can be distinguished by the target by the value of the +returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system +call hasn't been performed. This is equivalent to the @code{EINTR} handling +on POSIX systems. In any other case, the target may presume that the +system call has been finished --- successful or not --- and should behave +as if the break message arrived right after the system call. + +@value{GDBN} must behave reliable. If the system call has not been called +yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as +@code{errno} in the packet. If the system call on the host has been finished +before the user requests a break, the full action must be finshed by +@value{GDBN}. This requires sending @code{M} or @code{X} packets as they fit. +The @code{F} packet may only be send when either nothing has happened +or the full action has been completed. + +@node Console I/O +@subsection Console I/O +@cindex console i/o as part of file-i/o + +By default and if not explicitely closed by the target system, the file +descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output +on the @value{GDBN} console is handled as any other file output operation +(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled +by @value{GDBN} so that after the target read request from file descriptor +0 all following typing is buffered until either one of the following +conditions is met: -@item @code{e} --- reserved +@itemize @bullet +@item +The user presses @kbd{Ctrl-C}. The behaviour is as explained above, the +@code{read} +system call is treated as finished. -Reserved for future use. +@item +The user presses @kbd{Enter}. This is treated as end of input with a trailing +line feed. -@item @code{E} --- reserved +@item +The user presses @kbd{Ctrl-D}. This is treated as end of input. No trailing +character, especially no Ctrl-D is appended to the input. -Reserved for future use. +@end itemize -@item @code{f} --- reserved +If the user has typed more characters as fit in the buffer given to +the read call, the trailing characters are buffered in @value{GDBN} until +either another @code{read(0, @dots{})} is requested by the target or debugging +is stopped on users request. -Reserved for future use. +@node The isatty call +@subsection The isatty(3) call +@cindex isatty call, file-i/o protocol -@item @code{F} --- reserved +A special case in this protocol is the library call @code{isatty} which +is implemented as it's own call inside of this protocol. It returns +1 to the target if the file descriptor given as parameter is attached +to the @value{GDBN} console, 0 otherwise. Implementing through system calls +would require implementing @code{ioctl} and would be more complex than +needed. -Reserved for future use. +@node The system call +@subsection The system(3) call +@cindex system call, file-i/o protocol -@item @code{g} --- read registers -@anchor{read registers packet} -@cindex @code{g} packet +The other special case in this protocol is the @code{system} call which +is implemented as it's own call, too. @value{GDBN} is taking over the full +task of calling the necessary host calls to perform the @code{system} +call. The return value of @code{system} is simplified before it's returned +to the target. Basically, the only signal transmitted back is @code{EINTR} +in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists +entirely of the exit status of the called command. -Read general registers. +Due to security concerns, the @code{system} call is refused to be called +by @value{GDBN} by default. The user has to allow this call explicitly by +entering -Reply: @table @samp -@item @var{XX@dots{}} -Each byte of register data is described by two hex digits. The bytes -with the register are transmitted in target byte order. The size of -each register and their position within the @samp{g} @var{packet} are -determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} -and @var{REGISTER_NAME} macros. The specification of several standard -@code{g} packets is specified below. -@item E@var{NN} -for an error. +@kindex set remote system-call-allowed 1 +@item @code{set remote system-call-allowed 1} @end table -@item @code{G}@var{XX@dots{}} --- write regs -@cindex @code{G} packet - -@xref{read registers packet}, for a description of the @var{XX@dots{}} -data. +Disabling the @code{system} call is done by -Reply: @table @samp -@item OK -for success -@item E@var{NN} -for an error +@kindex set remote system-call-allowed 0 +@item @code{set remote system-call-allowed 0} @end table -@item @code{h} --- reserved +The current setting is shown by typing -Reserved for future use. +@table @samp +@kindex show remote system-call-allowed +@item @code{show remote system-call-allowed} +@end table -@item @code{H}@var{c}@var{t@dots{}} --- set thread -@cindex @code{H} packet +@node List of supported calls +@subsection List of supported calls +@cindex list of supported file-i/o calls -Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, -@samp{G}, et.al.). @var{c} depends on the operation to be performed: it -should be @samp{c} for step and continue operations, @samp{g} for other -operations. The thread designator @var{t@dots{}} may be -1, meaning all -the threads, a thread number, or zero which means pick any thread. +@menu +* open:: +* close:: +* read:: +* write:: +* lseek:: +* rename:: +* unlink:: +* stat/fstat:: +* gettimeofday:: +* isatty:: +* system:: +@end menu -Reply: -@table @samp -@item OK -for success -@item E@var{NN} -for an error -@end table +@node open +@unnumberedsubsubsec open +@cindex open, file-i/o system call -@c FIXME: JTC: -@c 'H': How restrictive (or permissive) is the thread model. If a -@c thread is selected and stopped, are other threads allowed -@c to continue to execute? As I mentioned above, I think the -@c semantics of each command when a thread is selected must be -@c described. For example: -@c -@c 'g': If the stub supports threads and a specific thread is -@c selected, returns the register block from that thread; -@c otherwise returns current registers. -@c -@c 'G' If the stub supports threads and a specific thread is -@c selected, sets the registers of the register block of -@c that thread; otherwise sets current registers. +@smallexample +@exdent Synopsis: +int open(const char *pathname, int flags); +int open(const char *pathname, int flags, mode_t mode); -@item @code{i}@var{addr}@code{,}@var{nnn} --- cycle step @strong{(draft)} -@anchor{cycle step packet} -@cindex @code{i} packet +@exdent Request: +Fopen,pathptr/len,flags,mode +@end smallexample -Step the remote target by a single clock cycle. If @code{,}@var{nnn} is -present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle -step starting at that address. +@noindent +@code{flags} is the bitwise or of the following values: -@item @code{I} --- signal then cycle step @strong{(reserved)} -@cindex @code{I} packet +@table @code +@item O_CREAT +If the file does not exist it will be created. The host +rules apply as far as file ownership and time stamps +are concerned. -@xref{step with signal packet}. @xref{cycle step packet}. +@item O_EXCL +When used with O_CREAT, if the file already exists it is +an error and open() fails. -@item @code{j} --- reserved +@item O_TRUNC +If the file already exists and the open mode allows +writing (O_RDWR or O_WRONLY is given) it will be +truncated to length 0. -Reserved for future use. +@item O_APPEND +The file is opened in append mode. -@item @code{J} --- reserved +@item O_RDONLY +The file is opened for reading only. -Reserved for future use. +@item O_WRONLY +The file is opened for writing only. -@item @code{k} --- kill request -@cindex @code{k} packet +@item O_RDWR +The file is opened for reading and writing. -FIXME: @emph{There is no description of how to operate when a specific -thread context has been selected (i.e.@: does 'k' kill only that -thread?)}. +@noindent +Each other bit is silently ignored. -@item @code{K} --- reserved +@end table -Reserved for future use. +@noindent +@code{mode} is the bitwise or of the following values: -@item @code{l} --- reserved +@table @code +@item S_IRUSR +User has read permission. -Reserved for future use. +@item S_IWUSR +User has write permission. -@item @code{L} --- reserved +@item S_IRGRP +Group has read permission. -Reserved for future use. +@item S_IWGRP +Group has write permission. -@item @code{m}@var{addr}@code{,}@var{length} --- read memory -@cindex @code{m} packet +@item S_IROTH +Others have read permission. -Read @var{length} bytes of memory starting at address @var{addr}. -Neither @value{GDBN} nor the stub assume that sized memory transfers are -assumed using word aligned accesses. FIXME: @emph{A word aligned memory -transfer mechanism is needed.} +@item S_IWOTH +Others have write permission. + +@noindent +Each other bit is silently ignored. -Reply: -@table @samp -@item @var{XX@dots{}} -@var{XX@dots{}} is mem contents. Can be fewer bytes than requested if able -to read only part of the data. Neither @value{GDBN} nor the stub assume -that sized memory transfers are assumed using word aligned -accesses. FIXME: @emph{A word aligned memory transfer mechanism is -needed.} -@item E@var{NN} -@var{NN} is errno @end table -@item @code{M}@var{addr},@var{length}@code{:}@var{XX@dots{}} --- write mem -@cindex @code{M} packet +@smallexample +@exdent Return value: +open returns the new file descriptor or -1 if an error +occured. -Write @var{length} bytes of memory starting at address @var{addr}. -@var{XX@dots{}} is the data. +@exdent Errors: +@end smallexample -Reply: -@table @samp -@item OK -for success -@item E@var{NN} -for an error (this includes the case where only part of the data was -written). -@end table +@table @code +@item EEXIST +pathname already exists and O_CREAT and O_EXCL were used. -@item @code{n} --- reserved +@item EISDIR +pathname refers to a directory. -Reserved for future use. +@item EACCES +The requested access is not allowed. + +@item ENAMETOOLONG +pathname was too long. + +@item ENOENT +A directory component in pathname does not exist. + +@item ENODEV +pathname refers to a device, pipe, named pipe or socket. + +@item EROFS +pathname refers to a file on a read-only filesystem and +write access was requested. + +@item EFAULT +pathname is an invalid pointer value. + +@item ENOSPC +No space on device to create the file. + +@item EMFILE +The process already has the maximum number of files open. -@item @code{N} --- reserved +@item ENFILE +The limit on the total number of files open on the system +has been reached. -Reserved for future use. +@item EINTR +The call was interrupted by the user. +@end table -@item @code{o} --- reserved +@node close +@unnumberedsubsubsec close +@cindex close, file-i/o system call -Reserved for future use. +@smallexample +@exdent Synopsis: +int close(int fd); -@item @code{O} --- reserved +@exdent Request: +Fclose,fd -Reserved for future use. +@exdent Return value: +close returns zero on success, or -1 if an error occurred. -@item @code{p}@var{n@dots{}} --- read reg @strong{(reserved)} -@cindex @code{p} packet +@exdent Errors: +@end smallexample -@xref{write register packet}. +@table @code +@item EBADF +fd isn't a valid open file descriptor. -Reply: -@table @samp -@item @var{r@dots{}.} -The hex encoded value of the register in target byte order. +@item EINTR +The call was interrupted by the user. @end table -@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register -@anchor{write register packet} -@cindex @code{P} packet +@node read +@unnumberedsubsubsec read +@cindex read, file-i/o system call -Write register @var{n@dots{}} with value @var{r@dots{}}, which contains two hex -digits for each byte in the register (target byte order). +@smallexample +@exdent Synopsis: +int read(int fd, void *buf, unsigned int count); -Reply: -@table @samp -@item OK -for success -@item E@var{NN} -for an error -@end table +@exdent Request: +Fread,fd,bufptr,count -@item @code{q}@var{query} --- general query -@anchor{general query packet} -@cindex @code{q} packet +@exdent Return value: +On success, the number of bytes read is returned. +Zero indicates end of file. If count is zero, read +returns zero as well. On error, -1 is returned. -Request info about @var{query}. In general @value{GDBN} queries have a -leading upper case letter. Custom vendor queries should use a company -prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may optionally -be followed by a @samp{,} or @samp{;} separated list. Stubs must ensure -that they match the full @var{query} name. +@exdent Errors: +@end smallexample -Reply: -@table @samp -@item @var{XX@dots{}} -Hex encoded data from query. The reply can not be empty. -@item E@var{NN} -error reply -@item -Indicating an unrecognized @var{query}. +@table @code +@item EBADF +fd is not a valid file descriptor or is not open for +reading. + +@item EFAULT +buf is an invalid pointer value. + +@item EINTR +The call was interrupted by the user. @end table -@item @code{Q}@var{var}@code{=}@var{val} --- general set -@cindex @code{Q} packet +@node write +@unnumberedsubsubsec write +@cindex write, file-i/o system call -Set value of @var{var} to @var{val}. +@smallexample +@exdent Synopsis: +int write(int fd, const void *buf, unsigned int count); -@xref{general query packet}, for a discussion of naming conventions. +@exdent Request: +Fwrite,fd,bufptr,count -@item @code{r} --- reset @strong{(deprecated)} -@cindex @code{r} packet +@exdent Return value: +On success, the number of bytes written are returned. +Zero indicates nothing was written. On error, -1 +is returned. -Reset the entire system. +@exdent Errors: +@end smallexample -@item @code{R}@var{XX} --- remote restart -@cindex @code{R} packet +@table @code +@item EBADF +fd is not a valid file descriptor or is not open for +writing. -Restart the program being debugged. @var{XX}, while needed, is ignored. -This packet is only available in extended mode. +@item EFAULT +buf is an invalid pointer value. -Reply: -@table @samp -@item @emph{no reply} -The @samp{R} packet has no reply. +@item EFBIG +An attempt was made to write a file that exceeds the +host specific maximum file size allowed. + +@item ENOSPC +No space on device to write the data. + +@item EINTR +The call was interrupted by the user. @end table -@item @code{s}@var{addr} --- step -@cindex @code{s} packet +@node lseek +@unnumberedsubsubsec lseek +@cindex lseek, file-i/o system call -@var{addr} is address to resume. If @var{addr} is omitted, resume at -same address. +@smallexample +@exdent Synopsis: +long lseek (int fd, long offset, int flag); -Reply: -@xref{Stop Reply Packets}, for the reply specifications. +@exdent Request: +Flseek,fd,offset,flag +@end smallexample -@item @code{S}@var{sig}@code{;}@var{addr} --- step with signal -@anchor{step with signal packet} -@cindex @code{S} packet +@code{flag} is one of: -Like @samp{C} but step not continue. +@table @code +@item SEEK_SET +The offset is set to offset bytes. -Reply: -@xref{Stop Reply Packets}, for the reply specifications. +@item SEEK_CUR +The offset is set to its current location plus offset +bytes. -@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search -@cindex @code{t} packet +@item SEEK_END +The offset is set to the size of the file plus offset +bytes. +@end table -Search backwards starting at address @var{addr} for a match with pattern -@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes. -@var{addr} must be at least 3 digits. +@smallexample +@exdent Return value: +On success, the resulting unsigned offset in bytes from +the beginning of the file is returned. Otherwise, a +value of -1 is returned. -@item @code{T}@var{XX} --- thread alive -@cindex @code{T} packet +@exdent Errors: +@end smallexample -Find out if the thread XX is alive. +@table @code +@item EBADF +fd is not a valid open file descriptor. -Reply: -@table @samp -@item OK -thread is still alive -@item E@var{NN} -thread is dead +@item ESPIPE +fd is associated with the @value{GDBN} console. + +@item EINVAL +flag is not a proper value. + +@item EINTR +The call was interrupted by the user. @end table -@item @code{u} --- reserved +@node rename +@unnumberedsubsubsec rename +@cindex rename, file-i/o system call -Reserved for future use. +@smallexample +@exdent Synopsis: +int rename(const char *oldpath, const char *newpath); -@item @code{U} --- reserved +@exdent Request: +Frename,oldpathptr/len,newpathptr/len -Reserved for future use. +@exdent Return value: +On success, zero is returned. On error, -1 is returned. -@item @code{v} --- reserved +@exdent Errors: +@end smallexample -Reserved for future use. +@table @code +@item EISDIR +newpath is an existing directory, but oldpath is not a +directory. -@item @code{V} --- reserved +@item EEXIST +newpath is a non-empty directory. -Reserved for future use. +@item EBUSY +oldpath or newpath is a directory that is in use by some +process. -@item @code{w} --- reserved +@item EINVAL +An attempt was made to make a directory a subdirectory +of itself. -Reserved for future use. +@item ENOTDIR +A component used as a directory in oldpath or new +path is not a directory. Or oldpath is a directory +and newpath exists but is not a directory. -@item @code{W} --- reserved +@item EFAULT +oldpathptr or newpathptr are invalid pointer values. -Reserved for future use. +@item EACCES +No access to the file or the path of the file. -@item @code{x} --- reserved +@item ENAMETOOLONG -Reserved for future use. +oldpath or newpath was too long. -@item @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX@dots{}} --- write mem (binary) -@cindex @code{X} packet +@item ENOENT +A directory component in oldpath or newpath does not exist. -@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}} -is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are -escaped using @code{0x7d}. +@item EROFS +The file is on a read-only filesystem. -Reply: -@table @samp -@item OK -for success -@item E@var{NN} -for an error +@item ENOSPC +The device containing the file has no room for the new +directory entry. + +@item EINTR +The call was interrupted by the user. @end table -@item @code{y} --- reserved +@node unlink +@unnumberedsubsubsec unlink +@cindex unlink, file-i/o system call -Reserved for future use. +@smallexample +@exdent Synopsis: +int unlink(const char *pathname); -@item @code{Y} reserved +@exdent Request: +Funlink,pathnameptr/len -Reserved for future use. +@exdent Return value: +On success, zero is returned. On error, -1 is returned. -@item @code{z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- remove breakpoint or watchpoint @strong{(draft)} -@itemx @code{Z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- insert breakpoint or watchpoint @strong{(draft)} -@anchor{insert breakpoint or watchpoint packet} -@cindex @code{z} packet -@cindex @code{Z} packets +@exdent Errors: +@end smallexample -Insert (@code{Z}) or remove (@code{z}) a @var{type} breakpoint or -watchpoint starting at address @var{address} and covering the next -@var{length} bytes. +@table @code +@item EACCES +No access to the file or the path of the file. -Each breakpoint and watchpoint packet @var{type} is documented -separately. +@item EPERM +The system does not allow unlinking of directories. -@emph{Implementation notes: A remote target shall return an empty string -for an unrecognized breakpoint or watchpoint packet @var{type}. A -remote target shall support either both or neither of a given -@code{Z}@var{type}@dots{} and @code{z}@var{type}@dots{} packet pair. To -avoid potential problems with duplicate packets, the operations should -be implemented in an idempotent way.} +@item EBUSY +The file pathname cannot be unlinked because it's +being used by another process. -@item @code{z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- remove memory breakpoint @strong{(draft)} -@item @code{Z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- insert memory breakpoint @strong{(draft)} -@cindex @code{z0} packet -@cindex @code{Z0} packet +@item EFAULT +pathnameptr is an invalid pointer value. -Insert (@code{Z0}) or remove (@code{z0}) a memory breakpoint at address -@code{addr} of size @code{length}. +@item ENAMETOOLONG +pathname was too long. -A memory breakpoint is implemented by replacing the instruction at -@var{addr} with a software breakpoint or trap instruction. The -@code{length} is used by targets that indicates the size of the -breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and -@sc{mips} can insert either a 2 or 4 byte breakpoint). +@item ENOENT +A directory component in pathname does not exist. -@emph{Implementation note: It is possible for a target to copy or move -code that contains memory breakpoints (e.g., when implementing -overlays). The behavior of this packet, in the presence of such a -target, is not defined.} +@item ENOTDIR +A component of the path is not a directory. -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error +@item EROFS +The file is on a read-only filesystem. + +@item EINTR +The call was interrupted by the user. @end table -@item @code{z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- remove hardware breakpoint @strong{(draft)} -@item @code{Z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- insert hardware breakpoint @strong{(draft)} -@cindex @code{z1} packet -@cindex @code{Z1} packet +@node stat/fstat +@unnumberedsubsubsec stat/fstat +@cindex fstat, file-i/o system call +@cindex stat, file-i/o system call -Insert (@code{Z1}) or remove (@code{z1}) a hardware breakpoint at -address @code{addr} of size @code{length}. +@smallexample +@exdent Synopsis: +int stat(const char *pathname, struct stat *buf); +int fstat(int fd, struct stat *buf); -A hardware breakpoint is implemented using a mechanism that is not -dependant on being able to modify the target's memory. +@exdent Request: +Fstat,pathnameptr/len,bufptr +Ffstat,fd,bufptr -@emph{Implementation note: A hardware breakpoint is not affected by code -movement.} +@exdent Return value: +On success, zero is returned. On error, -1 is returned. -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error -@end table +@exdent Errors: +@end smallexample -@item @code{z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- remove write watchpoint @strong{(draft)} -@item @code{Z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- insert write watchpoint @strong{(draft)} -@cindex @code{z2} packet -@cindex @code{Z2} packet +@table @code +@item EBADF +fd is not a valid open file. -Insert (@code{Z2}) or remove (@code{z2}) a write watchpoint. +@item ENOENT +A directory component in pathname does not exist or the +path is an empty string. -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error -@end table +@item ENOTDIR +A component of the path is not a directory. -@item @code{z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- remove read watchpoint @strong{(draft)} -@item @code{Z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- insert read watchpoint @strong{(draft)} -@cindex @code{z3} packet -@cindex @code{Z3} packet +@item EFAULT +pathnameptr is an invalid pointer value. -Insert (@code{Z3}) or remove (@code{z3}) a read watchpoint. +@item EACCES +No access to the file or the path of the file. -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error +@item ENAMETOOLONG +pathname was too long. + +@item EINTR +The call was interrupted by the user. @end table -@item @code{z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- remove access watchpoint @strong{(draft)} -@item @code{Z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- insert access watchpoint @strong{(draft)} -@cindex @code{z4} packet -@cindex @code{Z4} packet +@node gettimeofday +@unnumberedsubsubsec gettimeofday +@cindex gettimeofday, file-i/o system call -Insert (@code{Z4}) or remove (@code{z4}) an access watchpoint. +@smallexample +@exdent Synopsis: +int gettimeofday(struct timeval *tv, void *tz); -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error +@exdent Request: +Fgettimeofday,tvptr,tzptr + +@exdent Return value: +On success, 0 is returned, -1 otherwise. + +@exdent Errors: +@end smallexample + +@table @code +@item EINVAL +tz is a non-NULL pointer. + +@item EFAULT +tvptr and/or tzptr is an invalid pointer value. @end table +@node isatty +@unnumberedsubsubsec isatty +@cindex isatty, file-i/o system call + +@smallexample +@exdent Synopsis: +int isatty(int fd); + +@exdent Request: +Fisatty,fd + +@exdent Return value: +Returns 1 if fd refers to the @value{GDBN} console, 0 otherwise. + +@exdent Errors: +@end smallexample + +@table @code +@item EINTR +The call was interrupted by the user. @end table -@node Stop Reply Packets -@section Stop Reply Packets -@cindex stop reply packets +@node system +@unnumberedsubsubsec system +@cindex system, file-i/o system call -The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can -receive any of the below as a reply. In the case of the @samp{C}, -@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned -when the target halts. In the below the exact meaning of @samp{signal -number} is poorly defined. In general one of the UNIX signal numbering -conventions is used. +@smallexample +@exdent Synopsis: +int system(const char *command); -@table @samp +@exdent Request: +Fsystem,commandptr/len -@item S@var{AA} -@var{AA} is the signal number +@exdent Return value: +The value returned is -1 on error and the return status +of the command otherwise. Only the exit status of the +command is returned, which is extracted from the hosts +system return value by calling WEXITSTATUS(retval). +In case /bin/sh could not be executed, 127 is returned. -@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} -@cindex @code{T} packet reply +@exdent Errors: +@end smallexample -@var{AA} = two hex digit signal number; @var{n...} = register number -(hex), @var{r...} = target byte ordered register contents, size defined -by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} = -thread process ID, this is a hex integer; @var{n...} = (@samp{watch} | -@samp{rwatch} | @samp{awatch}, @var{r...} = data address, this is a hex -integer; @var{n...} = other string not starting with valid hex digit. -@value{GDBN} should ignore this @var{n...}, @var{r...} pair and go on -to the next. This way we can extend the protocol. +@table @code +@item EINTR +The call was interrupted by the user. +@end table -@item W@var{AA} +@node Protocol specific representation of datatypes +@subsection Protocol specific representation of datatypes +@cindex protocol specific representation of datatypes, in file-i/o protocol -The process exited, and @var{AA} is the exit status. This is only -applicable to certain targets. +@menu +* Integral datatypes:: +* Pointer values:: +* struct stat:: +* struct timeval:: +@end menu -@item X@var{AA} +@node Integral datatypes +@unnumberedsubsubsec Integral datatypes +@cindex integral datatypes, in file-i/o protocol -The process terminated with signal @var{AA}. +The integral datatypes used in the system calls are -@item N@var{AA};@var{t@dots{}};@var{d@dots{}};@var{b@dots{}} @strong{(obsolete)} +@smallexample +int@r{,} unsigned int@r{,} long@r{,} unsigned long@r{,} mode_t @r{and} time_t +@end smallexample -@var{AA} = signal number; @var{t@dots{}} = address of symbol -@code{_start}; @var{d@dots{}} = base of data section; @var{b@dots{}} = -base of bss section. @emph{Note: only used by Cisco Systems targets. -The difference between this reply and the @samp{qOffsets} query is that -the @samp{N} packet may arrive spontaneously whereas the @samp{qOffsets} -is a query initiated by the host debugger.} +@code{Int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are +implemented as 32 bit values in this protocol. -@item O@var{XX@dots{}} +@code{Long} and @code{unsigned long} are implemented as 64 bit types. -@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at -any time while the program is running and the debugger should continue -to wait for @samp{W}, @samp{T}, etc. +@xref{Limits}, for corresponding MIN and MAX values (similar to those +in @file{limits.h}) to allow range checking on host and target. -@end table +@code{time_t} datatypes are defined as seconds since the Epoch. -@node General Query Packets -@section General Query Packets +All integral datatypes transferred as part of a memory read or write of a +structured datatype e.g.@: a @code{struct stat} have to be given in big endian +byte order. -The following set and query packets have already been defined. +@node Pointer values +@unnumberedsubsubsec Pointer values +@cindex pointer values, in file-i/o protocol -@table @r +Pointers to target data are transmitted as they are. An exception +is made for pointers to buffers for which the length isn't +transmitted as part of the function call, namely strings. Strings +are transmitted as a pointer/length pair, both as hex values, e.g.@: -@item @code{q}@code{C} --- current thread +@smallexample +@code{1aaf/12} +@end smallexample -Return the current thread id. +@noindent +which is a pointer to data of length 18 bytes at position 0x1aaf. +The length is defined as the full string length in bytes, including +the trailing null byte. Example: -Reply: -@table @samp -@item @code{QC}@var{pid} -Where @var{pid} is a HEX encoded 16 bit process id. -@item * -Any other reply implies the old pid. -@end table +@smallexample +``hello, world'' at address 0x123456 +@end smallexample -@item @code{q}@code{fThreadInfo} -- all thread ids +@noindent +is transmitted as -@code{q}@code{sThreadInfo} +@smallexample +@code{123456/d} +@end smallexample -Obtain a list of active thread ids from the target (OS). Since there -may be too many active threads to fit into one reply packet, this query -works iteratively: it may require more than one query/reply sequence to -obtain the entire list of threads. The first query of the sequence will -be the @code{qf}@code{ThreadInfo} query; subsequent queries in the -sequence will be the @code{qs}@code{ThreadInfo} query. +@node struct stat +@unnumberedsubsubsec struct stat +@cindex struct stat, in file-i/o protocol -NOTE: replaces the @code{qL} query (see below). +The buffer of type struct stat used by the target and @value{GDBN} is defined +as follows: -Reply: -@table @samp -@item @code{m}@var{id} -A single thread id -@item @code{m}@var{id},@var{id}@dots{} -a comma-separated list of thread ids -@item @code{l} -(lower case 'el') denotes end of list. -@end table +@smallexample +struct stat @{ + unsigned int st_dev; /* device */ + unsigned int st_ino; /* inode */ + mode_t st_mode; /* protection */ + unsigned int st_nlink; /* number of hard links */ + unsigned int st_uid; /* user ID of owner */ + unsigned int st_gid; /* group ID of owner */ + unsigned int st_rdev; /* device type (if inode device) */ + unsigned long st_size; /* total size, in bytes */ + unsigned long st_blksize; /* blocksize for filesystem I/O */ + unsigned long st_blocks; /* number of blocks allocated */ + time_t st_atime; /* time of last access */ + time_t st_mtime; /* time of last modification */ + time_t st_ctime; /* time of last change */ +@}; +@end smallexample -In response to each query, the target will reply with a list of one or -more thread ids, in big-endian hex, separated by commas. @value{GDBN} -will respond to each reply with a request for more thread ids (using the -@code{qs} form of the query), until the target responds with @code{l} -(lower-case el, for @code{'last'}). +The integral datatypes are conforming to the definitions given in the +approriate section (see @ref{Integral datatypes}, for details) so this +structure is of size 64 bytes. -@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info +The values of several fields have a restricted meaning and/or +range of values. -Where @var{id} is a thread-id in big-endian hex. Obtain a printable -string description of a thread's attributes from the target OS. This -string may contain anything that the target OS thinks is interesting for -@value{GDBN} to tell the user about the thread. The string is displayed -in @value{GDBN}'s @samp{info threads} display. Some examples of -possible thread extra info strings are ``Runnable'', or ``Blocked on -Mutex''. +@smallexample +st_dev: 0 file + 1 console -Reply: -@table @samp -@item @var{XX@dots{}} -Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising -the printable string containing the extra information about the thread's -attributes. -@end table +st_ino: No valid meaning for the target. Transmitted unchanged. -@item @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} --- query @var{LIST} or @var{threadLIST} @strong{(deprecated)} +st_mode: Valid mode bits are described in Appendix C. Any other + bits have currently no meaning for the target. -Obtain thread information from RTOS. Where: @var{startflag} (one hex -digit) is one to indicate the first query and zero to indicate a -subsequent query; @var{threadcount} (two hex digits) is the maximum -number of threads the response packet can contain; and @var{nextthread} -(eight hex digits), for subsequent queries (@var{startflag} is zero), is -returned in the response as @var{argthread}. +st_uid: No valid meaning for the target. Transmitted unchanged. -NOTE: this query is replaced by the @code{q}@code{fThreadInfo} query -(see above). +st_gid: No valid meaning for the target. Transmitted unchanged. -Reply: -@table @samp -@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}} -Where: @var{count} (two hex digits) is the number of threads being -returned; @var{done} (one hex digit) is zero to indicate more threads -and one indicates no further threads; @var{argthreadid} (eight hex -digits) is @var{nextthread} from the request packet; @var{thread@dots{}} -is a sequence of thread IDs from the target. @var{threadid} (eight hex -digits). See @code{remote.c:parse_threadlist_response()}. -@end table +st_rdev: No valid meaning for the target. Transmitted unchanged. -@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block +st_atime, st_mtime, st_ctime: + These values have a host and file system dependent + accuracy. Especially on Windows hosts the file systems + don't support exact timing values. +@end smallexample -Reply: -@table @samp -@item @code{E}@var{NN} -An error (such as memory fault) -@item @code{C}@var{CRC32} -A 32 bit cyclic redundancy check of the specified memory region. -@end table +The target gets a struct stat of the above representation and is +responsible to coerce it to the target representation before +continuing. -@item @code{q}@code{Offsets} --- query sect offs +Note that due to size differences between the host and target +representation of stat members, these members could eventually +get truncated on the target. -Get section offsets that the target used when re-locating the downloaded -image. @emph{Note: while a @code{Bss} offset is included in the -response, @value{GDBN} ignores this and instead applies the @code{Data} -offset to the @code{Bss} section.} +@node struct timeval +@unnumberedsubsubsec struct timeval +@cindex struct timeval, in file-i/o protocol -Reply: -@table @samp -@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} -@end table +The buffer of type struct timeval used by the target and @value{GDBN} +is defined as follows: -@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request +@smallexample +struct timeval @{ + time_t tv_sec; /* second */ + long tv_usec; /* microsecond */ +@}; +@end smallexample -Returns information on @var{threadid}. Where: @var{mode} is a hex -encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. +The integral datatypes are conforming to the definitions given in the +approriate section (see @ref{Integral datatypes}, for details) so this +structure is of size 8 bytes. -Reply: -@table @samp -@item * -@end table +@node Constants +@subsection Constants +@cindex constants, in file-i/o protocol -See @code{remote.c:remote_unpack_thread_info_response()}. +The following values are used for the constants inside of the +protocol. @value{GDBN} and target are resposible to translate these +values before and after the call as needed. -@item @code{q}@code{Rcmd,}@var{command} --- remote command +@menu +* Open flags:: +* mode_t values:: +* Errno values:: +* Lseek flags:: +* Limits:: +@end menu -@var{command} (hex encoded) is passed to the local interpreter for -execution. Invalid commands should be reported using the output string. -Before the final result packet, the target may also respond with a -number of intermediate @code{O}@var{output} console output packets. -@emph{Implementors should note that providing access to a stubs's -interpreter may have security implications}. +@node Open flags +@unnumberedsubsubsec Open flags +@cindex open flags, in file-i/o protocol -Reply: -@table @samp -@item OK -A command response with no output. -@item @var{OUTPUT} -A command response with the hex encoded output string @var{OUTPUT}. -@item @code{E}@var{NN} -Indicate a badly formed request. -@item @samp{} -When @samp{q}@samp{Rcmd} is not recognized. -@end table +All values are given in hexadecimal representation. -@item @code{qSymbol::} --- symbol lookup +@smallexample + O_RDONLY 0x0 + O_WRONLY 0x1 + O_RDWR 0x2 + O_APPEND 0x8 + O_CREAT 0x200 + O_TRUNC 0x400 + O_EXCL 0x800 +@end smallexample -Notify the target that @value{GDBN} is prepared to serve symbol lookup -requests. Accept requests from the target for the values of symbols. +@node mode_t values +@unnumberedsubsubsec mode_t values +@cindex mode_t values, in file-i/o protocol -Reply: -@table @samp -@item @code{OK} -The target does not need to look up any (more) symbols. -@item @code{qSymbol:}@var{sym_name} -The target requests the value of symbol @var{sym_name} (hex encoded). -@value{GDBN} may provide the value by using the -@code{qSymbol:}@var{sym_value}:@var{sym_name} message, described below. -@end table +All values are given in octal representation. -@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value +@smallexample + S_IFREG 0100000 + S_IFDIR 040000 + S_IRUSR 0400 + S_IWUSR 0200 + S_IXUSR 0100 + S_IRGRP 040 + S_IWGRP 020 + S_IXGRP 010 + S_IROTH 04 + S_IWOTH 02 + S_IXOTH 01 +@end smallexample -Set the value of @var{sym_name} to @var{sym_value}. +@node Errno values +@unnumberedsubsubsec Errno values +@cindex errno values, in file-i/o protocol -@var{sym_name} (hex encoded) is the name of a symbol whose value the -target has previously requested. +All values are given in decimal representation. -@var{sym_value} (hex) is the value for symbol @var{sym_name}. If -@value{GDBN} cannot supply a value for @var{sym_name}, then this field -will be empty. +@smallexample + EPERM 1 + ENOENT 2 + EINTR 4 + EBADF 9 + EACCES 13 + EFAULT 14 + EBUSY 16 + EEXIST 17 + ENODEV 19 + ENOTDIR 20 + EISDIR 21 + EINVAL 22 + ENFILE 23 + EMFILE 24 + EFBIG 27 + ENOSPC 28 + ESPIPE 29 + EROFS 30 + ENAMETOOLONG 91 + EUNKNOWN 9999 +@end smallexample -Reply: -@table @samp -@item @code{OK} -The target does not need to look up any (more) symbols. -@item @code{qSymbol:}@var{sym_name} -The target requests the value of a new symbol @var{sym_name} (hex -encoded). @value{GDBN} will continue to supply the values of symbols -(if available), until the target ceases to request them. -@end table + EUNKNOWN is used as a fallback error value if a host system returns + any error value not in the list of supported error numbers. -@end table +@node Lseek flags +@unnumberedsubsubsec Lseek flags +@cindex lseek flags, in file-i/o protocol -@node Register Packet Format -@section Register Packet Format +@smallexample + SEEK_SET 0 + SEEK_CUR 1 + SEEK_END 2 +@end smallexample -The following @samp{g}/@samp{G} packets have previously been defined. -In the below, some thirty-two bit registers are transferred as -sixty-four bits. Those registers should be zero/sign extended (which?) -to fill the space allocated. Register bytes are transfered in target -byte order. The two nibbles within a register byte are transfered -most-significant - least-significant. +@node Limits +@unnumberedsubsubsec Limits +@cindex limits, in file-i/o protocol -@table @r +All values are given in decimal representation. -@item MIPS32 +@smallexample + INT_MIN -2147483648 + INT_MAX 2147483647 + UINT_MAX 4294967295 + LONG_MIN -9223372036854775808 + LONG_MAX 9223372036854775807 + ULONG_MAX 18446744073709551615 +@end smallexample -All registers are transfered as thirty-two bit quantities in the order: -32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point -registers; fsr; fir; fp. +@node File-I/O Examples +@subsection File-I/O Examples +@cindex file-i/o examples -@item MIPS64 +Example sequence of a write call, file descriptor 3, buffer is at target +address 0x1234, 6 bytes should be written: -All registers are transfered as sixty-four bit quantities (including -thirty-two bit registers such as @code{sr}). The ordering is the same -as @code{MIPS32}. +@smallexample +<- @code{Fwrite,3,1234,6} +@emph{request memory read from target} +-> @code{m1234,6} +<- XXXXXX +@emph{return "6 bytes written"} +-> @code{F6} +@end smallexample -@end table +Example sequence of a read call, file descriptor 3, buffer is at target +address 0x1234, 6 bytes should be read: -@node Examples -@section Examples +@smallexample +<- @code{Fread,3,1234,6} +@emph{request memory write to target} +-> @code{X1234,6:XXXXXX} +@emph{return "6 bytes read"} +-> @code{F6} +@end smallexample -Example sequence of a target being re-started. Notice how the restart -does not get any direct output: +Example sequence of a read call, call fails on the host due to invalid +file descriptor (EBADF): @smallexample --> @code{R00} -<- @code{+} -@emph{target restarts} --> @code{?} -<- @code{+} -<- @code{T001:1234123412341234} --> @code{+} +<- @code{Fread,3,1234,6} +-> @code{F-1,9} @end smallexample -Example sequence of a target being stepped by a single instruction: +Example sequence of a read call, user presses Ctrl-C before syscall on +host is called: @smallexample --> @code{G1445@dots{}} -<- @code{+} --> @code{s} -<- @code{+} -@emph{time passes} -<- @code{T001:1234123412341234} --> @code{+} --> @code{g} -<- @code{+} -<- @code{1455@dots{}} --> @code{+} +<- @code{Fread,3,1234,6} +-> @code{F-1,4,C} +<- @code{T02} +@end smallexample + +Example sequence of a read call, user presses Ctrl-C after syscall on +host is called: + +@smallexample +<- @code{Fread,3,1234,6} +-> @code{X1234,6:XXXXXX} +<- @code{T02} @end smallexample +@include agentexpr.texi + @include gpl.texi +@raisesections @include fdl.texi +@lowersections @node Index @unnumbered Index