included in a translation approved by the author instead of in the
original English.
@end ifinfo
-
+@c @smallbook
@setchapternewpage odd
@settitle Using GDB (v4.0)
@titlepage
@end titlepage
@page
-@node Top, Top, Top, (DIR)
+@node Top, New Features, (dir), (dir)
@unnumbered Summary of GDB
The purpose of a debugger such as GDB is to allow you to see what is
Fortran compiler is written.
@menu
-* New Features:: What's new in GDB 4.0
-* License:: The GNU General Public License gives you permission
- to redistribute GDB on certain terms; and also
- explains that there is no warranty.
-* User Interface:: GDB command syntax and input and output conventions.
-* Files:: Specifying files for GDB to operate on.
-* Options:: GDB arguments and options.
-* Compilation::Compiling your program so you can debug it.
-* Running:: Running your program under GDB.
-* Stopping:: Making your program stop. Why it may stop. What to do then.
-* Stack:: Examining your program's stack.
-* Source:: Examining your program's source files.
-* Data:: Examining data in your program.
-* Symbols:: Examining the debugger's symbol table.
-* Altering:: Altering things in your program.
-* Sequences:: Canned command sequences for repeated use.
-* Emacs:: Using GDB through GNU Emacs.
-* Remote:: Remote debugging across a serial line or TCP/IP.
-* GDB Bugs:: How to report bugs (if you want to get them fixed).
-* Installing GDB:: How to set up GDB for your host and target
-* Commands:: Index of GDB commands.
-* Concepts:: Index of GDB concepts.
+* New Features:: New Features in GDB version 4.0
+* User Interface:: GDB Commands and Displays
+* Files:: Specifying GDB's Files
+* Compilation:: Compiling Your Program for Debugging
+* Targets:: Specifying a Debugging Target
+* Running:: Running Your Program Under GDB
+* Stopping:: Stopping and Continuing
+* Stack:: Examining the Stack
+* Source:: Examining Source Files
+* Data:: Examining Data
+* Symbols:: Examining the Symbol Table
+* Altering:: Altering Execution
+* Sequences:: Canned Sequences of Commands
+* Options:: Options and Arguments for GDB
+* Emacs:: Using GDB under GNU Emacs
+* Remote:: Remote Debugging
+* GDB Bugs:: Reporting Bugs in GDB
+* Installing GDB:: Installing GDB
+* License:: GNU GENERAL PUBLIC LICENSE
+* Commands:: Command Index
+* Concepts:: Index
+
+ --- The Detailed Node Listing ---
+
+Specifying GDB's Files
+
+* File Arguments:: Specifying Files with Arguments
+* File Commands:: Specifying Files with Commands
+
+Running Your Program Under GDB
+
+* Arguments:: Specifying the arguments for your program.
+* Environment:: Specifying the environment for your program.
+* Working Directory:: Specifying the working directory for giving
+ to your program when it is run.
+* Input/Output:: Specifying the program's standard input and output.
+* Attach:: Debugging a process started outside GDB.
+* Kill Process:: Getting rid of the child process running your program.
+
+Stopping and Continuing
+
+* Signals:: Fatal signals in your program just stop it;
+ then you can use GDB to see what is going on.
+* Breakpoints:: Breakpoints let you stop your program when it
+ reaches a specified point in the code.
+ an expression changes.
+* Continuing:: Resuming execution until the next signal or breakpoint.
+* Stepping:: Stepping runs the program a short distance and
+ then stops it wherever it has come to.
+
+Breakpoints
+
+* Set Breaks:: How to establish breakpoints.
+* Exception Handling:: How GDB supports exception handling for C++.
+* Delete Breaks:: How to remove breakpoints no longer needed.
+* Disabling:: How to disable breakpoints (turn them off temporarily).
+* Conditions:: Making extra conditions on whether to stop.
+* Break Commands:: Commands to be executed at a breakpoint.
+* Error in Breakpoints::
+
+Examining the Stack
+
+* Frames:: Explanation of stack frames and terminology.
+* Backtrace:: Summarizing many frames at once.
+* Selection:: How to select a stack frame.
+* Frame Info:: Information on a Frame
+
+Examining Source Files
+
+* List:: Using the @samp{list} command to print source files.
+* Search:: Commands for searching source files.
+* Source Path:: Specifying the directories to search for source files.
+
+Examining Data
+
+* Expressions:: Expressions that can be computed and printed.
+* Variables:: Using your program's variables in expressions.
+* Arrays:: Examining part of memory as an array.
+* Format options:: Controlling how structures and arrays are printed.
+* Output formats:: Specifying formats for printing values.
+* Auto Display:: Printing certain expressions whenever program stops.
+* Value History:: Referring to values previously printed.
+* Convenience Vars:: Giving names to values for future reference.
+* Registers:: Referring to and storing in machine registers.
+
+Output formats
+
+* Memory:: Examining Memory
+
+Altering Execution
+
+* Assignment:: Altering variable values or memory contents.
+* Jumping:: Altering control flow.
+* Signaling:: Making signals happen in the program.
+* Returning:: Making a function return prematurely.
+* Calling:: Calling functions from your program
+
+Canned Sequences of Commands
+
+* Define:: User-defined commands.
+* Command Files:: Command files.
+* Output:: Controlled output commands useful in
+ user-defined commands and command files.
+
+Options and Arguments for GDB
+
+* Mode Options:: Options controlling modes of operation.
+* File Options:: Options to specify files (executable, coredump, commands)
+* Other Arguments:: Any other arguments without options
+ also specify files.
+
+Remote Debugging
+
+* Remote Commands:: Commands used to start and finish remote debugging.
+
+Reporting Bugs in GDB
+
+* Bug Criteria:: Have You Found a Bug?
+* Bug Reporting:: How to Report Bugs
@end menu
-@node New Features, License, Top, Top
+@node New Features, User Interface, Top, Top
@unnumbered New Features in GDB version 4.0
@itemize @bullet
@end itemize
+@node User Interface, Files, New Features, Top
+@chapter GDB Commands and Displays
+GDB is invoked with the shell command @samp{gdb}. Once started, it reads
+commands from the terminal until you tell it to exit.
-@node License, User Interface, New Features, Top
-@unnumbered GNU GENERAL PUBLIC LICENSE
-@center Version 1, February 1989
+A GDB command is a single line of input. There is no limit on how long
+it can be. It starts with a command name, which is followed by arguments
+whose meaning depends on the command name. For example, the command
+@samp{step} accepts an argument which is the number of times to step,
+as in @samp{step 5}. You can also use the @samp{step} command with
+no arguments. Some command names do not allow any arguments.
-@display
-Copyright @copyright{} 1989 Free Software Foundation, Inc.
-675 Mass Ave, Cambridge, MA 02139, USA
+@cindex abbreviation
+GDB command names may always be truncated if that abbreviation is
+unambiguous. Other possible command abbreviations are listed in the
+documentation of the individual commands. Sometimes even ambiguous
+abbreviations are allowed; for example, @samp{s} is specially defined as
+equivalent to @samp{step} even though there are other commands whose
+names start with @samp{s}.
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@end display
+@cindex repeating commands
+A blank line as input to GDB means to repeat the previous command.
+Certain commands will not repeat this way; these are commands for which
+unintentional repetition might cause trouble and which you are unlikely
+to want to repeat. Certain others (@samp{list} and @samp{x}) act
+differently when repeated because that is more useful.
-@unnumberedsec Preamble
+@kindex #
+@cindex comment
+A line of input starting with @samp{#} is a comment; it does nothing.
+This is useful mainly in command files (@xref{Command Files}).
- The license agreements of most software companies try to keep users
-at the mercy of those companies. By contrast, our 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. The
-General Public License applies to the Free Software Foundation's
-software and to any other program whose authors commit to using it.
-You can use it for your programs, too.
+@cindex online documentation
+@kindex help
+@table @code
+@item help
+@itemx help @var{category}
+@itemx help @var{command}
+You can always ask GDB itself for information on its commands, using the
+command @samp{help}. With a command name as argument, it will display a
+paragraph on how to use the command. Used with no arguments,
+@samp{help} displays a short list of named categories of commands; you
+can then use @samp{help @var{category}} to list the individual commands
+in a category.
- When we speak of free software, we are referring to freedom, not
-price. Specifically, the General Public License is designed to make
-sure that you have the freedom to give away or sell copies of free
-software, 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.
+@kindex info version
+@item info version
+As GDB evolves, new commands are introduced, and old ones may wither
+away. If multiple versions of GDB are in use at your site, it may
+occasionally be useful to make sure what version of GDB you're running.
+GDB announces its version whenever it starts up; but you can make it
+repeat this information with the @samp{info version} command.
+@end table
- 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.
+@cindex prompt
+GDB indicates its readiness to read a command by printing a string
+called the @dfn{prompt}. This string is normally @samp{(gdb)}. You can
+change the prompt string with the @samp{set prompt} command. For
+instance, when debugging GDB with GDB, it is useful to change the prompt
+in one of the GDBs so that you tell which one you are talking to.
- For example, if you distribute copies of a 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 tell them their rights.
+@table @code
+@item set prompt @var{newprompt}
+@kindex set prompt
+Directs GDB to use @var{newprompt} as its prompt string henceforth.
+@kindex show prompt
+@item show prompt
+Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
+@end table
- 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.
+@cindex exiting GDB
+@kindex quit
+To exit GDB, use the @samp{quit} command (abbreviated @samp{q}), or type
+an end-of-file character (usually @ctrl{d}). An interrupt (often
+@ctrl{c}) will not exit from GDB, but rather will terminate the action
+of any GDB command that is in progress and return to GDB command level.
+It is safe to type the interrupt character at any time because GDB does
+not allow it to take effect until a time when it is safe.
- 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.
+@cindex readline
+@cindex command line editing
+@cindex history substitution
+GDB reads its input commands via the @code{readline} interface. This
+GNU library provides consistent behavior for programs which provide a
+command line interface to the user. Advantages are @samp{emacs}-style
+or @samp{vi}-style inline editing of commands, @samp{csh}-like history
+substitution, and a storage and recall of command history across
+debugging sessions.
- The precise terms and conditions for copying, distribution and
-modification follow.
+You may control the behavior of command line editing in GDB with the
+command @samp{set}. You may check the status of any of these settings
+with the command @samp{show}.
-@iftex
-@unnumberedsec TERMS AND CONDITIONS
-@end iftex
-@ifinfo
-@center TERMS AND CONDITIONS
-@end ifinfo
+@table @code
+@kindex set editing
+@cindex editing
+@item set editing
+@itemx set editing on
+Enable command line editing (enabled by default).
-@enumerate
-@item
-This License Agreement 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 work containing the
-Program or a portion of it, either verbatim or with modifications. Each
-licensee is addressed as ``you''.
+@item set editing off
+Disable command line editing.
-@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
-General Public License and to the absence of any warranty; and give any
-other recipients of the Program a copy of this General Public License
-along with the Program. You may charge a fee for the physical act of
-transferring a copy.
+@kindex show editing
+@item show editing
+Show whether command line editing is enabled.
-@item
-You may modify your copy or copies of the Program or any portion of
-it, and copy and distribute such modifications under the terms of Paragraph
-1 above, provided that you also do the following:
+@cindex history file
+@kindex set history file
+@item set history file @var{filename}
+Set the name of the GDB command history file to @samp{filename}. This is
+the file from which GDB will read an initial command history
+list or to which it will write this list when it exits. This list is
+accessed through history expansion or through the history
+command editing characters listed below. This file defaults to the
+value of the environmental variable @code{GDBHISTFILE}, or to
+@code{./.gdb_history} if this variable is not set.
-@itemize @bullet
-@item
-cause the modified files to carry prominent notices stating that
-you changed the files and the date of any change; and
+@cindex history write
+@kindex set history write
+@item set history write
+@itemx set history write on
+Make GDB record command history in a file, whose name may be specified with the
+@samp{set history file} command. By default, this option is disabled.
-@item
-cause the whole of any work that you distribute or publish, that
-in whole or in part contains the Program or any part thereof, either
-with or without modifications, to be licensed at no charge to all
-third parties under the terms of this General Public License (except
-that you may choose to grant warranty protection to some or all
-third parties, at your option).
+@item set history write off
+Make GDB stop recording command history in a file.
-@item
-If the modified program normally reads commands interactively when
-run, you must cause it, when started running for such interactive use
-in the simplest and most usual 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 General
-Public License.
+@cindex history size
+@kindex set history size
+@item set history size @var{size}
+Set the number of commands which GDB will keep in its history list.
+This defaults to the value of the environmental variable
+@code{HISTSIZE}, or to 256 if this variable is not set.
+@end table
-@item
-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.
-@end itemize
+@cindex history expansion
+History expansion assigns special meaning to the character @samp{!}
+(@pxref{Event Designators}). Since @samp{!} is also the logical not
+operator in C, history expansion is off by default. If you decide to
+enable history expansion with the @samp{set history expansion on}
+command, you may sometimes need to follow @samp{!} (when it is used as
+logical not, in an expression) with a space or a tab to prevent it from
+being expanded. The @code{readline} history facilities will not attempt
+substitution on the strings @samp{!=} and @samp{!(}, even when history
+expansion is enabled.
-Mere aggregation of another independent work with the Program (or its
-derivative) on a volume of a storage or distribution medium does not bring
-the other work under the scope of these terms.
-
-@item
-You may copy and distribute the Program (or a portion or derivative of
-it, under Paragraph 2) in object code or executable form under the terms of
-Paragraphs 1 and 2 above provided that you also do one of the following:
-
-@itemize @bullet
-@item
-accompany it with the complete corresponding machine-readable
-source code, which must be distributed under the terms of
-Paragraphs 1 and 2 above; or,
-
-@item
-accompany it with a written offer, valid for at least three
-years, to give any third party free (except for a nominal charge
-for the cost of distribution) a complete machine-readable copy of the
-corresponding source code, to be distributed under the terms of
-Paragraphs 1 and 2 above; or,
-
-@item
-accompany it with the information you received as to where the
-corresponding source code may be obtained. (This alternative is
-allowed only for noncommercial distribution and only if you
-received the program in object code or executable form alone.)
-@end itemize
-
-Source code for a work means the preferred form of the work for making
-modifications to it. For an executable file, complete source code means
-all the source code for all modules it contains; but, as a special
-exception, it need not include source code for modules which are standard
-libraries that accompany the operating system on which the executable
-file runs, or for standard header files or definitions files that
-accompany that operating system.
-
-@item
-You may not copy, modify, sublicense, distribute or transfer the
-Program except as expressly provided under this General Public License.
-Any attempt otherwise to copy, modify, sublicense, distribute or transfer
-the Program is void, and will automatically terminate your rights to use
-the Program under this License. However, parties who have received
-copies, or rights to use copies, from you under this General Public
-License will not have their licenses terminated so long as such parties
-remain in full compliance.
-
-@item
-By copying, distributing or modifying 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.
-
-@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.
-
-@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 the 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
-the 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 Appendix: How to Apply These Terms to Your New Programs
-
- If you develop a new program, and you want it to be of the greatest
-possible use to humanity, 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 a brief 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 1, 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 `show w' and `show c' should show the
-appropriate parts of the General Public License. Of course, the
-commands you use may be called something other than `show w' and `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 a sample; alter the names:
-
-@example
-Yoyodyne, Inc., hereby disclaims all copyright interest in the
-program `Gnomovision' (a program to direct compilers to make passes
-at assemblers) written by James Hacker.
-
-@var{signature of Ty Coon}, 1 April 1989
-Ty Coon, President of Vice
-@end example
-
-That's all there is to it!
-
-@node User Interface, Files, License, Top
-@chapter GDB Commands and Displays
-
-GDB is invoked with the shell command @samp{gdb}. Once started, it reads
-commands from the terminal until you tell it to exit.
-
-A GDB command is a single line of input. There is no limit on how long
-it can be. It starts with a command name, which is followed by arguments
-whose meaning depends on the command name. For example, the command
-@samp{step} accepts an argument which is the number of times to step,
-as in @samp{step 5}. You can also use the @samp{step} command with
-no arguments. Some command names do not allow any arguments.
-
-@cindex abbreviation
-GDB command names may always be truncated if that abbreviation is
-unambiguous. Other possible command abbreviations are listed in the
-documentation of the individual commands. Sometimes even ambiguous
-abbreviations are allowed; for example, @samp{s} is specially defined as
-equivalent to @samp{step} even though there are other commands whose
-names start with @samp{s}.
-
-@cindex repeating commands
-A blank line as input to GDB means to repeat the previous command.
-Certain commands will not repeat this way; these are commands for which
-unintentional repetition might cause trouble and which you are unlikely
-to want to repeat. Certain others (@samp{list} and @samp{x}) act
-differently when repeated because that is more useful.
-
-@kindex #
-@cindex comment
-A line of input starting with @samp{#} is a comment; it does nothing.
-This is useful mainly in command files (@xref{Command Files}).
-
-@cindex online documentation
-@kindex help
-@table @code
-@item help
-@itemx help @var{category}
-@itemx help @var{command}
-You can always ask GDB itself for information on its commands, using the
-command @samp{help}. With a command name as argument, it will display a
-paragraph on how to use the command. Used with no arguments,
-@samp{help} displays a short list of named categories of commands; you
-can then use @samp{help @var{category}} to list the individual commands
-in a category.
-
-@kindex info version
-@item info version
-As GDB evolves, new commands are introduced, and old ones may wither
-away. If multiple versions of GDB are in use at your site, it may
-occasionally be useful to make sure what version of GDB you're running.
-GDB announces its version whenever it starts up; but you can make it
-repeat this information with the @samp{info version} command.
-@end table
-
-@cindex prompt
-GDB indicates its readiness to read a command by printing a string
-called the @dfn{prompt}. This string is normally @samp{(gdb)}. You can
-change the prompt string with the @samp{set prompt} command. For
-instance, when debugging GDB with GDB, it is useful to change the prompt
-in one of the GDBs so that you tell which one you are talking to.
-
-@table @code
-@item set prompt @var{newprompt}
-@kindex set prompt
-Directs GDB to use @var{newprompt} as its prompt string henceforth.
-@kindex show prompt
-@item show prompt
-Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
-@end table
-
-@cindex exiting GDB
-@kindex quit
-To exit GDB, use the @samp{quit} command (abbreviated @samp{q}), or type
-an end-of-file character (usually @ctrl{d}). An interrupt (often
-@ctrl{c}) will not exit from GDB, but rather will terminate the action
-of any GDB command that is in progress and return to GDB command level.
-It is safe to type the interrupt character at any time because GDB does
-not allow it to take effect until a time when it is safe.
-
-@cindex readline
-@cindex command line editing
-@cindex history substitution
-GDB reads its input commands via the @code{readline} interface. This
-GNU library provides consistent behavior for programs which provide a
-command line interface to the user. Advantages are @samp{emacs}-style
-or @samp{vi}-style inline editing of commands, @samp{csh}-like history
-substitution, and a storage and recall of command history across
-debugging sessions.
-
-You may control the behavior of command line editing in GDB with the
-command @samp{set}. You may check the status of any of these settings
-with the command @samp{show}.
-
-@table @code
-@kindex set editing
-@cindex editing
-@item set editing
-@itemx set editing on
-Enable command line editing (enabled by default).
-
-@item set editing off
-Disable command line editing.
-
-@kindex show editing
-@item show editing
-Show whether command line editing is enabled.
-
-@cindex history file
-@kindex set history file
-@item set history file @var{filename}
-Set the name of the GDB command history file to @samp{filename}. This is
-the file from which GDB will read an initial command history
-list or to which it will write this list when it exits. This list is
-accessed through history expansion or through the history
-command editing characters listed below. This file defaults to the
-value of the environmental variable @code{GDBHISTFILE}, or to
-@code{./.gdb_history} if this variable is not set.
-
-@cindex history write
-@kindex set history write
-@item set history write
-@itemx set history write on
-Make GDB record command history in a file, whose name may be specified with the
-@samp{set history file} command. By default, this option is disabled.
-
-@item set history write off
-Make GDB stop recording command history in a file.
-
-@cindex history size
-@kindex set history size
-@item set history size @var{size}
-Set the number of commands which GDB will keep in its history list.
-This defaults to the value of the environmental variable
-@code{HISTSIZE}, or to 256 if this variable is not set.
-@end table
-
-@cindex history expansion
-History expansion assigns special meaning to the character @samp{!}
-(@pxref{Event Designators}). Since @samp{!} is also the logical not
-operator in C, history expansion is off by default. If you decide to
-enable history expansion with the @samp{set history expansion on}
-command, you may sometimes need to follow @samp{!} (when it is used as
-logical not, in an expression) with a space or a tab to prevent it from
-being expanded. The @code{readline} history facilities will not attempt
-substitution on the strings @samp{!=} and @samp{!(}, even when history
-expansion is enabled.
-
-The commands to control history expansion are:
+The commands to control history expansion are:
@table @code
the core dump.
@menu
-* Arguments: File Arguments. Specifying files with arguments
- (when you start GDB).
-* Commands: File Commands. Specifying files with GDB commands.
+* File Arguments:: Specifying Files with Arguments
+* File Commands:: Specifying Files with Commands
@end menu
@node File Arguments, File Commands, Files, Files
@xref{Options}, for full information on options and arguments for
invoking GDB.
-@node File Commands,, File Arguments, Files
+@node File Commands, , File Arguments, Files
@section Specifying Files with Commands
Usually you specify the files for GDB to work with by giving arguments when
Symbol number @var{n} contains a pointer into the string table which is
larger than the size of the string table. GDB circumvents the problem
by considering the symbol to have the name @code{foo}, which may cause
-other problems if many symbols end up with this name. @index{foo}
+other problems if many symbols end up with this name. @cindex{foo}
@item unknown symbol type @code{0xNN}
@code{ar} dated more recently than August 1989.
@end ignore
-@node Targets, Running, Compilation, Top
+@node Targets, Running, Compilation, Top
@chapter Specifying a Debugging Target
@cindex debugging target
@kindex target
program. In this process, it tries to retain your current breakpoints.
@menu
-* Arguments:: Specifying the arguments for your program.
-* Environment:: Specifying the environment for your program.
-* Working Directory:: Specifying the working directory for giving
+* Arguments:: Specifying the arguments for your program.
+* Environment:: Specifying the environment for your program.
+* Working Directory:: Specifying the working directory for giving
to your program when it is run.
-* Input/Output:: Specifying the program's standard input and output.
-* Attach:: Debugging a process started outside GDB.
-* Kill Process:: Getting rid of the child process running your program.
+* Input/Output:: Specifying the program's standard input and output.
+* Attach:: Debugging a process started outside GDB.
+* Kill Process:: Getting rid of the child process running your program.
@end menu
@node Arguments, Environment, Running, Running
The @samp{attach} command is also used to debug a remote machine via a
serial connection. @xref{Remote}, for more info.
-@node Kill Process,, Attach, Running
+@node Kill Process, , Attach, Running
@section Killing the Child Process
@table @code
investigate and find out why.
@menu
-* Signals:: Fatal signals in your program just stop it;
+* Signals:: Fatal signals in your program just stop it;
then you can use GDB to see what is going on.
-* Breakpoints:: Breakpoints let you stop your program when it
+* Breakpoints:: Breakpoints let you stop your program when it
reaches a specified point in the code.
an expression changes.
-* Continuing:: Resuming execution until the next signal or breakpoint.
-* Stepping:: Stepping runs the program a short distance and
+* Continuing:: Resuming execution until the next signal or breakpoint.
+* Stepping:: Stepping runs the program a short distance and
then stops it wherever it has come to.
@end menu
seeing a signal, or cause it to see a signal it normally would not see,
or to give it any signal at any time. @xref{Signaling}.
-@node Breakpoints, Watchpoints Continuing, Signals, Stopping
+@node Breakpoints, Continuing, Signals, Stopping
@section Breakpoints
@cindex breakpoints
@end table
@menu
-* Set Breaks:: How to establish breakpoints.
-* Exception Handling:: How GDB supports exception handling for C++.
-* Delete Breaks:: How to remove breakpoints no longer needed.
-* Disabling:: How to disable breakpoints (turn them off temporarily).
-* Conditions:: Making extra conditions on whether to stop.
-* Break Commands:: Commands to be executed at a breakpoint.
-* Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do.
+* Set Breaks:: How to establish breakpoints.
+* Exception Handling:: How GDB supports exception handling for C++.
+* Delete Breaks:: How to remove breakpoints no longer needed.
+* Disabling:: How to disable breakpoints (turn them off temporarily).
+* Conditions:: Making extra conditions on whether to stop.
+* Break Commands:: Commands to be executed at a breakpoint.
+* Error in Breakpoints::
@end menu
@node Set Breaks, Exception Handling, Breakpoints, Breakpoints
You cannot interactively install an exception handler.
@end itemize
-@node Delete Breaks, Disabling, Set Breaks, Breakpoints
+@node Delete Breaks, Disabling, Exception Handling, Breakpoints
@subsection Deleting Breakpoints
@cindex clearing breakpoints and watchpoints
nontrivial conditions for performing the side effects, the operators
@samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
-@node Error in Breakpoints,, Break Commands, Breakpoints
+@node Error in Breakpoints, , Break Commands, Breakpoints
@subsection ``Cannot Insert Breakpoints'' Error
Under some operating systems, breakpoints cannot be used in a program if
also act in advance to control what signals your program will see, using
the @samp{handle} command (@pxref{Signals}).
-@node Stepping,, Continuing, Stopping
+@node Stepping, , Continuing, Stopping
@section Stepping
@cindex stepping
(@pxref{Frame Info, Info}).
@menu
-* Frames:: Explanation of stack frames and terminology.
-* Backtrace:: Summarizing many frames at once.
-* Selection:: How to select a stack frame.
-* Info: Frame Info, Commands to print information on stack frames.
+* Frames:: Explanation of stack frames and terminology.
+* Backtrace:: Summarizing many frames at once.
+* Selection:: How to select a stack frame.
+* Frame Info:: Information on a Frame
@end menu
@node Frames, Backtrace, Stack, Stack
After such a printout, the @samp{list} command with no arguments will print
ten lines centered on the point of execution in the frame. @xref{List}.
-@node Frame Info, , Selection, Stack
+@node Frame Info, , Selection, Stack
@section Information on a Frame
There are several other commands to print information about the selected
print parts of source files by explicit command.
@menu
-* List:: Using the @samp{list} command to print source files.
-* Search:: Commands for searching source files.
-* Source Path:: Specifying the directories to search for source files.
+* List:: Using the @samp{list} command to print source files.
+* Search:: Commands for searching source files.
+* Source Path:: Specifying the directories to search for source files.
@end menu
@node List, Search, Source, Source
for @var{regexp}. It lists the line that is found. You can abbreviate
this command with as little as @samp{rev}.
-@node Source Path,, Search, Source
+@node Source Path, , Search, Source
@section Specifying Source Directories
@cindex source path
specified format.
@menu
-* Expressions:: Expressions that can be computed and printed.
-* Variables:: Using your program's variables in expressions.
-* Assignment:: Setting your program's variables.
-* Arrays:: Examining part of memory as an array.
-* Format Options:: Controlling how structures and arrays are printed.
-* Output formats:: Specifying formats for printing values.
-* Memory:: Examining memory explicitly.
-* Auto Display:: Printing certain expressions whenever program stops.
-* Value History:: Referring to values previously printed.
-* Convenience Vars:: Giving names to values for future reference.
-* Registers:: Referring to and storing in machine registers.
+* Expressions:: Expressions that can be computed and printed.
+* Variables:: Using your program's variables in expressions.
+* Arrays:: Examining part of memory as an array.
+* Format options:: Controlling how structures and arrays are printed.
+* Output formats:: Specifying formats for printing values.
+* Auto Display:: Printing certain expressions whenever program stops.
+* Value History:: Referring to values previously printed.
+* Convenience Vars:: Giving names to values for future reference.
+* Registers:: Referring to and storing in machine registers.
@end menu
@node Expressions, Variables, Data, Data
@item set prettyprint off
Cause GDB to print structures in a compact format, like this:
-@example
+@smallexample
$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \
= 0x54 "Pork"@}
-@end example
+@end smallexample
@noindent
This is the default format.
For example, given the declarations
-@example
+@smallexample
typedef enum @{Tree, Bug@} Species;
typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
typedef enum @{Caterpillar, Cocoon, Butterfly@} Bug_forms;
@};
struct thing foo = @{Tree, @{Acorn@}@};
-@end example
+@end smallexample
@noindent
with @samp{set unionprint on} in effect @samp{p foo} would print
-@example
+@smallexample
$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
-@end example
+@end smallexample
@noindent
and with @samp{set unionprint off} in effect it would print
@end example
@end table
-@node Output formats, Memory, Format options, Data
+@node Output formats, Auto Display, Format options, Data
@section Output formats
@cindex formatted output
you can use the @samp{print} command with just a format and no
expression. For example, @samp{p/x} reprints the last value in hex.
-@node Memory, Auto Display, Output formats, Data
+@menu
+* Memory:: Examining Memory
+@end menu
+
+@node Memory, , Output formats, Output formats
@subsection Examining Memory
@cindex examining memory
are from the last memory unit printed; this is not the same as the last
address printed if several units were printed on the last line of output.
-@node Auto Display, Value History, Memory, Data
+@node Auto Display, Value History, Output formats, Data
@section Automatic Display
@cindex automatic display
@cindex display of expressions
to the value found in the last address examined.
@end table
-@node Registers,, Convenience Vars, Data
+@node Registers, , Convenience Vars, Data
@section Registers
@cindex registers
or even return prematurely from a function to its caller.
@menu
-* Assignment:: Altering variable values or memory contents.
-* Jumping:: Altering control flow.
-* Signaling:: Making signals happen in the program.
-* Returning:: Making a function return prematurely.
-* Calling:: Calling functions from your program
+* Assignment:: Altering variable values or memory contents.
+* Jumping:: Altering control flow.
+* Signaling:: Making signals happen in the program.
+* Returning:: Making a function return prematurely.
+* Calling:: Calling functions from your program
@end menu
@node Assignment, Jumping, Altering, Altering
(@pxref{Stepping}), which resumes execution until the selected stack
frame returns @emph{naturally}.
-@node Calling, , , Returning, Altering
+@node Calling, , Returning, Altering
@comment node-name, next, previous, up
@section Calling your Program's Functions
user-defined commands and command files.
@menu
-* Define:: User-defined commands.
-* Command Files:: Command files.
-* Output:: Controlled output commands useful in
+* Define:: User-defined commands.
+* Command Files:: Command files.
+* Output:: Controlled output commands useful in
user-defined commands and command files.
@end menu
normally print messages to say what they are doing omit the messages
when used in a command file.
-@node Output,, Command Files, Sequences
+@node Output, , Command Files, Sequences
@section Commands for Controlled Output
During the execution of a command file or a user-defined command, the only
operate on and what other things to do.
@menu
-* Mode Options:: Options controlling modes of operation.
-* File Options:: Options to specify files (executable, coredump, commands)
-* Other Arguments:: Any other arguments without options
+* Mode Options:: Options controlling modes of operation.
+* File Options:: Options to specify files (executable, coredump, commands)
+* Other Arguments:: Any other arguments without options
also specify files.
@end menu
Add @var{directory} to the path to search for source files.
@end table
-@node Other Arguments,, File Options, Options
+@node Other Arguments, , File Options, Options
@section Other Arguments
If there are arguments to GDB that are not options or associated with
each value is printed in its own window.
@end ignore
-@node Remote, Commands, Emacs, Top
+@node Remote, GDB Bugs, Emacs, Top
@chapter Remote Debugging
@cindex remote debugging
the @file{README} file in the GDB distribution for more information.
@menu
-* Remote Commands:: Commands used to start and finish remote debugging.
+* Remote Commands:: Commands used to start and finish remote debugging.
@end menu
For details of the communication protocol, see the comments in the GDB
source file @file{remote.c}.
-@node Remote Commands, GDB Bugs, Remote, Remote
+@node Remote Commands, , Remote, Remote
@section Commands for Remote Debugging
To start remote debugging, first run GDB and specify as an executable file
target remote /dev/ttyd
@end example
-@noindent
-if the serial line is connected to the device named @file{/dev/ttyd}. This
-will stop the remote machine if it is not already stopped.
+@noindent
+if the serial line is connected to the device named @file{/dev/ttyd}. This
+will stop the remote machine if it is not already stopped.
+
+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 @samp{detach}
+command.
+
+@table @code
+@item reset
+@kindex reset
+For a target attached through a serial line, 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
+
+@node GDB Bugs, Installing GDB, Remote, Top
+@comment node-name, next, previous, up
+@chapter Reporting Bugs in GDB
+@cindex Bugs in GDB
+@cindex Reporting Bugs in GDB
+
+Your bug reports play an essential role in making GDB reliable.
+
+Reporting a bug may help you by bringing a solution to your problem, or it
+may not. But in any case the important function of a bug report is to help
+the entire community by making the next version of GDB work better. Bug
+reports are your contribution to the maintenance of GDB.
+
+In order for a bug report to serve its purpose, you must include the
+information that makes for fixing the bug.
+
+@menu
+* Bug Criteria:: Have You Found a Bug?
+* Bug Reporting:: How to Report Bugs
+@end menu
+
+@node Bug Criteria, Bug Reporting, GDB Bugs, GDB Bugs
+@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
+@item
+@cindex Fatal Signal
+@cindex Core Dump
+If the debugger gets a fatal signal, for any input whatever, that is a
+GDB bug. Reliable debuggers never crash.
+
+@item
+@cindex error on Valid Input
+If GDB produces an error message for valid input, that is a bug.
+
+@item
+@cindex Invalid Input
+If GDB 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 GDB are welcome in any case.
+@end itemize
+
+@node Bug Reporting, , Bug Criteria, GDB Bugs
+@section How to Report Bugs
+@cindex Bug Reports
+@cindex Compiler Bugs, Reporting
+
+@comment The following is meant to be neutral and helpful, not just a plug for
+@comment Cygnus; feedback on the issue (to "pesch@cygnus.com" or
+@comment "info@cygnus.com"---the latter will reach all of Cygnus)
+@comment is welcome.
+A number of companies and individuals offer support for GNU products.
+If you obtained GDB from a support organization, we recommend you
+contact that organization first.
+
+Among these organizations are Cygnus Support (Palo Alto CA, USA); C2V
+(Paris, France); Dynamix Corporation (King of Prussia PA, USA); The Nice
+Computer Company (Perth, Australia); Optimal Solutions (Seattle WA,
+USA); and The Pharos Group (Las Cruces NM, USA).
+
+Full contact information is in the file @samp{etc/SERVICE} in the GNU
+Emacs distribution. Numerous individual consultants are also listed
+there.
+@comment END NEUTRAL+HELPFUL section
+
+In any event, we also recommend that you send bug reports for GDB to one
+of these addresses:
+
+@example
+bug-gdb@@prep.ai.mit.edu
+@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb
+@end example
+
+@strong{Do not send bug reports to @samp{info-gdb}, or to
+@samp{help-gdb}, or to any newsgroups.} Most users of GDB do not want to
+receive bug reports. Those that do, have asked to be on @samp{bug-gdb}.
+
+The mailing list @samp{bug-gdb} has a newsgroup 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 does not contain 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.
+
+As a last resort, send bug reports on paper to:
+
+@example
+GNU Debugger Bugs
+545 Tech Sq
+Cambridge, MA 02139
+@end example
+
+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 they conclude that some details don't matter. Thus, you might
+assume that the name of the variable you use in an example does not matter.
+Well, probably it doesn't, 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 if it is not known. It isn't very important what happens if
+the bug is already known. Therefore, always write your bug reports on
+the assumption that the bug is not known.
+
+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 GDB. GDB announces it on startup; you can also print it
+at any time using @samp{info version}.
+
+Without this, we won't know whether there is any point in looking for
+the bug in the current version of GDB.
+
+@item
+A complete input script, and all necessary source files, that will
+reproduce the bug.
+
+@item
+What compiler (and its version) was used to compile GDB---e.g.
+``GCC-1.37.1''.
+
+@item
+What compiler (and its version) was used to compile GDB.
+
+@item
+The command arguments you gave the compiler to compile that example and
+observe the bug. For example, did you use @samp{-O}? To guarantee
+you won't omit something important, list them all.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we would not encounter the bug.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@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 GDB 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.
+
+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 GDB 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 @i{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 GDB source, send us context
+diffs. If you even discuss something in the GDB source, refer to
+it by context, not by line number.
+
+The line numbers in our development sources don't 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, etc.
+
+However, simplification is not vital; if you don't 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 don't 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 GDB it is very hard to
+construct an example that will make the program follow a certain path
+through the code. If you don't send us the example, we won't be able
+to construct one, so we won't be able to verify that the bug is fixed.
+
+And if we can't understand what bug you are trying to fix, or why your
+patch should be an improvement, we won't install it. A test case will
+help us to understand.
-Now you can use all the usual commands to examine and change data and to
-step and continue the remote program.
+@item
+A guess about what the bug is or what it depends on.
-To resume the remote program and stop debugging it, use the @samp{detach}
-command.
+Such guesses are usually wrong. Even we can't guess right about such
+things without first using the debugger to find the facts.
+@end itemize
-@table @code
-@item reset
-@kindex reset
-For a target attached through a serial line, 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
+@iftex
+@include readline/inc-readline.texinfo
+@include readline/inc-history.texinfo
+@end iftex
-@node GDB Bugs, , Remote Commands, Top
-@comment node-name, next, previous, up
-@chapter Reporting Bugs in GDB
-@cindex Bugs in GDB
-@cindex Reporting Bugs in GDB
+@node Installing GDB, License, GDB Bugs, Top
+@appendix Installing GDB
+@cindex configuring GDB
+@cindex installation
-Your bug reports play an essential role in making GDB reliable.
+The script @samp{config.gdb} automates the process of preparing GDB for
+installation; you can then use @samp{make} to actually build it. For
+example,
-Reporting a bug may help you by bringing a solution to your problem, or it
-may not. But in any case the important function of a bug report is to help
-the entire community by making the next version of GDB work better. Bug
-reports are your contribution to the maintenance of GDB.
+@example
+config.gdb sun3os4
+make
+@end example
-In order for a bug report to serve its purpose, you must include the
-information that makes for fixing the bug.
+@noindent
+is all that's required to install GDB on a Sun 3 running SunOS 4.
-@menu
-* Criteria: Bug Criteria. Have you really found a bug?
-* Reporting: Bug Reporting. How to report a bug effectively.
-* Known: Trouble. Known problems.
-@end menu
+@table @code
+@kindex config.gdb
+@item config.gdb @var{machine}
+@itemx config.gdb +srcdir=@var{dir} @var{machine}
+This is the most usual way of configuring GDB; to debug programs running
+on the same machine as GDB itself. If you wish to build the GDB binaries
+in a completely different directory from the sources, specify a path to
+the source directory using the @samp{+srcdir} option.
-@node Bug Criteria, Bug Reporting, Bugs, Bugs
-@section Have You Found a Bug?
-@cindex Bug Criteria
+@item config.gdb +host
+@cindex host environments
+Display a list of supported host environments for GDB.
-If you are not sure whether you have found a bug, here are some guidelines:
+@item config.gdb @var{host} @var{target}
+@itemx config.gdb +srcdir=@var{dir} @var{host} @var{target}
+@cindex cross-debugging
+GDB can also be used as a cross-debugger, running on a machine of one
+type while debugging a program running on a machine of another type.
+You configure it this way by specifying first the @var{host}, then the
+@var{target} environment on the @code{config.gdb} argument list; the
+@var{host} is where GDB runs, and the @var{target} is where your program
+runs. @xref{Remote}. Again, you can use @samp{+srcdir} to specify a
+path to the GDB source.
-@itemize @bullet
-@item
-@cindex Fatal Signal
-@cindex Core Dump
-If the debugger gets a fatal signal, for any input whatever, that is a
-GDB bug. Reliable debuggers never crash.
+@item config.gdb +target
+@cindex target environments
+Display a list of supported target environments for GDB.
+@end table
-@item
-@cindex error on Valid Input
-If GDB produces an error message for valid input, that is a bug.
+@node License, Commands, Installing GDB, Top
+@unnumbered GNU GENERAL PUBLIC LICENSE
+@center Version 1, February 1989
-@item
-@cindex Invalid Input
-If GDB 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''.
+@display
+Copyright @copyright{} 1989 Free Software Foundation, Inc.
+675 Mass Ave, Cambridge, MA 02139, USA
-@item
-If you are an experienced user of debugging tools, your suggestions
-for improvement of GDB are welcome in any case.
-@end itemize
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
-@node Bug Reporting,, Bug Criteria, Bugs
-@section How to Report Bugs
-@cindex Bug Reports
-@cindex Compiler Bugs, Reporting
+@unnumberedsec Preamble
-@comment The following is meant to be neutral and helpful, not just a plug for
-@comment Cygnus; feedback on the issue (to "pesch@cygnus.com" or
-@comment "info@cygnus.com"---the latter will reach all of Cygnus)
-@comment is welcome.
-A number of companies and individuals offer support for GNU products.
-If you obtained GDB from a support organization, we recommend you
-contact that organization first.
+ The license agreements of most software companies try to keep users
+at the mercy of those companies. By contrast, our 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. The
+General Public License applies to the Free Software Foundation's
+software and to any other program whose authors commit to using it.
+You can use it for your programs, too.
-Among these organizations are Cygnus Support (Palo Alto CA, USA); C2V
-(Paris, France); Dynamix Corporation (King of Prussia PA, USA); The Nice
-Computer Company (Perth, Australia); Optimal Solutions (Seattle WA,
-USA); and The Pharos Group (Las Cruces NM, USA).
+ When we speak of free software, we are referring to freedom, not
+price. Specifically, the General Public License is designed to make
+sure that you have the freedom to give away or sell copies of free
+software, 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.
-Full contact information is in the file @samp{etc/SERVICE} in the GNU
-Emacs distribution. Numerous individual consultants are also listed
-there.
-@comment END NEUTRAL+HELPFUL section
+ 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.
-In any event, we also recommend that you send bug reports for GDB to one
-of these addresses:
+ For example, if you distribute copies of a 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 tell them their rights.
-@example
-bug-gdb@@prep.ai.mit.edu
-@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb
-@end example
+ 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.
-@strong{Do not send bug reports to @samp{info-gdb}, or to
-@samp{help-gdb}, or to any newsgroups.} Most users of GDB do not want to
-receive bug reports. Those that do, have asked to be on @samp{bug-gdb}.
+ 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.
-The mailing list @samp{bug-gdb} has a newsgroup 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 does not contain 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 precise terms and conditions for copying, distribution and
+modification follow.
-As a last resort, send bug reports on paper to:
+@iftex
+@unnumberedsec TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS
+@end ifinfo
-@example
-GNU Debugger Bugs
-545 Tech Sq
-Cambridge, MA 02139
-@end example
+@enumerate
+@item
+This License Agreement 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 work containing the
+Program or a portion of it, either verbatim or with modifications. Each
+licensee is addressed as ``you''.
-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!
+@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
+General Public License and to the absence of any warranty; and give any
+other recipients of the Program a copy of this General Public License
+along with the Program. You may charge a fee for the physical act of
+transferring a copy.
-Often people omit facts because they think they know what causes the
-problem and they conclude that some details don't matter. Thus, you might
-assume that the name of the variable you use in an example does not matter.
-Well, probably it doesn't, 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.
+@item
+You may modify your copy or copies of the Program or any portion of
+it, and copy and distribute such modifications under the terms of Paragraph
+1 above, provided that you also do the following:
-Keep in mind that the purpose of a bug report is to enable us to fix
-the bug if it is not known. It isn't very important what happens if
-the bug is already known. Therefore, always write your bug reports on
-the assumption that the bug is not known.
+@itemize @bullet
+@item
+cause the modified files to carry prominent notices stating that
+you changed the files and the date of any change; and
-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
+cause the whole of any work that you distribute or publish, that
+in whole or in part contains the Program or any part thereof, either
+with or without modifications, to be licensed at no charge to all
+third parties under the terms of this General Public License (except
+that you may choose to grant warranty protection to some or all
+third parties, at your option).
-To enable us to fix the bug, you should include all these things:
+@item
+If the modified program normally reads commands interactively when
+run, you must cause it, when started running for such interactive use
+in the simplest and most usual 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 General
+Public License.
-@itemize @bullet
@item
-The version of GDB. GDB announces it on startup; you can also print it
-at any time using @samp{info version}.
+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.
+@end itemize
-Without this, we won't know whether there is any point in looking for
-the bug in the current version of GDB.
+Mere aggregation of another independent work with the Program (or its
+derivative) on a volume of a storage or distribution medium does not bring
+the other work under the scope of these terms.
@item
-A complete input script, and all necessary source files, that will
-reproduce the bug.
+You may copy and distribute the Program (or a portion or derivative of
+it, under Paragraph 2) in object code or executable form under the terms of
+Paragraphs 1 and 2 above provided that you also do one of the following:
+@itemize @bullet
@item
-What compiler (and its version) was used to compile GDB---e.g.
-``GCC-1.37.1''.
+accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of
+Paragraphs 1 and 2 above; or,
@item
-What compiler (and its version) was used to compile GDB.
+accompany it with a written offer, valid for at least three
+years, to give any third party free (except for a nominal charge
+for the cost of distribution) a complete machine-readable copy of the
+corresponding source code, to be distributed under the terms of
+Paragraphs 1 and 2 above; or,
@item
-The command arguments you gave the compiler to compile that example and
-observe the bug. For example, did you use @samp{-O}? To guarantee
-you won't omit something important, list them all.
+accompany it with the information you received as to where the
+corresponding source code may be obtained. (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form alone.)
+@end itemize
-If we were to try to guess the arguments, we would probably guess wrong
-and then we would not encounter the bug.
+Source code for a work means the preferred form of the work for making
+modifications to it. For an executable file, complete source code means
+all the source code for all modules it contains; but, as a special
+exception, it need not include source code for modules which are standard
+libraries that accompany the operating system on which the executable
+file runs, or for standard header files or definitions files that
+accompany that operating system.
@item
-The type of machine you are using, and the operating system name and
-version number.
+You may not copy, modify, sublicense, distribute or transfer the
+Program except as expressly provided under this General Public License.
+Any attempt otherwise to copy, modify, sublicense, distribute or transfer
+the Program is void, and will automatically terminate your rights to use
+the Program under this License. However, parties who have received
+copies, or rights to use copies, from you under this General Public
+License will not have their licenses terminated so long as such parties
+remain in full compliance.
@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 GDB 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.
-
-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 GDB 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 @i{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.
+By copying, distributing or modifying 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.
@item
-If you wish to suggest changes to the GDB source, send us context
-diffs. If you even discuss something in the GDB source, refer to
-it by context, not by line number.
-
-The line numbers in our development sources don't match those in your
-sources. Your line numbers would convey no useful information to us.
+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.
-@end itemize
+@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.
-Here are some things that are not necessary:
+Each version is given a distinguishing version number. If the Program
+specifies a version number of the 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
+the license, you may choose any version ever published by the Free Software
+Foundation.
-@itemize @bullet
@item
-A description of the envelope of the bug.
+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.
-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.
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
-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
+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.
-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, etc.
+@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
-However, simplification is not vital; if you don't want to do this,
-report the bug anyway and send us the entire test case you used.
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
-@item
-A patch for the bug.
+@page
+@unnumberedsec How to Apply These Terms to Your New Programs
-A patch for the bug does help us if it is a good one. But don't 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.
+ If you develop a new program, and you want it to be of the greatest
+possible use to humanity, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
-Sometimes with a program as complicated as GDB it is very hard to
-construct an example that will make the program follow a certain path
-through the code. If you don't send us the example, we won't be able
-to construct one, so we won't be able to verify that the bug is fixed.
+ 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.
-And if we can't understand what bug you are trying to fix, or why your
-patch should be an improvement, we won't install it. A test case will
-help us to understand.
+@smallexample
+@var{one line to give the program's name and a brief idea of what it does.}
+Copyright (C) 19@var{yy} @var{name of author}
-@item
-A guess about what the bug is or what it depends on.
+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 1, or (at your option)
+any later version.
-Such guesses are usually wrong. Even we can't guess right about such
-things without first using the debugger to find the facts.
-@end itemize
+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.
-@iftex
-@include readline/inc-readline.texinfo
-@include readline/inc-history.texinfo
-@end iftex
+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
-@node Installing GDB, , ,Top
-@appendix Installing GDB
-@cindex configuring GDB
-@cindex installation
+Also add information on how to contact you by electronic and paper mail.
-The script @samp{config.gdb} automates the process of preparing GDB for
-installation; you can then use @samp{make} to actually build it. For
-example,
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
-@example
-config.gdb sun3os4
-make
-@end example
+@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
-@noindent
-is all that's required to install GDB on a Sun 3 running SunOS 4.
+The hypothetical commands `show w' and `show c' should show the
+appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than `show w' and `show
+c'; they could even be mouse-clicks or menu items---whatever suits your
+program.
-@table @code
-@kindex config.gdb
-@item config.gdb @var{machine}
-@itemx config.gdb +srcdir=@var{dir} @var{machine}
-This is the most usual way of configuring GDB; to debug programs running
-on the same machine as GDB itself. If you wish to build the GDB binaries
-in a completely different directory from the sources, specify a path to
-the source directory using the @samp{+srcdir} option.
+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:
-@item config.gdb +host
-@cindex host environments
-Display a list of supported host environments for GDB.
+@smallexample
+Yoyodyne, Inc., hereby disclaims all copyright interest in the
+program `Gnomovision' (a program to direct compilers to make passes
+at assemblers) written by James Hacker.
-@item config.gdb @var{host} @var{target}
-@itemx config.gdb +srcdir=@var{dir} @var{host} @var{target}
-@cindex cross-debugging
-GDB can also be used as a cross-debugger, running on a machine of one
-type while debugging a program running on a machine of another type.
-You configure it this way by specifying first the @var{host}, then the
-@var{target} environment on the @code{config.gdb} argument list; the
-@var{host} is where GDB runs, and the @var{target} is where your program
-runs. @xref{Remote}. Again, you can use @samp{+srcdir} to specify a
-path to the GDB source.
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end smallexample
-@item config.gdb +target
-@cindex target environments
-Display a list of supported target environments for GDB.
-@end table
+That's all there is to it!
-@node Commands, Concepts, Remote, Top
+@node Commands, Concepts, License, Top
@unnumbered Command Index
@printindex ky
-@node Concepts, , Commands, Top
+@node Concepts, , Commands, Top
@unnumbered Index
@printindex cp
projects / binutils-gdb.git / commitdiff