@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
-section entitled ``GNU General Public License'' is included exactly as
-in the original, and provided that the entire resulting derived work is
-distributed under the terms of a permission notice identical to this
-one.
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the section entitled ``GNU General Public License'' may be
-included in a translation approved by the Free Software Foundation
-instead of in the original English.
+into another language, under the above conditions for modified versions.
@end ifinfo
@titlepage
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
-section entitled ``GNU General Public License'' is included exactly as
-in the original, and provided that the entire resulting derived work is
-distributed under the terms of a permission notice identical to this
-one.
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the section entitled ``GNU General Public License'' may be
-included in a translation approved by the Free Software Foundation
-instead of in the original English.
+into another language, under the above conditions for modified versions.
@end titlepage
@page
* Formatting Documentation:: How to format and print GDB documentation
* Installing GDB:: Installing GDB
@end ifclear
-@ifclear AGGLOMERATION
-* Copying:: GNU GENERAL PUBLIC LICENSE
-@end ifclear
* Index:: Index
@end menu
you have these freedoms and that you cannot take these freedoms away
from anyone else.
-@ifclear AGGLOMERATION
-For full details, @pxref{Copying, ,GNU GENERAL PUBLIC LICENSE}.
-@end ifclear
-
@node Contributors
@unnumberedsec Contributors to GDB
@end quotation
So that they may not regard their long labor as thankless, we
-particularly thank those who shepherded GDB through major releases: Stu
-Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, 4.4), John Gilmore
-(releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon (releases 3.5, 3.4,
-3.3); and Randy Smith (releases 3.2, 3.1, 3.0). As major maintainer of
-GDB for some period, each contributed significantly to the structure,
-stability, and capabilities of the entire debugger.
+particularly thank those who shepherded GDB through major releases: Fred
+Fish (release 4.9), Stu Grossman and John Gilmore (releases 4.8, 4.7,
+4.6, 4.5, 4.4), John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim
+Kingdon (releases 3.5, 3.4, 3.3); and Randy Smith (releases 3.2, 3.1,
+3.0). As major maintainer of GDB for some period, each contributed
+significantly to the structure, stability, and capabilities of the
+entire debugger.
Richard Stallman, assisted at various times by Pete TerMaat, Chris
Hanson, and Richard Mlynarik, handled releases through 2.8.
to make the output more readable.
@item Object Code Formats
-GDB uses a new library called the Binary File Descriptor (BFD)
-Library to permit it to switch dynamically, without reconfiguration or
+GDB uses a new library called the Binary File Descriptor (BFD) Library
+to permit it to switch dynamically, without reconfiguration or
recompilation, between different object-file formats. Formats currently
-supported are COFF, a.out, and the Intel 960 b.out; files may be read as
-.o files, archive libraries, or core dumps. BFD is available as a
-subroutine library so that other programs may take advantage of it, and
-the other GNU binary utilities are being converted to use it.
+supported are COFF, ELF, a.out, Intel 960 b.out, MIPS ECOFF, HPPA SOM
+(with stabs debugging), and S-records; files may be read as .o files,
+archive libraries, or core dumps. BFD is available as a subroutine
+library so that other programs may take advantage of it, and the other
+GNU binary utilities are being converted to use it.
@item Configuration and Ports
Compile-time configuration (to select a particular architecture and
@item Reference Card
GDB 4 has a reference card. @xref{Formatting Documentation,,Formatting
the Documentation}, for instructions about how to print it.
-
-@item Work in Progress
-Kernel debugging for BSD and Mach systems; Tahoe and HPPA architecture
-support.
@end table
@end ifset
@item -core=@var{file}
@itemx -c @var{file}
Use file @var{file} as a core dump to examine.
+
+@item -c @var{number}
+Connect to process ID @var{number}, as with the @code{attach} command
+(unless there is a file in core-dump format named @var{number}, in which
+case @samp{-c} specifies that file as a core dump to read).
@end ifclear
@item -command=@var{file}
@table @code
@item -nx
@itemx -n
-Do not execute commands from any @file{@value{GDBINIT}} initialization files.
-Normally, the commands in these files are executed after all the
-command options and arguments have been processed.
-@xref{Command Files,,Command files}.
+Do not execute commands from any initialization files (normally called
+@file{@value{GDBINIT}}). Normally, the commands in these files are
+executed after all the command options and arguments have been
+processed. @xref{Command Files,,Command files}.
@item -quiet
@itemx -q
messages are also suppressed in batch mode.
@item -batch
-Run in batch mode. Exit with status @code{0} after processing all the command
-files specified with @samp{-x} (and @file{@value{GDBINIT}}, if not inhibited).
-Exit with nonzero status if an error occurs in executing the @value{GDBN}
-commands in the command files.
+Run in batch mode. Exit with status @code{0} after processing all the
+command files specified with @samp{-x} (and all commands from
+initialization files, if not inhibited with @samp{-n}). Exit with
+nonzero status if an error occurs in executing the @value{GDBN} commands
+in the command files.
Batch mode may be useful for running @value{GDBN} as a filter, for example to
download and run a program on another computer; in order to make this
use at your site, you may occasionally want to determine which version
of @value{GDBN} you are running; as @value{GDBN} evolves, new commands are introduced,
and old ones may wither away. The version number is also announced
-when you start @value{GDBN} with no arguments.
+when you start @value{GDBN}.
@kindex show copying
@item show copying
@code{ar} dated more recently than August 1989.
@end ignore
+@need 2000
@node Starting
@section Starting your program
@cindex starting
the front, so it will be searched sooner.
You can use the string @samp{$cwd} to refer to whatever is the current
-working directory at the time @value{GDBN} searches the path. If you use
-@samp{.} instead, it refers to the directory where you executed the
-@code{path} command. @value{GDBN} fills in the current path where needed in
-the @var{directory} argument, before adding it to the search path.
+working directory at the time @value{GDBN} searches the path. If you
+use @samp{.} instead, it refers to the directory where you executed the
+@code{path} command. @value{GDBN} replaces @samp{.} in the
+@var{directory} argument (with the current path) before adding
+@var{directory} to the search path.
@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
@c document that, since repeating it would be a no-op.
executing the command.
@end table
-To use @code{attach}, you must be debugging in an environment which
-supports processes. You must also have permission to send the process a
-signal, and it must have the same effective user ID as the @value{GDBN}
-process.
+To use @code{attach}, your program must be running in an environment
+which supports processes; for example, @code{attach} does not work for
+programs on bare-board targets that lack an operating system. You must
+also have permission to send the process a signal.
When using @code{attach}, you should first use the @code{file} command
to specify the program running in the process and load its symbol table.
@end table
@noindent
-Breakpoint commands, if any, are listed after the line for the
-corresponding breakpoint.
+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.
@noindent
@code{info break} with a breakpoint
To make the breakpoint stop the next time it is reached, specify
a count of zero.
-@item continue @var{count}
-@itemx c @var{count}
-@itemx fg @var{count}
-@kindex continue @var{count}
-Continue execution of your program, setting the ignore count of the
-breakpoint where your program stopped to @var{count} minus one.
-Thus, your program will not stop at this breakpoint until the
-@var{count}'th time it is reached.
-
-An argument to this command is meaningful only when your program stopped
-due to a breakpoint. At other times, the argument to @code{continue} is
-ignored.
-
-The synonym @code{fg} is provided purely for convenience, and has
-exactly the same behavior as other forms of the command.
-@end table
+When you use @code{continue} to resume execution of your program from a
+breakpoint, you can specify an ignore count directly as an argument to
+@code{continue}, rather than using @code{ignore}. @xref{Continuing and
+Stepping,,Continuing and stepping}.
If a breakpoint has a positive ignore count and a condition, the condition
is not checked. Once the ignore count reaches zero, the condition will
as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
is decremented each time. @xref{Convenience Vars, ,Convenience
variables}.
+@end table
@node Break Commands
@subsection Breakpoint command lists
will see no sign that the breakpoint was reached. @code{silent} is
meaningful only at the beginning of a breakpoint command list.
-The commands @code{echo} and @code{output} that allow you to print
-precisely controlled output are often useful in silent breakpoints.
-@xref{Output, ,Commands for controlled output}.
+The commands @code{echo}, @code{output}, and @code{printf} allow you to
+print precisely controlled output, and are often useful in silent
+breakpoints. @xref{Output, ,Commands for controlled output}.
For example, here is how you could use breakpoint commands to print the
value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
break foo if x>0
commands
silent
-echo x is\040
-output x
-echo \n
+printf "x is %d\n",x
cont
end
@end example
We choose three particular definitions of that function name:
@c FIXME! This is likely to change to show arg type lists, at least
-@example
+@smallexample
(@value{GDBP}) b String::after
[0] cancel
[1] all
Breakpoint 2 at 0xb344: file String.cc, line 875.
Breakpoint 3 at 0xafcc: file String.cc, line 846.
Multiple breakpoints were set.
-Use the "delete" command to delete unwanted breakpoints.
+Use the "delete" command to delete unwanted
+ breakpoints.
(@value{GDBP})
-@end example
+@end smallexample
@end ifclear
@ifclear BARETARGET
@table @code
@item continue @r{[}@var{ignore-count}@r{]}
+@itemx c @r{[}@var{count}@r{]}
+@itemx fg @r{[}@var{count}@r{]}
@kindex continue
+@kindex c
+@kindex fg
Resume program execution, at the address where your program last stopped;
any breakpoints set at that address are bypassed. The optional argument
@var{ignore-count} allows you to specify a further number of times to
ignore a breakpoint at this location; its effect is like that of
@code{ignore} (@pxref{Conditions, ,Break conditions}).
+The argument @var{ignore-count} is meaningful only when your program
+stopped due to a breakpoint. At other times, the argument to
+@code{continue} is ignored.
+
+The synonyms @code{c} and @code{fg} are provided purely for convenience,
+and have exactly the same behavior as @code{continue}.
+@end table
+
To resume execution at a different place, you can use @code{return}
(@pxref{Returning, ,Returning from a function}) to go back to the
calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
different address}) to go to an arbitrary location in your program.
-@end table
A typical technique for using stepping is to set a breakpoint
@ifclear CONLY
@quotation
@emph{Warning:} If you use the @code{step} command while control is
within a function that was compiled without debugging information,
-execution will proceed until control reaches another function.
+execution proceeds until control reaches a function that does have
+debugging information.
@end quotation
@item step @var{count}
Do not print addresses when displaying their contents. For example,
this is the same stack frame displayed with @code{set print address off}:
-@example
+@smallexample
@group
(@value{GDBP}) set print addr off
(@value{GDBP}) f
#0 set_quotes (lq="<<", rq=">>") at input.c:530
530 if (lquote != def_lquote)
@end group
-@end example
+@end smallexample
You can use @samp{set print address off} to eliminate all machine
dependent displays from the @value{GDBN} interface. For example, with
Cause @value{GDBN} to print structures in an indented format with one member per
line, like this:
-@example
+@smallexample
@group
$1 = @{
next = 0x0,
meat = 0x54 "Pork"
@}
@end group
-@end example
+@end smallexample
@item set print pretty off
Cause @value{GDBN} to print structures in a compact format, like this:
@end table
@ifclear CONLY
+@need 1000
@noindent
These settings are of interest when debugging C++ programs:
files that @value{GDBN} has skimmed, but not yet read completely. Finally,
@samp{maint print msymbols} dumps just the minimal symbol information
required for each object file from which @value{GDBN} has read some symbols.
-The description of @code{symbol-file} explains how @value{GDBN} reads
-symbols; both @code{info source} and @code{symbol-file} are described in
-@ref{Files, ,Commands to specify files}.
+@xref{Files, ,Commands to specify files}, for a discussion of how
+@value{GDBN} reads symbols (in the description of @code{symbol-file}).
@end table
@node Altering
has been dynamically loaded (by some other means) into the program that
is running. @var{address} should be the memory address at which the
file has been loaded; @value{GDBN} cannot figure this out for itself.
+You can specify @var{address} as an expression.
The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command. You can use the
complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
messages}).
-The messages currently printed, and their meanings, are:
+The messages currently printed, and their meanings, include:
@table @code
@item inner block not inside outer block in @var{symbol}
If you specify a height of zero lines, @value{GDBN} will not pause during output
no matter how long the output is. This is useful if output is to a file
or to an editor buffer.
+
+Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
+from wrapping its output.
@end table
@node Numbers
@kindex set radix
@item set radix @var{base}
Set the default base for numeric input and display. Supported choices
-for @var{base} are decimal 2, 8, 10, 16. @var{base} must itself be
+for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
specified either unambiguously or using the current default radix; for
example, any of
@example
-set radix 1010
set radix 012
set radix 10.
set radix 0xa
@item printf @var{string}, @var{expressions}@dots{}
@kindex printf
Print the values of the @var{expressions} under the control of
-@var{string}. The @var{expressions} are separated by commas and may
-be either numbers or pointers. Their values are printed as specified
-by @var{string}, exactly as if your program were to execute
+@var{string}. The @var{expressions} are separated by commas and may be
+either numbers or pointers. Their values are printed as specified by
+@var{string}, exactly as if your program were to execute the C
+subroutine
@example
printf (@var{string}, @var{expressions}@dots{});
@noindent
where @var{host} is an identifier such as @samp{sun4} or
@samp{decstation}, that identifies the platform where GDB 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}
you tell it not to, with the @samp{--norecursion} option).
You can run the @code{configure} script from any of the
-subordinate directories in the GDB distribution, if you only want to
-configure that subdirectory; but be sure to specify a path to it.
+subordinate directories in the GDB distribution if you only want to
+configure that subdirectory, but be sure to specify a path to it.
For example, with version @value{GDBVN}, type the following to configure only
the @code{bfd} subdirectory:
@smallexample
% sh config.sub sun4
-sparc-sun-sunos411
+sparc-sun-sunos4.1.1
% sh config.sub sun3
-m68k-sun-sunos411
+m68k-sun-sunos4.1.1
% sh config.sub decstation
-mips-dec-ultrix42
+mips-dec-ultrix4.2
% sh config.sub hp300bsd
m68k-hp-bsd
% sh config.sub i386v
propagate configuration to subdirectories.
@item --rm
-Remove the configuration that the other arguments specify.
+@emph{Remove} files otherwise built during configuration.
@c This does not work (yet if ever). FIXME.
@c @item --parse=@var{lang} @dots{}
options that affect GDB or its supporting libraries.
@end ifclear
-@ifclear AGGLOMERATION
-@node Copying
-@unnumbered GNU GENERAL PUBLIC LICENSE
-@center Version 2, June 1991
-
-@display
-Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
-675 Mass Ave, Cambridge, MA 02139, USA
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@end display
-
-@unnumberedsec Preamble
-
- The licenses for most software are designed to take away your
-freedom to share and change it. By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software---to make sure the software is free for all its users. This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it. (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.) You can apply it to
-your programs, too.
-
- When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have. You must make sure that they, too, receive or can get the
-source code. And you must show them these terms so they know their
-rights.
-
- We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software. If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
- Finally, any free program is threatened constantly by software
-patents. We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary. To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
- The precise terms and conditions for copying, distribution and
-modification follow.
-
-@iftex
-@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-@end iftex
-@ifinfo
-@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-@end ifinfo
-
-@enumerate
-@item
-This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License. The ``Program'', below,
-refers to any such program or work, and a ``work based on the Program''
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language. (Hereinafter, translation is included without limitation in
-the term ``modification''.) Each licensee is addressed as ``you''.
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope. The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
-@item
-You may copy and distribute verbatim copies of the Program's
-source code as you receive it, in any medium, provided that you
-conspicuously and appropriately publish on each copy an appropriate
-copyright notice and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
-@item
-You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
-@enumerate a
-@item
-You must cause the modified files to carry prominent notices
-stating that you changed the files and the date of any change.
-
-@item
-You must cause any work that you distribute or publish, that in
-whole or in part contains or is derived from the Program or any
-part thereof, to be licensed as a whole at no charge to all third
-parties under the terms of this License.
-
-@item
-If the modified program normally reads commands interactively
-when run, you must cause it, when started running for such
-interactive use in the most ordinary way, to print or display an
-announcement including an appropriate copyright notice and a
-notice that there is no warranty (or else, saying that you provide
-a warranty) and that users may redistribute the program under
-these conditions, and telling the user how to view a copy of this
-License. (Exception: if the Program itself is interactive but
-does not normally print such an announcement, your work based on
-the Program is not required to print an announcement.)
-@end enumerate
-
-These requirements apply to the modified work as a whole. If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works. But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
-@item
-You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
-@enumerate a
-@item
-Accompany it with the complete corresponding machine-readable
-source code, which must be distributed under the terms of Sections
-1 and 2 above on a medium customarily used for software interchange; or,
-
-@item
-Accompany it with a written offer, valid for at least three
-years, to give any third party, for a charge no more than your
-cost of physically performing source distribution, a complete
-machine-readable copy of the corresponding source code, to be
-distributed under the terms of Sections 1 and 2 above on a medium
-customarily used for software interchange; or,
-
-@item
-Accompany it with the information you received as to the offer
-to distribute corresponding source code. (This alternative is
-allowed only for noncommercial distribution and only if you
-received the program in object code or executable form with such
-an offer, in accord with Subsection b above.)
-@end enumerate
-
-The source code for a work means the preferred form of the work for
-making modifications to it. For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable. However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
-@item
-You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License. Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-@item
-You are not required to accept this License, since you have not
-signed it. However, nothing else grants you permission to modify or
-distribute the Program or its derivative works. These actions are
-prohibited by law if you do not accept this License. Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
-@item
-Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions. You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
-@item
-If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License. If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all. For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices. Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
-@item
-If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded. In such case, this License incorporates
-the limitation as if written in the body of this License.
-
-@item
-The Free Software Foundation may publish revised and/or new versions
-of the General Public License from time to time. Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Program
-specifies a version number of this License which applies to it and ``any
-later version'', you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation. If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
-
-@item
-If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission. For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this. Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
-@iftex
-@heading NO WARRANTY
-@end iftex
-@ifinfo
-@center NO WARRANTY
-@end ifinfo
-
-@item
-BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
-FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
-OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
-TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
-PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
-REPAIR OR CORRECTION.
-
-@item
-IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
-TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
-YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
-PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
-@end enumerate
-
-@iftex
-@heading END OF TERMS AND CONDITIONS
-@end iftex
-@ifinfo
-@center END OF TERMS AND CONDITIONS
-@end ifinfo
-
-@page
-@unnumberedsec Applying These Terms to Your New Programs
-
- If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
- To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the ``copyright'' line and a pointer to where the full notice is found.
-
-@smallexample
-@var{one line to give the program's name and an idea of what it does.}
-Copyright (C) 19@var{yy} @var{name of author}
-
-This program is free software; you can redistribute it and/or
-modify it under the terms of the GNU General Public License
-as published by the Free Software Foundation; either version 2
-of the License, or (at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program; if not, write to the
-Free Software Foundation, Inc., 675 Mass Ave,
-Cambridge, MA 02139, USA.
-@end smallexample
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
-@smallexample
-Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
-Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
-type `show w'. This is free software, and you are welcome
-to redistribute it under certain conditions; type `show c'
-for details.
-@end smallexample
-
-The hypothetical commands @samp{show w} and @samp{show c} should show
-the appropriate parts of the General Public License. Of course, the
-commands you use may be called something other than @samp{show w} and
-@samp{show c}; they could even be mouse-clicks or menu items---whatever
-suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a ``copyright disclaimer'' for the program, if
-necessary. Here is a sample; alter the names:
-
-@example
-Yoyodyne, Inc., hereby disclaims all copyright
-interest in the program `Gnomovision'
-(which makes passes at compilers) written
-by James Hacker.
-
-@var{signature of Ty Coon}, 1 April 1989
-Ty Coon, President of Vice
-@end example
-
-This General Public License does not permit incorporating your program into
-proprietary programs. If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library. If this is what you want to do, use the GNU Library General
-Public License instead of this License.
-@end ifclear
-
@node Index
@unnumbered Index
way for @value{GDBN} to get control. For instance, if your target
machine has some sort of interrupt button, you won't need to call this;
pressing the interrupt button will transfer control to
-@code{handle_exception}---in efect, to @value{GDBN}. On some machines,
+@code{handle_exception}---in effect, to @value{GDBN}. On some machines,
simply receiving characters on the serial port may also trigger a trap;
again, in that situation, you don't need to call @code{breakpoint} from
your own program---simply running @samp{target remote} from the host
@item
For the 680x0 stub only, you need to provide a variable called
-exceptionHook. Normally you just use
+@code{exceptionHook}. Normally you just use
@example
void (*exceptionHook)() = 0;
@end example
-but if you, before calling @code{set_debug_traps}, set it to point to
-a function, that function will be called when the debugger continues
-from a trap (for example, bus error) which causes the debugger to be
-entered. It is passed one parameter---an @code{int} which is the
-exception number.
+but if before calling @code{set_debug_traps}, you set it to point to a
+function in your program, that function is called when
+@code{@value{GDBN}} continues after stopping on a trap (for example, bus
+error). The function indicated by @code{exceptionHook} is called with
+one parameter: an @code{int} which is the exception number.
@item
Compile and link together: your program, the @value{GDBN} debugging stub for
@end table
@node EB29K Remote
-@subsection @value{GDBN} with a remote EB29K
+@subsection @value{GDBN} and the EBMON protocol for AMD29K
@cindex EB29K board
@cindex running 29K programs
-To use @value{GDBN} from a Unix system to run programs on AMD's EB29K
-board in a PC, you must first connect a serial cable between the PC
-and a serial port on the Unix system. In the following, we assume
-you've hooked the cable between the PC's @file{COM1} port and
+AMD distributes a 29K development board meant to fit in a PC, together
+with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
+term, this development system is called the ``EB29K''. To use
+@value{GDBN} from a Unix system to run programs on the EB29K board, you
+must first connect a serial cable between the PC (which hosts the EB29K
+board) and a serial port on the Unix system. In the following, we
+assume you've hooked the cable between the PC's @file{COM1} port and
@file{/dev/ttya} on the Unix system.
@menu
VxWorks targets from a Unix host. Already-running tasks spawned from
the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
both the UNIX host and on the VxWorks target. The program
-@code{@value{GDBP}} is installed and executed on the UNIX host.
+@code{gdb} is installed and executed on the UNIX host. (It may be
+installed with the name @code{vxgdb}, to distinguish it from a
+@value{GDBN} for debugging programs on the host itself.)
The following information on connecting to VxWorks was current when
this manual was produced; newer releases of VxWorks may use revised
Once you have included the RDB interface in your VxWorks system image
and set your Unix execution search path to find @value{GDBN}, you are ready
-to run @value{GDBN}. From your UNIX host, type:
+to run @value{GDBN}. From your UNIX host, run @code{gdb} (or
+@code{vxgdb}, depending on your installation).
-@example
-% @value{GDBP}
-@end example
-
-@value{GDBN} will come up showing the prompt:
+@value{GDBN} comes up showing the prompt:
@example
-(@value{GDBP})
+(vxgdb)
@end example
@menu
network. To connect to a target whose host name is ``@code{tt}'', type:
@example
-(@value{GDBP}) target vxworks tt
+(vxgdb) target vxworks tt
@end example
-@value{GDBN} will display a message similar to the following:
+@value{GDBN} displays messages like these:
@smallexample
-Attaching remote machine across net... Success!
+Attaching remote machine across net...
+Connected to tt.
@end smallexample
-@value{GDBN} will then attempt to read the symbol tables of any object modules
+@value{GDBN} then attempts to read the symbol tables of any object modules
loaded into the VxWorks target since it was last booted. @value{GDBN} locates
these files by searching the directories listed in the command search
path (@pxref{Environment, ,Your program's environment}); if it fails
-to find an object file, it will display a message such as:
+to find an object file, it displays a message such as:
@example
prog.o: No such file or directory.
@end example
-This will cause the @code{target} command to abort. When this happens,
-you should add the appropriate directory to the search path, with the
-@value{GDBN} command @code{path}, and execute the @code{target} command
-again.
+When this happens, add the appropriate directory to the search path with
+the @value{GDBN} command @code{path}, and execute the @code{target}
+command again.
@node VxWorks Download
@subsubsection VxWorks download
@cindex download to VxWorks
If you have connected to the VxWorks target and you want to debug an
-object that has not yet been loaded, you can use the @value{GDBN} @code{load}
-command to download a file from UNIX to VxWorks incrementally. The
-object file given as an argument to the @code{load} command is actually
-opened twice: first by the VxWorks target in order to download the code,
-then by @value{GDBN} in order to read the symbol table. This can lead to
-problems if the current working directories on the two systems differ.
-It is simplest to set the working directory on both systems to the
-directory in which the object file resides, and then to reference the
-file by its name, without any path. Thus, to load a program
-@file{prog.o}, residing in @file{wherever/vw/demo/rdb}, on VxWorks type:
+object that has not yet been loaded, you can use the @value{GDBN}
+@code{load} command to download a file from UNIX to VxWorks
+incrementally. The object file given as an argument to the @code{load}
+command is actually opened twice: first by the VxWorks target in order
+to download the code, then by @value{GDBN} in order to read the symbol
+table. This can lead to problems if the current working directories on
+the two systems differ. If both systems have NFS mounted the same
+filesystems, you can avoid these problems by using absolute paths.
+Otherwise, it is simplest to set the working directory on both systems
+to the directory in which the object file resides, and then to reference
+the file by its name, without any path. For instance, a program
+@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
+and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
+program, type this on VxWorks:
@example
--> cd "wherever/vw/demo/rdb"
+-> cd "@var{vxpath}/vw/demo/rdb"
@end example
-On @value{GDBN} type:
+Then, in @value{GDBN}, type:
@example
-(@value{GDBP}) cd wherever/vw/demo/rdb
-(@value{GDBP}) load prog.o
+(vxgdb) cd @var{hostpath}/vw/demo/rdb
+(vxgdb) load prog.o
@end example
-@value{GDBN} will display a response similar to the following:
+@value{GDBN} displays a response similar to this:
@smallexample
Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
follows:
@example
-(@value{GDBP}) attach @var{task}
+(vxgdb) attach @var{task}
@end example
@noindent
projects / binutils-gdb.git / commitdiff