Previous Page
Next Page

20.3. Starting GDB

You can start GDB by entering gdb at the shell command prompt. GDB supports numerous command-line options and arguments:

gdb [options] [executable_file [core_file | process_id]]

For example, the following command starts the debugger without displaying its sign-on message:

$ gdb -silent

In this example, the command line does not name the executable file to be debugged. You can specify the program you want to test in GDB using the debugger's file command, described in the section "Using GDB Commands," later in this chapter.

20.3.1. Command-Line Arguments

Ordinarily, the program to be debugged is named on the GDB command line. In the following example, the GDB command loads the executable myprog for debugging:

$ gdb myprog

As an additional argument after the name of the program to be tested, you may specify a process ID number or the name of a core dump file. In the following example, the number after the program name is a process ID (or "PID"):

$ gdb myprog 1001

This command instructs GDB to connect to a process that is already running on the system, and has the program name myprog and the process ID 1001. If GDB finds such a process, you can interrupt its execution to begin debugging by pressing Ctrl+C. If the debugger finds a file in the current working directory named 1001, however, it will interpret that argument as the name of a core file rather than a process ID. For details about debugging with core files, see the section "Analyzing Core Files in GDB ," at the end of this chapter.

20.3.2. Command-Line Options

Most of the command-line options for the GDB debugger have both short and long forms. The descriptions in the following list and subsections show both forms for the most frequently used options. You can also truncate the long form, if you type enough of it to be unambiguous. For options that take an argument, such as -tty device, the option and its argument can be separated either by a space or by an equals sign (=), as in -tty=/dev/tty6. Options may be introduced by either one or two hyphens: -quiet for example is synonymous with --quiet.

This section lists the most commonly used GDB options. For a complete list, see the program's documentation.

--version, -v

GDB prints its version and copyright information to the console and then exits, without starting a debugging session.

--quiet, --silent

GDB starts an interactive session without displaying its version and copyright information.

--help, -h

GDB displays its command-line syntax with a brief description of all the options, then exits without starting a debugging session. Passing arguments to the program being debugged

GDB has one special command-line option that serves to separate the debugger's own command line from that of the program you want it to load for debugging:


Use the --args option on starting a debugging session to pass command-line arguments to the program that GDB loads for debugging. In the following example, myprog is the program to be debugged:

$ gdb --args myprog -d "$HOME"

The --args option must be immediately followed by the command invoking the program you wish to debug. That command should consist of the program name and then its arguments, just as they would appear if you were starting that program without GDB. In the previous example, -d and "$HOME" are command-line arguments for myprog, not for gdb. If you want to specify options for GDB at the same time, you must place them before --args on the command line. In other words, --args must be the last GDB option.

You can also specify arguments for the program you are debugging after GDB has started, by using one of the interactive commands run or set args, described in the section "Running a Program in the Debugger," later in this chapter. Selecting files

The following command-line options tell GDB which input files to use:

-symbols filename, -s filename

If the table of debugging symbols is not contained in the executable file, use the -symbols option to load a separate symbol table file. GDB reads the symbol table from the specified file.

-exec filename, -e filename

The -exec option specifies the executable file to be debugged.

-se filename

The specified file is the executable you want to test in GDB and contains the symbol table. This option is not usually necessary; if the GDB command line contains a filename that is not an argument to any option, GDB treats the first such file as if it were an argument to the -se option.

-core filename, -c filename, -c number, -pid number, -p number

The -core and -pid options are actually synonymous. If the argument to either one is a decimal number, GDB connects to a running process with that process ID, if there is one. If there is no process with that ID, GDB attempts to open a core file with the name number. If you want to force GDB to open a core file whose name is a decimal number, you can prefix the directory to the filename. For example, gdb -p ./32436 instructs GDB to open a core file named 32436 in the current directory, regardless of whether there is a running process with that PID.

Like the -se option, the -core option is often unnecessary. If the GDB command line contains a second filename that is not an argument to any option, GDB treats that file as if it were an argument to the -core option. Selecting the user interface

