Debugging with GDB: Man Pages

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# K. Manual pages

> gdb man |  | The GNU Debugger man page
> gdbserver man |  | Remote Server for the GNU Debugger man page
> gcore |  | Generate a core file of a running program
> gdbinit |  | gdbinit scripts

## gdb man

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

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`. 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, if you want to debug a running process:

    gdb program 1234
    gdb -p 1234

would attach GDB to process `1234` (unless you also have a file named ``1234'`; GDB does check for a core file first). With option ``-p'` you can omit the program filename.

Here are some of the most frequently needed GDB commands:

`break [file:]functiop`
  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.

`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 from GDB.

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 difference when the ``-x'` option is used.

`-help`
`-h`
  List all options, with brief explanations.

`-symbols=file`
`-s file`
  Read symbol table from file file.

`-write`
  Enable writing into executable and core files.

`-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.

`-ex command`
  Execute given GDB command.

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

`-nh`
  Do not execute commands from ``~/.gdbinit'`.

`-nx`
`-n`
  Do not execute commands from any ``.gdbinit'` initialization files.

`-quiet`
`-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.

`-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 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 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.

## gdbserver man

    gdbserver comm prog [args...]

    gdbserver --attach comm pid

    gdbserver --multi comm

`gdbserver` is a program that allows you to run GDB on a different machine than the one which is running the program being debugged.

### Usage (server (target) side)

First, you need to have a copy of the program you want to debug put onto the target system. The program can be stripped to save space if needed, as `gdbserver` doesn't care about symbols. All symbol handling is taken care of by the GDB running on the host system.

To use the server, you log on to the target system, and run the `gdbserver` program. You must tell it (a) how to communicate with GDB, (b) the name of your program, and (c) its arguments. The general syntax is:

    target> gdbserver comm program [args ...]

For example, using a serial port, you might say:

    target> gdbserver `/dev/com1' emacs foo.txt

This tells `gdbserver` to debug emacs with an argument of foo.txt, and to communicate with GDB via ``/dev/com1'`. `gdbserver` now waits patiently for the host GDB to communicate with it.

To use a TCP connection, you could say:

    target> gdbserver host:2345 emacs foo.txt

This says pretty much the same thing as the last example, except that we are going to communicate with the `host` GDB via TCP. The `host:2345` argument means that we are expecting to see a TCP connection from `host` to local TCP port 2345. (Currently, the `host` part is ignored.) You can choose any number you want for the port number as long as it does not conflict with any existing TCP ports on the target system. This same port number must be used in the host GDBs `target remote` command, which will be described shortly. Note that if you chose a port number that conflicts with another service, `gdbserver` will print an error message and exit.

`gdbserver` can also attach to running programs. This is accomplished via the ``--attach'` argument. The syntax is:

    target> gdbserver --attach comm pid

pid is the process ID of a currently running process. It isn't necessary to point `gdbserver` at a binary for the running process.

To start `gdbserver` without supplying an initial command to run or process ID to attach, use the ``--multi'` command line option. In such case you should connect using `target extended-remote` to start the program you want to debug.

    target> gdbserver --multi comm

### Usage (host side)

You need an unstripped copy of the target program on your host system, since GDB needs to examine it's symbol tables and such. Start up GDB as you normally would, with the target program as the first argument. (You may need to use the ``--baud'` option if the serial line is running at anything except 9600 baud.) That is `gdb TARGET-PROG`, or `gdb --baud BAUD TARGET-PROG`. After that, the only new command you need to know about is `target remote` (or `target extended-remote`). Its argument is either a device name (usually a serial device, like ``/dev/ttyb'`), or a `HOST:PORT` descriptor. For example:

    (gdb) target remote `/dev/ttyb'

communicates with the server via serial line ``/dev/ttyb'`, and:

    (gdb) target remote the-target:2345

communicates via a TCP connection to port 2345 on host `the-target', where you previously started up `gdbserver` with the same port number. Note that for TCP connections, you must start up `gdbserver` prior to using the `target remote' command, otherwise you may get an error that looks something like `Connection refused'.

