Next: Remote Configuration, Previous: Connecting, Up: Remote Debugging
gdbserver
Programgdbserver
is a control program for Unix-like systems, which
allows you to connect your program with a remote gdb via
target remote
—but without linking in the usual debugging stub.
gdbserver
is not a complete replacement for the debugging stubs,
because it requires essentially the same operating-system facilities
that gdb itself does. In fact, a system that can run
gdbserver
to connect to a remote gdb could also run
gdb locally! gdbserver
is sometimes useful nevertheless,
because it is a much smaller program than gdb itself. It is
also easier to port than all of gdb, so you may be able to get
started more quickly on a new system by using gdbserver
.
Finally, if you develop code for real-time systems, you may find that
the tradeoffs involved in real-time operation make it more convenient to
do as much development work as possible on another system, for example
by cross-compiling. You can use gdbserver
to make a similar
choice for debugging.
gdb and gdbserver
communicate via either a serial line
or a TCP connection, using the standard gdb remote serial
protocol.
gdbserver
does not need your program's symbol table, so you can
strip the program if necessary to save space. gdb on the host
system does all the symbol handling.
To use the server, you must tell it how to communicate with gdb; the name of your program; and the arguments for your program. The usual syntax is:
target> gdbserver comm program [ args ... ]
comm is either a device name (to use a serial line) or a TCP hostname and portnumber. For example, to debug Emacs with the argument `foo.txt' and communicate with gdb over the serial port /dev/com1:
target> gdbserver /dev/com1 emacs foo.txt
gdbserver
waits passively for the host gdb to communicate
with it.
To use a TCP connection instead of a serial line:
target> gdbserver host:2345 emacs foo.txt
The only difference from the previous example is the first argument,
specifying that you are communicating with the host gdb via
TCP. The `host:2345' argument means that gdbserver
is to
expect a TCP connection from machine `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
TCP ports already in use on the target system (for example, 23
is
reserved for telnet
).1 You must use the same port number with the host gdb
target remote
command.
On some targets, gdbserver
can also attach to running programs.
This is accomplished via the --attach
argument. The syntax is:
target> gdbserver comm --attach 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.
You can debug processes by name instead of process ID if your target has the
pidof
utility:
target> gdbserver comm --attach `pidof program`
In case more than one copy of program is running, or program
has multiple threads, most versions of pidof
support the
-s
option to only return the first process ID.
file
command before you connect. Use
set sysroot
to locate target libraries (unless your gdb
was compiled with the correct sysroot using --with-system-root
).
The symbol file and target libraries must exactly match the executable
and libraries on the target, with one exception: the files on the host
system should not be stripped, even if the files on the target system
are. Mismatched or missing files will lead to confusing results
during debugging. On gnu/Linux targets, mismatched or missing
files may also prevent gdbserver
from debugging multi-threaded
programs.
Connect to your target (see Connecting to a Remote Target).
For TCP connections, you must start up gdbserver
prior to using
the target remote
command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
`Connection refused'. You don't need to use the load
command in gdb when using gdbserver
, since the program is
already on the target.
gdbserver
During a gdb session using gdbserver
, you can use the
monitor
command to send special requests to gdbserver
.
Here are the available commands; they are only of interest when
debugging gdb or gdbserver
.
monitor help
monitor set debug 0
monitor set debug 1
monitor set remote-debug 0
monitor set remote-debug 1
[1] If you choose a port number that
conflicts with another service, gdbserver
prints an error message
and exits.