[ < ] [ > ]   [ << ] [ 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:

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:

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