X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fgdb.1;h=f3f4bdb2ffd55a12fad6aa3436c53598313cb430;hb=b44e9041564f8b446bab9175540999d7930b8f84;hp=11a42a6996007ccdfbf5668d859e5bda49b3f6f1;hpb=7b4ac7e1ed2c4616bce56d1760807798be87ac9e;p=deliverable%2Fbinutils-gdb.git

diff --git a/gdb/gdb.1 b/gdb/gdb.1
index 11a42a6996..f3f4bdb2ff 100644
--- a/gdb/gdb.1
+++ b/gdb/gdb.1
@@ -1,91 +1,381 @@
-.TH GDB 1 "13 April 1987"
-.UC 4
+.\" Copyright 1991, 1999 Free Software Foundation, Inc.
+.\" See section COPYING for conditions for redistribution
+.\" $Id$
+.TH gdb 1 "22may2002" "GNU Tools" "GNU Tools"
 .SH NAME
-gdb \- Project GNU's DeBugger
+gdb \- The GNU Debugger
 .SH SYNOPSIS
-\fBgdb\fP [ \fBoptions\fP ]   See documentation mentioned below.
+.na
+.TP
+.B gdb
+.RB "[\|" \-help "\|]"
+.RB "[\|" \-nx "\|]"
+.RB "[\|" \-q "\|]"
+.RB "[\|" \-batch "\|]"
+.RB "[\|" \-cd=\c
+.I dir\c
+\|]
+.RB "[\|" \-f "\|]"
+.RB "[\|" "\-b\ "\c
+.IR bps "\|]"
+.RB "[\|" "\-tty="\c
+.IR dev "\|]"
+.RB "[\|" "\-s "\c
+.I symfile\c
+\&\|]
+.RB "[\|" "\-e "\c
+.I prog\c
+\&\|]  
+.RB "[\|" "\-se "\c
+.I prog\c
+\&\|]
+.RB "[\|" "\-c "\c
+.I core\c
+\&\|]
+.RB "[\|" "\-x "\c
+.I cmds\c
+\&\|]
+.RB "[\|" "\-d "\c
+.I dir\c
+\&\|]
+.RB "[\|" \c
+.I prog\c
+.RB "[\|" \c
+.IR core \||\| procID\c
+\&\|]\&\|]
+.ad b
 .SH DESCRIPTION
