gdb

NAME

       gdb - The GNU Debugger

SYNOPSIS

       gdb    [-help] [-nx] [-q] [-batch] [-cd=dir] [-f] [-b bps]
              [-tty=dev] [-s symfile] [-e prog] [-se prog] [-c
              core] [-x cmds] [-d dir] [prog[core|procID]]

DESCRIPTION

       The  purpose  of a debugger such as GDB is to allow you to
       see what is going on ``inside'' another program  while  it
       executes--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:


          o   Start  your program, specifying anything that might
              affect its behavior.


          o   Make your program stop on specified conditions.


          o   Examine what has happened, when  your  program  has
              stopped.


          o   Change  things  in your program, so you can experi-
              ment with correcting the effects of one bug and  go
              on to learn about another.


       You  can  use GDB to debug programs written in C, C++, and
       Modula-2.  Fortran support will be added when a  GNU  For-
       tran compiler is ready.

       GDB  is invoked with the shell command gdb.  Once started,
       it reads commands from the terminal until you tell  it  to
       exit  with  the GDB command quit.  You can get online help
       from gdb itself by using the command help.

       You can run gdb with no arguments or options; but the most
       usual way to start GDB is with one argument or two, speci-
       fying an executable program as the argument:

       gdb program


       You can also start with both an executable program  and  a
       core file specified:

       gdb program core
       You  can,  instead, specify a process ID as a second argu-
       ment, if you want to debug a running process:

       gdb program 1234


       would attach GDB to process 1234 (unless you also  have  a
       file  named `1234'; GDB does check for a core file first).

       Here are some of the most frequently needed GDB commands:

       break [file:]function
               Set a breakpoint at function (in file).

       run [arglist]
              Start your program (with arglist, if specified).

       bt     Backtrace: display the program stack.

       print expr
               Display the value of an expression.

       c      Continue running your program (after stopping, e.g.
              at a breakpoint).

       next   Execute  next  program  line (after stopping); step
              over any function calls in the line.

       step   Execute next program line  (after  stopping);  step
              into any function calls in the line.

       help [name]
              Show information about GDB command name, or general
              information about using GDB.

       quit   Exit from GDB.

       For full details on GDB, see Using GDB: A Guide to the GNU
       Source-Level  Debugger,  by Richard M. Stallman and Roland
       H. Pesch.  The same text is available online  as  the  gdb
       entry in the info program.

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 `-se' option, and the second, if  any,  is
       equivalent  to  a  `-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 `+' rather than `-', 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  differ-
       ence when the `-x' option is used.


       -help

       -h     List all options, with brief explanations.


       -symbols=file

       -s file
               Read symbol table from file file.


       -exec=file

       -e file
                Use  file  file as the executable file to execute
              when appropriate, and for examining  pure  data  in
              conjunction with a core dump.


       -se=file
               Read symbol table from file file and use it as the
              executable file.


       -core=file

       -c file
               Use file file as a core dump to examine.


       -command=file

       -x file
               Execute GDB commands from file file.


       -directory=directory

       -d directory
               Add directory to the path  to  search  for  source
              files.



       -nx

       -n     Do  not  execute  commands from any `.gdbinit' ini-
              tialization files.  Normally, the commands in these
              files  are  executed  after all the command options
              and arguments have been processed.



       -quiet

       -q     ``Quiet''.  Do not print the introductory and copy-
              right messages.  These messages are also suppressed
              in batch mode.


       -batch Run in batch mode.  Exit with status 0  after  pro-
              cessing  all  the command files specified with `-x'
              (and `.gdbinit',  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  fil-
              ter,  for  example to download and run a program on
              another computer; in order to make this  more  use-
              ful, the message

              Program exited normally.


              (which is ordinarily issued whenever a program run-
              ning under GDB control terminates)  is  not  issued
              when running in batch mode.


       -cd=directory
                Run GDB using directory as its working directory,
              instead of the current directory.


       -fullname

       -f     Emacs sets this option when it runs GDB as  a  sub-
              process.  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 recog-
              nizable  format  looks  like  two ` 32' characters,
              followed by the file name, line number and  charac-
              ter  position  separated  by colons, and a newline.
              The Emacs-to-GDB interface  program  uses  the  two
              ` 32'  characters as a signal to display the source
              code for the frame.


       -b bps  Set the line speed (baud rate or bits per  second)
              of  any  serial  interface  used  by GDB for remote
              debugging.

       -tty=device
               Run using device for your program's standard input
              and output.

SEE ALSO

       `gdb' entry in info; Using GDB: A Guide to the GNU Source-
       Level Debugger, Richard M. Stallman and Roland  H.  Pesch,
       July 1991.

COPYING

       Copyright (c) 1991 Free Software Foundation, Inc.

       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.

       Permission is granted to copy and distribute modified ver-
       sions 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.

       Permission  is granted to copy and distribute translations
       of this manual into another language, under the above con-
       ditions 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.