In GDB's customary command-line mode, the console I/O of the program being debugged appears interspersed with the debugger's own commands and diagnostic output. If this behavior is inconvenient, you can prevent it by specifying a separate terminal for the input and output of the program you are debugging.

-tty device, -t device

The debugger uses device as the standard input and output streams of the program you are debugging. In the following example, the standard I/O streams of the program myprog are attached to the terminal /dev/tty5:

$ gdb myprog -t /dev/tty5

-windows, -w

GDB may also be built with an integrated GUI. This user interface provides separate display windows for the source code, assembler code, and CPU registers of the program you are debugging. The -w option instructs GDB to run with its GUI, if possible. If the GUI is not available, this option has no effect.

-nowindows, -nw

The -nw option instructs GDB to run in console mode, even if a GUI is available. If the GUI is not available, this option has no effect.

There are a number of separate "frontend" programs that provide GUIs for GDB. The best known of these is DDD, the Data Display Debugger (see DDD's capabilities include displaying dynamic data structures such as linked lists and trees. But even without a GUI, you may be able to use separate display windows with GDB:


If the help text displayed by the command gdb -h includes the option --tui, then your GDB installation provides a text-based user interface, or TUI, to manage a number of console windows. The TUI is a program module that uses the curses library.

The -tui option starts GDB with the text-based full-screen user interface, or TUI. The initial display consists of two windows: the upper window displays the C source code, with the current line highlighted and breakpoints indicated in the left margin. Below it is the command window, which displays the same (gdb) command prompt and diagnostic output as a line-based GDB session. You can also open a third window to display the program in assembly language or the contents of CPU registers. For details about working with the TUI, see the section "GDB Text User Interface" in the GDB manual.

If you use the Emacs editor, you can run GDB using the Emacs buffer windows for its display. Start GDB within Emacs using the command M-x gdb. The debugger's command window appears as a new Emacs buffer. When you begin running a program in GDB, a second buffer is created displaying the source code. The Emacs "debugger" mode also provides commands to control GDB, which are described in the section "Using GDB under GNU Emacs" in the GDB manual, and also documented in Emacs itself through the C-h m command. Executing command scripts

-command command_file, -x command_file

The -command or -x option instructs GDB to carry out the commands in the specified file on starting. A command file is a text file whose lines are GDB commands. Blank lines and comments, which are lines beginning with the hash character (#), are ignored. If you want the debugger to execute one or more command files and then exit, use the -batch option in addition to the -x or -command option.


The -batch option instructs GDB to exit after executing all command files specified in -x commands. If no errors occur, GDB exits with the status 0. Any other exit status indicates an error.

20.3.3. Initialization Files

On starting, GDB ordinarily processes an initialization file, if present, with the name .gdbinit. On certain systems with a special debugger configuration, the initialization file may have a different name. Initialization files have the same internal syntax as command files, consisting of GDB commands, comments, and blank lines. GDB processes the initialization files it finds in the current directory and your home directory. The initialization files, command line, and command files are processed in the following order:

  1. Upon starting, GDB first reads the initialization file in your home directory, if present, and carries out the commands it contains. On Windows, GDB determines the home directory from the value of the environment variable HOME. The initialization file typically contains general commands to configure the debugger, such as set listsize 5 to limit the default output of the list command to five lines.

  2. Next, GDB processes the command-line options. Any command files specified in -x or -command options are not executed at this point, though.

  3. If the current directory is not your home directory, and if the current directory contains an initialization file, GDB executes the commands in that file. Usually the current directory contains the files of a program in development, and the local initialization file .gdbinit contains commands to configure the debugger for the program's special requirements.

  4. Finally, GDB executes the commands in files specified by the -x or -command options on the command line.

GDB also lets you skip any .gdbinit files by specifying the following command-line option:

-nx, -n

Instructs GDB to ignore all initialization files. The option takes no argument.

Previous Page
Next Page