gdb

Debugger (GNU)

Syntax:

gdb_variant [options] [executable] [ core_file | pid ]

Options:

The gdb_variant depends on the target platform, as follows:

The options are:

-[no]async

Enable (disable) asynchronous version of CLI.

-b bps

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

-batch

Run in batch mode. Exit with status 0 after processing all the command files specified with -x (and all commands from initialization files, if not inhibited with -n). 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. To make this more useful, the message:

Program exited normally.

(which is ordinarily issued whenever a program running under gdb control terminates) isn't issued when running in batch mode.

-cd=directory

Run gdb using directory as its working directory, instead of the current directory.

-command=file

Execute gdb commands from file. See "Command files" in the full online GNU documentation.

-core=file

Examine file as a core dump.

-dbx

DBX compatibility mode.

-directory=directory

Add directory to the path to search for source files.

-epoch

Output information used by epoch emacs-GDB interface.

-exec=file

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

-fullname

GNU Emacs sets this option when it runs gdb as a subprocess. It tells gdb to output the full filename and line number in a standard, recognizable fashion each time a stack frame is displayed (which includes each time your 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.

-help

Display all available options and briefly describe their use.

-interpreter=file

Select a specific interpreter or user interface.

-mapped

Use mapped symbol files if supported on this system.

---

This option depends on operating system facilities that aren't supported on all systems.

---

If memory-mapped files are available on your system through the mmap() system call, you can use this option to have gdb write the symbols from your program into a reusable file in the current directory.

For example, if the program you're debugging is called /tmp/fred, the mapped symbol file is ./fred.syms. Future gdb debugging sessions notice the presence of this file, and can quickly map in symbol information from it, rather than read the symbol table from the executable program.

The .syms file is specific to the host machine where gdb is run. It holds an exact image of the internal gdb symbol table. It can't be shared across multiple host platforms.

-nw

Do not use a window interface.

-nx

Don't execute commands from any initialization files (normally called .gdbinit). If you don't specify this option, these .gdbinit files are executed before any command-line options and arguments have been processed.

For more information on initialization files, see "Command files" in the full online GNU documentation.

-quiet

Don't print the introductory and copyright messages. These messages are also suppressed in batch mode.

-readnow

Read each symbol file's entire symbol table immediately, rather than read it incrementally as needed. This makes startup slower, but makes future operations faster.

The -mapped and -readnow options are typically combined in order to build a .syms file that contains complete symbol information. (For more information, see "Commands to specify files" in the full online GNU documentation.)

Here's how you can build a .syms file for future use:

gdb -batch -nx -mapped -readnow programname

-se=file

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

-symbols=file

Read the symbol table from the file file.

-tty=device

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

-version

Print version information and then exit.

-w

Use a window interface.

-write

Set writing into executable and core files.

-xdb

XDB compatibility mode.

Description:

Invoke the GNU Debugger by running gdb. Once started, gdb reads commands from the terminal until you tell it to exit.

You can abbreviate a gdb command to the first few letters of the command name, if that abbreviation is unambiguous; and you can repeat certain gdb commands by typing just Enter. You can also use the Tab key to get gdb to fill out the rest of a word in a command (or to show you the alternatives available, if there's more than one possibility).

You can also run gdb with a variety of arguments and options, to specify more of your debugging environment at the outset.

Unless you specify the -nx option, this utility runs commands in an initialization file before running any command-line options. This file may be specific to the gdb_variant invoked, for instance, if you invoke ntomips-gdb, the utility runs the commands in the ${HOME}/.ntomips-gdbinit file. If no such gdb_variant initialization file exists, the utility runs commands found in the generic ${HOME}/.gdbinit file instead. If you specify -command, file overrides these default files.

The command-line options described here are designed to cover a variety of situations; in some environments, some of these options might not work.

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

gdb program core

Author:

GNU

See also:

Using GDB in the Programmer's Guide