\input texinfo @c -*-texinfo-*-
@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004, 2005
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
@c Free Software Foundation, Inc.
@c
@c %**start of header
Version @value{GDBVN}.
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
- 1999, 2000, 2001, 2002, 2003, 2004, 2005@*
+ 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006@*
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@vskip 0pt plus 1filll
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
-1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
+1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006
Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
This is the @value{EDITION} Edition, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-2005 Free Software Foundation, Inc.
+Copyright (C) 1988-2006 Free Software Foundation, Inc.
@menu
* Summary:: Summary of @value{GDBN}
Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped
with the migration of old architectures to this new framework.
+Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s
+unwinder framework, this consisting of a fresh new design featuring
+frame IDs, independent frame sniffers, and the sentinel frame. Mark
+Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
+libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
+trad unwinders. The architecture specific changes, each involving a
+complete rewrite of the architecture's frame code, were carried out by
+Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
+Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
+Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
+Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
+Weigand.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
To quit debugging one of the forked processes, you can either detach
from it by using the @w{@code{detach-fork}} command (allowing it to
run independently), or delete (and kill) it using the
-@w{@code{delete-fork}} command.
+@w{@code{delete fork}} command.
@table @code
@kindex detach-fork @var{fork-id}
@var{fork-id}, and remove it from the fork list. The process will be
allowed to run independently.
-@kindex delete-fork @var{fork-id}
-@item delete-fork @var{fork-id}
+@kindex delete fork @var{fork-id}
+@item delete fork @var{fork-id}
Kill the process identified by @value{GDBN} fork number @var{fork-id},
and remove it from the fork list.
only restores things that reside in the program being debugged, not in
the debugger.
-@kindex delete-checkpoint @var{checkpoint-id}
-@item delete-checkpoint @var{checkpoint-id}
+@kindex delete checkpoint @var{checkpoint-id}
+@item delete checkpoint @var{checkpoint-id}
Delete the previously-saved checkpoint identified by @var{checkpoint-id}.
@end table
that---@file{/mnt/cross/foo.c}.
Note that the executable search path is @emph{not} used to locate the
-source files. Neither is the current working directory, unless it
-happens to be in the source path.
+source files.
Whenever you reset or rearrange the source path, @value{GDBN} clears out
any information it has cached about where source files are found and where
directory at the time you add an entry to the source path.
@item directory
-Reset the source path to empty again. This requires confirmation.
+Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation.
@c RET-repeat for @code{directory} is explicitly disabled, but since
@c repeating it would be a no-op we do not say that. (thanks to RMS)
@enumerate
@item
-Use @code{directory} with no argument to reset the source path to empty.
+Use @code{directory} with no argument to reset the source path to its default value.
@item
Use @code{directory} with suitable arguments to reinstall the
* M2 Operators:: Built-in operators
* Built-In Func/Proc:: Built-in functions and procedures
* M2 Constants:: Modula-2 constants
+* M2 Types:: Modula-2 types
* M2 Defaults:: Default settings for Modula-2
* Deviations:: Deviations from standard Modula-2
* M2 Checks:: Modula-2 type and range checks
@end table
@quotation
-@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN}
+@emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN}
treats the use of the operator @code{IN}, or the use of operators
@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
@code{<=}, and @code{>=} on sets as an error.
Set constants are not yet supported.
@end itemize
+@node M2 Types
+@subsubsection Modula-2 Types
+@cindex Modula-2 types
+
+Currently @value{GDBN} can print the following data types in Modula-2
+syntax: array types, record types, set types, pointer types, procedure
+types, enumerated types, subrange types and base types. You can also
+print the contents of variables declared using these type.
+This section gives a number of simple source code examples together with
+sample @value{GDBN} sessions.
+
+The first example contains the following section of code:
+
+@smallexample
+VAR
+ s: SET OF CHAR ;
+ r: [20..40] ;
+@end smallexample
+
+@noindent
+and you can request @value{GDBN} to interrogate the type and value of
+@code{r} and @code{s}.
+
+@smallexample
+(@value{GDBP}) print s
+@{'A'..'C', 'Z'@}
+(@value{GDBP}) ptype s
+SET OF CHAR
+(@value{GDBP}) print r
+21
+(@value{GDBP}) ptype r
+[20..40]
+@end smallexample
+
+@noindent
+Likewise if your source code declares @code{s} as:
+
+@smallexample
+VAR
+ s: SET ['A'..'Z'] ;
+@end smallexample
+
+@noindent
+then you may query the type of @code{s} by:
+
+@smallexample
+(@value{GDBP}) ptype s
+type = SET ['A'..'Z']
+@end smallexample
+
+@noindent
+Note that at present you cannot interactively manipulate set
+expressions using the debugger.
+
+The following example shows how you might declare an array in Modula-2
+and how you can interact with @value{GDBN} to print its type and contents:
+
+@smallexample
+VAR
+ s: ARRAY [-10..10] OF CHAR ;
+@end smallexample
+
+@smallexample
+(@value{GDBP}) ptype s
+ARRAY [-10..10] OF CHAR
+@end smallexample
+
+Note that the array handling is not yet complete and although the type
+is printed correctly, expression handling still assumes that all
+arrays have a lower bound of zero and not @code{-10} as in the example
+above. Unbounded arrays are also not yet recognized in @value{GDBN}.
+
+Here are some more type related Modula-2 examples:
+
+@smallexample
+TYPE
+ colour = (blue, red, yellow, green) ;
+ t = [blue..yellow] ;
+VAR
+ s: t ;
+BEGIN
+ s := blue ;
+@end smallexample
+
+@noindent
+The @value{GDBN} interaction shows how you can query the data type
+and value of a variable.
+
+@smallexample
+(@value{GDBP}) print s
+$1 = blue
+(@value{GDBP}) ptype t
+type = [blue..yellow]
+@end smallexample
+
+@noindent
+In this example a Modula-2 array is declared and its contents
+displayed. Observe that the contents are written in the same way as
+their @code{C} counterparts.
+
+@smallexample
+VAR
+ s: ARRAY [1..5] OF CARDINAL ;
+BEGIN
+ s[1] := 1 ;
+@end smallexample
+
+@smallexample
+(@value{GDBP}) print s
+$1 = @{1, 0, 0, 0, 0@}
+(@value{GDBP}) ptype s
+type = ARRAY [1..5] OF CARDINAL
+@end smallexample
+
+The Modula-2 language interface to @value{GDBN} also understands
+pointer types as shown in this example:
+
+@smallexample
+VAR
+ s: POINTER TO ARRAY [1..5] OF CARDINAL ;
+BEGIN
+ NEW(s) ;
+ s^[1] := 1 ;
+@end smallexample
+
+@noindent
+and you can request that @value{GDBN} describes the type of @code{s}.
+
+@smallexample
+(@value{GDBP}) ptype s
+type = POINTER TO ARRAY [1..5] OF CARDINAL
+@end smallexample
+
+@value{GDBN} handles compound types as we can see in this example.
+Here we combine array types, record types, pointer types and subrange
+types:
+
+@smallexample
+TYPE
+ foo = RECORD
+ f1: CARDINAL ;
+ f2: CHAR ;
+ f3: myarray ;
+ END ;
+
+ myarray = ARRAY myrange OF CARDINAL ;
+ myrange = [-2..2] ;
+VAR
+ s: POINTER TO ARRAY myrange OF foo ;
+@end smallexample
+
+@noindent
+and you can ask @value{GDBN} to describe the type of @code{s} as shown
+below.
+
+@smallexample
+(@value{GDBP}) ptype s
+type = POINTER TO ARRAY [-2..2] OF foo = RECORD
+ f1 : CARDINAL;
+ f2 : CHAR;
+ f3 : ARRAY [-2..2] OF CARDINAL;
+END
+@end smallexample
+
@node M2 Defaults
@subsubsection Modula-2 defaults
@cindex Modula-2 defaults
@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
can silently drop packets on busy or unreliable networks, which will
cause havoc with your debugging session.
+@item target remote | @var{command}
+@cindex pipe, @code{target remote} to
+Run @var{command} in the background and communicate with it using a
+pipe. The @var{command} is a shell command, to be parsed and expanded
+by the system's command shell, @code{/bin/sh}; it should expect remote
+protocol packets on its standard input, and send replies on its
+standard output. You could use this to run a stand-alone simulator
+that speaks the remote debugging protocol, to make net connections
+using programs like @code{ssh}, or for other similar tricks.
+
+If @var{command} closes its standard output (perhaps by exiting),
+@value{GDBN} will try to send it a @code{SIGTERM} signal. (If the
+program has already exited, this will have no effect.)
+
@end table
Once the connection has been established, you can use all the usual
@end table
-@node NetWare
-@section Using the @code{gdbserve.nlm} program
-
-@kindex gdbserve.nlm
-@code{gdbserve.nlm} is a control program for NetWare systems, which
-allows you to connect your program with a remote @value{GDBN} via
-@code{target remote}.
-
-@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
-using the standard @value{GDBN} remote serial protocol.
-
-@table @emph
-@item On the target machine,
-you need to have a copy of the program you want to debug.
-@code{gdbserve.nlm} does not need your program's symbol table, so you
-can strip the program if necessary to save space. @value{GDBN} on the
-host system does all the symbol handling.
-
-To use the server, you must tell it how to communicate with
-@value{GDBN}; the name of your program; and the arguments for your
-program. The syntax is:
-
-@smallexample
-load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
- [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
-@end smallexample
-
-@var{board} and @var{port} specify the serial line; @var{baud} specifies
-the baud rate used by the connection. @var{port} and @var{node} default
-to 0, @var{baud} defaults to 9600@dmn{bps}.
-
-For example, to debug Emacs with the argument @samp{foo.txt}and
-communicate with @value{GDBN} over serial port number 2 or board 1
-using a 19200@dmn{bps} connection:
-
-@smallexample
-load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
-@end smallexample
-
-@item
-On the @value{GDBN} host machine, connect to your target (@pxref{Connecting,,
-Connecting to a remote target}).
-
-@end table
-
@node Remote configuration
@section Remote configuration
Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
interrupt the remote program.
-@item set remotedebug
-@cindex debug remote protocol
-@cindex remote protocol debugging
-@cindex display remote packets
-Control the debugging of the remote protocol. When enabled, each
-packet sent to or received from the remote target is displayed. The
-defaults is off.
-
-@item show remotedebug
-Show the current setting of the remote protocol debugging.
-
@item set remotedevice @var{device}
@cindex serial port name
Set the name of the serial port through which to communicate to the
This command loads symbols from a dll similarly to
add-sym command but without the need to specify a base address.
+@kindex set cygwin-exceptions
+@cindex debugging the Cygwin DLL
+@cindex Cygwin DLL, debugging
+@item set cygwin-exceptions @var{mode}
+If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that
+happen inside the Cygwin DLL. If @var{mode} is @code{off},
+@value{GDBN} will delay recognition of exceptions, and may ignore some
+exceptions which seem to be caused by internal Cygwin DLL
+``bookkeeping''. This option is meant primarily for debugging the
+Cygwin DLL itself; the default value is @code{off} to avoid annoying
+@value{GDBN} users with false @code{SIGSEGV} signals.
+
+@kindex show cygwin-exceptions
+@item show cygwin-exceptions
+Displays whether @value{GDBN} will break on exceptions that happen
+inside the Cygwin DLL itself.
+
@kindex set new-console
@item set new-console @var{mode}
If @var{mode} is @code{on} the debuggee will
debugging info.
@cindex packets, reporting on stdout
@cindex serial connections, debugging
+@cindex debug remote protocol
+@cindex remote protocol debugging
+@cindex display remote packets
@item set debug remote
Turns on or off display of reports on all packets sent back and forth across
the serial line to the remote machine. The info is printed on the
in the form of a reference manual.
Note that @sc{gdb/mi} is still under construction, so some of the
-features described below are incomplete and subject to change.
+features described below are incomplete and subject to change
+(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}).
@unnumberedsec Notation and Terminology
@menu
* GDB/MI Command Syntax::
* GDB/MI Compatibility with CLI::
+* GDB/MI Development and Front Ends::
* GDB/MI Output Records::
* GDB/MI Command Description Format::
* GDB/MI Breakpoint Table Commands::
behaviour, the exact output of such commands is likely to end up being
an un-supported hybrid of @sc{gdb/mi} and CLI output.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Development and Front Ends
+@section @sc{gdb/mi} Development and Front Ends
+@cindex @sc{gdb/mi} development
+
+The application which takes the MI output and presents the state of the
+program being debugged to the user is called a @dfn{front end}.
+
+Although @sc{gdb/mi} is still incomplete, it is currently being used
+by a variety of front ends to @value{GDBN}. This makes it difficult
+to introduce new functionality without breaking existing usage. This
+section tries to minimize the problems by describing how the protocol
+might change.
+
+Some changes in MI need not break a carefully designed front end, and
+for these the MI version will remain unchanged. The following is a
+list of changes that may occur within one level, so front ends should
+parse MI output in a way that can handle them:
+
+@itemize @bullet
+@item
+New MI commands may be added.
+
+@item
+New fields may be added to the output of any MI command.
+
+@c The format of field's content e.g type prefix, may change so parse it
+@c at your own risk. Yes, in general?
+
+@c The order of fields may change? Shouldn't really matter but it might
+@c resolve inconsistencies.
+@end itemize
+
+If the changes are likely to break front ends, the MI version level
+will be increased by one. This will allow the front end to parse the
+output according to the MI version. Apart from mi0, new versions of
+@value{GDBN} will not support old versions of MI and it will be the
+responsibility of the front end to work with the new one.
+
+@c Starting with mi3, add a new command -mi-version that prints the MI
+@c version?
+
+The best way to avoid unexpected changes in MI that might break your front
+end is to make your project known to @value{GDBN} developers and
+follow development on @email{gdb@@sources.redhat.com} and
+@email{gdb-patches@@sources.redhat.com}. There is also the mailing list
+@email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
+Group, which has the aim of creating a a more general MI protocol
+called Debugger Machine Interface (DMI) that will become a standard
+for all debuggers, not just @value{GDBN}.
+@cindex mailing lists
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Output Records
@section @sc{gdb/mi} Output Records
@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 rluser.texi
@include inc-hist.texinfo
The error response returned for some packets includes a two character
error number. That number is not well defined.
+@cindex empty response, for unsupported packets
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
Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
(@pxref{insert breakpoint or watchpoint packet}).
-@item c @var{addr}
+@item c @r{[}@var{addr}@r{]}
@cindex @samp{c} packet
Continue. @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 C @var{sig};@var{addr}
+@item C @var{sig}@r{[};@var{addr}@r{]}
@cindex @samp{C} packet
Continue with signal @var{sig} (hex signal number). If
@samp{;@var{addr}} is omitted, resume at same address.
The @samp{R} packet has no reply.
-@item s @var{addr}
+@item s @r{[}@var{addr}@r{]}
@cindex @samp{s} packet
Single step. @var{addr} is the address at which to resume. If
@var{addr} is omitted, resume at same address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item S @var{sig};@var{addr}
+@item S @var{sig}@r{[};@var{addr}@r{]}
@anchor{step with signal packet}
@cindex @samp{S} packet
Step with signal. This is analogous to the @samp{C} packet, but
foos) or @samp{Qacme.bar} (for setting bars).
@end itemize
-A query or set packet may optionally be followed by a @samp{,} or
-@samp{;} separated list. Stubs must be careful to match the full
-packet name, in case packet names have common prefixes.
+The name of a query or set packet should be separated from any
+parameters by a @samp{:}; the parameters themselves should be
+separated by @samp{,} or @samp{;}. Stubs must be careful to match the
+full packet name, and check for a separator or the end of the packet,
+in case two packet names share a common prefix. New packets should not begin
+with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL}
+packets predate these conventions, and have arguments without any terminator
+for the packet name; we suspect they are in widespread use in places that
+are difficult to upgrade. The @samp{qC} packet has no arguments, but some
+existing stubs (e.g.@: RedBoot) are known to not check for the end of the
+packet.}.
Like the descriptions of the other packets, each description here
has a template showing the packet's overall syntax, followed by an
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.
+Don't use this packet; use the @samp{qThreadExtraInfo} query instead
+(see below).
+
Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
@item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length}
encoding of @var{annex} is specific to the object; it can supply
additional details about what data to access.
+Since this packet is ambiguous with the older @code{qP} packet, we
+plan to rename it.
+
Here are the specific requests of this form defined so far. All
@samp{qPart:@var{object}:read:@dots{}} requests use the same reply
formats, listed below.
An empty reply indicates that @samp{qRcmd} is not recognized.
@end table
+(Note that the @code{qRcmd} packet's name is separated from the
+command by a @samp{,}, not a @samp{:}, contrary to the naming
+conventions above. Please don't use this packet as a model for new
+packets.)
+
@item qSymbol::
@cindex symbol lookup, remote request
@cindex @samp{qSymbol} packet
the thread's attributes.
@end table
+(Note that the @code{qThreadExtraInfo} packet's name is separated from
+the command by a @samp{,}, not a @samp{:}, contrary to the naming
+conventions above. Please don't use this packet as a model for new
+packets.)
+
@item QTStart
@itemx QTStop
@itemx QTinit
projects / deliverable / binutils-gdb.git / blobdiff