[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 [`-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
run [arglist]
bt
print expr
c
next
edit [file:]function
list [file:]function
step
help [name]
quit
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
-symbols=file
-s file
-write
-exec=file
-e file
-se=file
-core=file
-c file
-command=file
-x file
-ex command
-directory=directory
-d directory
-nh
-nx
-n
-quiet
-q
-batch
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
-fullname
-f
-b bps
-tty=device
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.
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 |
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
:
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.
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.
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
--version
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
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
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
gdbserver
to display remote protocol debug output.
This option is intended for gdbserver
development and for bug reports to
the developers.
--wrapper
--once
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 [-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
~/.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)
-nx
or -n
.
See more in
C.6 System-wide configuration and settings.
~/.gdbinit
-nx
, -n
or -nh
.
./.gdbinit
set auto-load local-gdbinit
.
See more in
22.7.1 Automatically loading init file in the current directory.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |