# gdb

## NAME



           gdb - The GNU Debugger
    


## SYNOPSIS



           gdb [OPTIONS] [_prog_ |_prog procID_ |_prog core_]
    


## 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:
    
           •   Start your program, specifying anything that might affect its
               behavior.
    
           •   Make your program stop on specified conditions.
    
           •   Examine what has happened, when your program has stopped.
    
           •   Change things in your program, so you can experiment 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++, Fortran and
           Modula-2.
    
           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" or "exit".  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, specifying 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 argument or use
           option "-p", if you want to debug a running process:
    
                   gdb program 1234
                   gdb -p 1234
    
           would attach GDB to process 1234.  With option **-p** you can omit the
           _program_ filename.
    
           Here are some of the most frequently needed GDB commands:
    
           **break [**_file_**:][**_function_**|**_line_**]**
               Set a breakpoint at _function_ or _line_ (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.
    
           **edit [**_file_**:]**_function_
               look at the program line where it is presently stopped.
    
           **list [**_file_**:]**_function_
               type the text of the program in the vicinity of where it is
               presently stopped.
    
           **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**
               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 abbreviated 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.
    
           The abbreviated forms are shown here with **-** and long forms are
           shown with **--** to reflect how they are shown in **--help**. However,
           GDB recognizes all of the following conventions for most options:
    
           "--option=_value_ "
           "--option _value_ "
           "-option=_value_ "
           "-option _value_ "
           "--o=_value_ "
           "--o _value_ "
           "-o=_value_ "
           "-o _value_ "
    
           All the options and command line arguments you give are processed
           in sequential order.  The order makes a difference when the **-x**
           option is used.
    
           **--help**
           **-h** List all options, with brief explanations.
    
           **--symbols=**_file_
           **-s** _file_
               Read symbol table from _file_.
    
           **--write**
               Enable writing into executable and core files.
    
           **--exec=**_file_
           **-e** _file_
               Use _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_ and use it as the executable file.
    
           **--core=**_file_
           **-c** _file_
               Use _file_ as a core dump to examine.
    
           **--command=**_file_
           **-x** _file_
               Execute GDB commands from _file_.
    
           **--eval-command=**_command_
           **-ex** _command_
               Execute given GDB _command_.
    
           **--init-eval-command=**_command_
           **-iex**
               Execute GDB _command_ before loading the inferior.
    
           **--directory=**_directory_
           **-d** _directory_
               Add _directory_ to the path to search for source files.
    
           **--nh**
               Do not execute commands from _~/.config/gdb/gdbinit_ ,
               _~/.gdbinit_ , _~/.config/gdb/gdbearlyinit_ , or _~/.gdbearlyinit_
    
           **--nx**
           **-n** Do not execute commands from any _.gdbinit_ or _.gdbearlyinit_
               initialization files.
    
           **--quiet**
           **--silent**
           **-q** "Quiet".  Do not print the introductory and copyright
               messages.  These messages are also suppressed in batch mode.
    
           **--batch**
               Run in batch mode.  Exit with status 0 after processing 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 filter, for
               example to download and run a program on another computer; in
               order to make this more useful, the message
    
                       Program exited normally.
    
               (which is ordinarily issued whenever a program running under
               GDB control terminates) is not issued when running in batch
               mode.
    
           **--batch-silent**
               Run in batch mode, just like **--batch** , but totally silent.  All
               GDB output is suppressed (stderr is unaffected).  This is much
               quieter than **--silent** and would be useless for an interactive
               session.
    
               This is particularly useful when using targets that give
               **Loading section** messages, for example.
    
               Note that targets that give their output via GDB, as opposed
               to writing directly to "stdout", will also be made silent.
    
           **--args** _prog_ **[**_arglist_**]**
               Change interpretation of command line so that arguments
               following this option are passed as arguments to the inferior.
               As an example, take the following command:
    
                       gdb ./a.out -q
    
               It would start GDB with **-q** , not printing the introductory
               message.  On the other hand, using:
    
                       gdb --args ./a.out -q
    
               starts GDB with the introductory message, and passes the
               option to the inferior.
    
           **--pid=**_pid_
               Attach GDB to an already running program, with the PID _pid_.
    
           **--tui**
               Open the terminal user interface.
    
           **--readnow**
               Read all symbols from the given symfile on the first access.
    
           **--readnever**
               Do not read symbol files.
    
           **--return-child-result**
               GDB's exit code will be the same as the child's exit code.
    
           **--configuration**
               Print details about GDB configuration and then exit.
    
           **--version**
               Print version information and then exit.
    
           **--cd=**_directory_
               Run GDB using _directory_ as its working directory, instead of
               the current directory.
    
           **--data-directory=**_directory_
           **-D** Run GDB using _directory_ as its data directory.  The data
               directory is where GDB searches for its auxiliary files.
    
           **--fullname**
           **-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 **\032** 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 **\032** characters as a signal to display the source
               code for the frame.
    
           **-b** _baudrate_
               Set the line speed (baud rate or bits per second) of any
               serial interface used by GDB for remote debugging.
    
           **-l** _timeout_
               Set timeout, in seconds, for remote debugging.
    
           **--tty=**_device_
               Run using _device_ for your program's standard input and output.
    


## ENVIRONMENT



    


* * *