`gdbserver` can also debug multiple inferiors at once, described in 4.9 Debugging Multiple Inferiors and Programs. In such case use the `extended-remote` GDB command variant:

    (gdb) target extended-remote the-target:2345

The `gdbserver` option ``--multi'` may or may not be used in such case.

There are three different modes for invoking `gdbserver`:

- Debug a specific program specified by its program name:

      gdbserver comm prog [args...]

  The comm parameter specifies how should the server communicate with GDB; it is either a device name (to use a serial line), a TCP port number (`:1234`), or `-` or `stdio` to use stdin/stdout of `gdbserver`. Specify the name of the program to debug in prog. Any remaining arguments will be passed to the program verbatim. When the program exits, GDB will close the connection, and `gdbserver` will exit.

- Debug a specific program by specifying the process ID of a running program:

      gdbserver --attach comm pid

  The comm parameter is as described above. Supply the process ID of a running program in pid; GDB will do everything else. Like with the previous mode, when the process pid exits, GDB will close the connection, and `gdbserver` will exit.

- Multi-process mode -- debug more than one program/process:

      gdbserver --multi comm

  In this mode, GDB can instruct `gdbserver` which command(s) to run. Unlike the other 2 modes, GDB will not close the connection when a process being debugged exits, so you can debug several processes in the same session.

In each of the modes you may specify these options:

`--help`
  List all options, with brief explanations.

`--version`
  This option causes `gdbserver` to print its version number and exit.

`--attach`
  `gdbserver` will attach to a running program. The syntax is:

      target> gdbserver --attach comm pid

  pid is the process ID of a currently running process. It isn't necessary to point `gdbserver` at a binary for the running process.

`--multi`
  To start `gdbserver` without supplying an initial command to run or process ID to attach, use this command line option. Then you can connect using `target extended-remote` and start the program you want to debug. The syntax is:

      target> gdbserver --multi comm

`--debug`
  Instruct `gdbserver` to display extra status information about the debugging process. This option is intended for `gdbserver` development and for bug reports to the developers.

`--remote-debug`
  Instruct `gdbserver` to display remote protocol debug output. This option is intended for `gdbserver` development and for bug reports to the developers.

`--wrapper`
  Specify a wrapper to launch programs for debugging. The option should be followed by the name of the wrapper, then any command-line arguments to pass to the wrapper, then `--` indicating the end of the wrapper arguments.

`--once`
  By default, `gdbserver` keeps the listening TCP port open, so that additional connections are possible. However, if you start `gdbserver` with the ``--once'` option, it will stop listening for any further connection attempts after connecting to the first GDB session.

## gcore

    gcore [-o filename] pid

Generate a core dump of a running program with process ID pid. Produced file is equivalent to a kernel produced core file as if the process crashed (and if `ulimit -c` were used to set up an appropriate core dump limit). Unlike after a crash, after `gcore` the program remains running without any change.

`-o filename`
  The optional argument filename specifies the file name where to put the core dump. If not specified, the file name defaults to ``core.pid'`, where pid is the running program process ID.

## gdbinit

    ~/.gdbinit

    ./.gdbinit

These files contain GDB commands to automatically execute during GDB startup. The lines of contents are canned sequences of commands, described in 23.1 Canned Sequences of Commands.

Please read more in 2.1.3 What GDB Does During Startup.

`(not enabled with `--with-system-gdbinit` during compilation)`
  System-wide initialization file. It is executed unless user specified GDB option `-nx` or `-n`. See more in C.6 System-wide configuration and settings.

`~/.gdbinit`
  User initialization file. It is executed unless user specified GDB options `-nx`, `-n` or `-nh`.

`./.gdbinit`
  Initialization file for current directory. It may need to be enabled with GDB security command `set auto-load local-gdbinit`. See more in 22.7.1 Automatically loading init file in the current directory.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html