-\fIgdb\fP is a source level symbolic debugger for C programs, created by
-Richard M. Stallman (rms) for the GNU Project, and distributed by the
-Free Software Foundation.  Eventually GNU (Gnu's Not Unix) will be a
-complete replacement for Berkeley Unix, all of which everyone will be
-able to use freely.  See the \fIGNU Emacs\fP man page for pointers to more
-information.
-.PP
-\fIgdb\fP has something of the flavor of \fIdbx\fP,
-but has more features and power.  It can also be used to debug o/s
-kernels, but needs to be configured differently for that task.
-.PP
-Project GNU isn't using Unix man pages.  Its style of complete
-documentation can be found by:
-.PP
-The help and info commands inside \fIgdb\fP.
-.PP
-In the Info system in \fIGNU Emacs\fP.  Type C-h i, and follow the
-directions.  This is equivalent to the reference manual for 
-\fIgdb\fP, and has about 55 pages of text.
+The purpose of a debugger such as GDB is to allow you to see what is
+going on ``inside'' another program while it executes\(em\&or what another
+program was doing at the moment it crashed.
+
+GDB can do four main kinds of things (plus other things in support of
+these) to help you catch bugs in the act:
+
+.TP
+\ \ \ \(bu
+Start your program, specifying anything that might affect its behavior.
+
+.TP
+\ \ \ \(bu
+Make your program stop on specified conditions.
+
+.TP
+\ \ \ \(bu
+Examine what has happened, when your program has stopped.
+
+.TP
+\ \ \ \(bu
+Change things in your program, so you can experiment with correcting the
+effects of one bug and go on to learn about another.
 .PP
-\fIgdb\fP could be extended to work with other languages (e.g. Pascal) and
-machines (e.g. encores).  If you like, copy the sources and give it a
-try.  When you have it working send \fIdiff -c\fP's of the changed files to
-bug-gdb@prep.ai.mit.edu (fuller details below), so they can benefit everyone.
-.SH DISTRIBUTION
-\fIgdb\fP is free; anyone may redistribute copies of
-\fIgdb\fP to anyone under the terms stated in the
-\fIgdb\fP General Public License, a copy of which accompanies each copy of
-\fIgdb\fP, is readable with the info command inside \fIgdb\fP,
-and which also appears in the \fIgdb\fP reference manual.
+
+You can use GDB to debug programs written in C, C++, and Modula-2.
+Fortran support will be added when a GNU Fortran compiler is ready.
+
+GDB is invoked with the shell command \c
+.B gdb\c
+\&.  Once started, it reads
+commands from the terminal until you tell it to exit with the GDB
+command \c
+.B quit\c
+\&.  You can get online help from \c
+.B gdb\c
+\& itself
+by using the command \c
+.B help\c
+\&.
+
+You can run \c
+.B gdb\c
+\& with no arguments or options; but the most
+usual way to start GDB is with one argument or two, specifying an
+executable program as the argument:
+.sp
+.br
+gdb\ program
+.br
+.sp
+
+You can also start with both an executable program and a core file specified:
+.sp
+.br
+gdb\ program\ core
+.br
+.sp
+
+You can, instead, specify a process ID as a second argument, if you want
+to debug a running process:
+.sp
+.br
+gdb\ program\ 1234
+.br
+.sp
+
+would attach GDB to process \c
+.B 1234\c
+\& (unless you also have a file
+named `\|\c
+.B 1234\c
+\&\|'; GDB does check for a core file first).
+
+Here are some of the most frequently needed GDB commands:
+.TP
+.B break \fR[\|\fIfile\fB:\fR\|]\fIfunction
+\&
+Set a breakpoint at \c
+.I function\c
+\& (in \c
+.I file\c
+\&).
+.TP
+.B run \fR[\|\fIarglist\fR\|]
+Start your program (with \c
+.I arglist\c
+\&, if specified).
+.TP
+.B bt
+Backtrace: display the program stack.
+.TP
+.BI print " expr"\c
+\&
+Display the value of an expression.
+.TP
+.B c
+Continue running your program (after stopping, e.g. at a breakpoint).
+.TP
+.B next
+Execute next program line (after stopping); step \c
+.I over\c
+\& any
+function calls in the line.
+.TP
+.B edit \fR[\|\fIfile\fB:\fR\|]\fIfunction
+look at the program line where it is presently stopped.
+.TP
+.B list \fR[\|\fIfile\fB:\fR\|]\fIfunction
+type the text of the program in the vicinity of where it is presently stopped.
+.TP
+.B step
+Execute next program line (after stopping); step \c
+.I into\c
+\& any
+function calls in the line.
+.TP
+.B help \fR[\|\fIname\fR\|]
+Show information about GDB command \c
+.I name\c
+\&, or general information
+about using GDB.
+.TP
+.B quit
+Exit from GDB.
 .PP
-Copies of \fIgdb\fP may sometimes be received packaged with
-distributions of Unix systems, but it is never included in the scope
-of any license covering those systems.  Such inclusion would violate
-the terms on which distribution is permitted.  In fact, the primary
-purpose of the General Public License is to prohibit anyone from
-attaching any other restrictions to redistribution of \fIgdb\fP.
+For full details on GDB, see \c
+.I 
+Using GDB: A Guide to the GNU Source-Level Debugger\c
+\&, by Richard M. Stallman and Roland H. Pesch.  The same text is available online
+as the \c
+.B gdb\c
+\& entry in the \c
+.B info\c
+\& program.
+.SH OPTIONS
+Any arguments other than options specify an executable
+file and core file (or process ID); that is, the first argument
+encountered with no 
+associated option flag is equivalent to a `\|\c
+.B \-se\c
+\&\|' option, and the
+second, if any, is equivalent to a `\|\c
+.B \-c\c
+\&\|' option if it's the name of a file.  Many options have
+both long and short forms; both are shown here.  The long forms are also
+recognized if you truncate them, so long as enough of the option is
+present to be unambiguous.  (If you prefer, you can flag option
+arguments with `\|\c
+.B +\c
+\&\|' rather than `\|\c
+.B \-\c
+\&\|', though we illustrate the
+more usual convention.)
+
+All the options and command line arguments you give are processed
+in sequential order.  The order makes a difference when the
+`\|\c
+.B \-x\c
+\&\|' option is used.
+
+.TP
+.B \-help
+.TP
+.B \-h
+List all options, with brief explanations.
+
+.TP
+.BI "\-symbols=" "file"\c
+.TP
+.BI "\-s " "file"\c
+\&
+Read symbol table from file \c
+.I file\c
+\&.
+
+.TP
+.B \-write
+Enable writing into executable and core files.
+
+.TP
+.BI "\-exec=" "file"\c
+.TP
+.BI "\-e " "file"\c
+\&
+Use file \c
+.I file\c
+\& as the executable file to execute when
+appropriate, and for examining pure data in conjunction with a core
+dump.
+
+.TP
+.BI "\-se=" "file"\c
+\&
+Read symbol table from file \c
+.I file\c
+\& and use it as the executable
+file.
+
+.TP
+.BI "\-core=" "file"\c
+.TP
+.BI "\-c " "file"\c
+\&
+Use file \c
+.I file\c
+\& as a core dump to examine.
+
+.TP
+.BI "\-command=" "file"\c
+.TP
+.BI "\-x " "file"\c
+\&
+Execute GDB commands from file \c
+.I file\c
+\&.  
+
+.TP
+.BI "\-directory=" "directory"\c
+.TP
+.BI "\-d " "directory"\c
+\&
+Add \c
+.I directory\c
+\& to the path to search for source files.
 .PP
-You can order printed copies of the \fIgdb\fP reference manual for $10.00/copy
-postpaid from the Free Software Foundation, which develops GNU software
-(contact them for quantity prices on the manual).  Their address is:
-.nf
-    Free Software Foundation
-    1000 Mass Ave.
-    Cambridge, MA  02138
-.fi
-As with all software and publications from FSF, everyone is permitted to
-make and distribute copies of the \fIgdb\fP reference manual.
-The TeX source to the \fIgdb\fP reference
-manual is also included in the \fIGNU Emacs\fP source distribution.
+
+.TP
+.B \-nx
+.TP
+.B \-n
+Do not execute commands from any `\|\c
+.B .gdbinit\c
+\&\|' initialization files.
+Normally, the commands in these files are executed after all the
+command options and arguments have been processed.
+
+
+.TP
+.B \-quiet
+.TP
+.B \-q
+``Quiet''.  Do not print the introductory and copyright messages.  These
+messages are also suppressed in batch mode.
+
+.TP
+.B \-batch
+Run in batch mode.  Exit with status \c
+.B 0\c
+\& after processing all the command
+files specified with `\|\c
+.B \-x\c
+\&\|' (and `\|\c
+.B .gdbinit\c
+\&\|', if not inhibited).
+Exit with nonzero status if an error occurs in executing the GDB
+commands in the command files.
+
+Batch mode may be useful for running GDB as a filter, for example to
+download and run a program on another computer; in order to make this
+more useful, the message
+.sp
+.br
+Program\ exited\ normally.
+.br
+.sp
+
+(which is ordinarily issued whenever a program running under GDB control
+terminates) is not issued when running in batch mode.
+
+.TP
+.BI "\-cd=" "directory"\c
+\&
+Run GDB using \c
+.I directory\c
+\& as its working directory,
+instead of the current directory.
+
+.TP
+.B \-fullname
+.TP
+.B \-f
+Emacs sets this option when it runs GDB as a subprocess.  It tells GDB
+to output the full file name and line number in a standard,
+recognizable fashion each time a stack frame is displayed (which
+includes each time the program stops).  This recognizable format looks
+like two `\|\c
+.B \032\c
+\&\|' characters, followed by the file name, line number
+and character position separated by colons, and a newline.  The
+Emacs-to-GDB interface program uses the two `\|\c
+.B \032\c
+\&\|' characters as
+a signal to display the source code for the frame.
+
+.TP
+.BI "\-b " "bps"\c
+\&
+Set the line speed (baud rate or bits per second) of any serial
+interface used by GDB for remote debugging.
+
+.TP
+.BI "\-tty=" "device"\c
+\&
+Run using \c
+.I device\c
+\& for your program's standard input and output.
 .PP
-.SH OPTIONS
-See documentation.
-.SH EXAMPLES
-See documentation.
+
 .SH "SEE ALSO"
-adb(1), sdb(1), dbx(1)
-.SH BUGS
-There is a mailing list, bug-gdb@prep.ai.mit.edu on the internet
-(ucbvax!prep.ai.mit.edu!bug-gdb on UUCPnet), for reporting \fIgdb\fP
-bugs and fixes.  But before reporting something as a bug, please try
-to be sure that it really is a bug, not a misunderstanding or a
-deliberate feature.  We ask you to read the section ``Reporting Emacs
-Bugs'' near the end of the \fIGNU Emacs\fP reference manual
-(or Info system) for hints
-on how and when to report bugs.  Also, include the version number of
-the \fIgdb\fP you are running in \fIevery\fR bug report that you send in.
+.RB "`\|" gdb "\|'"
+entry in
+.B info\c
+\&;
+.I 
+Using GDB: A Guide to the GNU Source-Level Debugger\c
+, Richard M. Stallman and Roland H. Pesch, July 1991.
+.SH COPYING
+Copyright (c) 1991 Free Software Foundation, Inc.
 .PP
-Do not expect a personal answer to a bug report.  The purpose of reporting
-bugs is to get them fixed for everyone in the next release, if possible.
-For personal assistance, look in the SERVICE file
-(see the \fIGNU Emacs\fP man page) for
-a list of people who offer it.
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
 .PP
-Please do not send anything but bug reports to this mailing list.
-Send other stuff to gnu@prep.ai.mit.edu (or the
-corresponding UUCP address).  For more information about GNU mailing
-lists, see the file MAILINGLISTS (see the \fIGNU Emacs\fP man page).  Bugs tend
-actually to be fixed if they can be isolated, so it is in your
-interest to report them in such a way that they can be easily
-reproduced.
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
 .PP
-No bugs are known at this time.
-
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be included in
+translations approved by the Free Software Foundation instead of in
+the original English.