This section describes how to connect to a remote target, including the types of connections and their differences, how to set up executable and symbol files on the host and target, and the commands used for connecting to and disconnecting from the remote target.
gdb supports two types of remote connections,
target extended-remote mode. Note that many remote targets
target remote mode. There are several major
differences between the two types of connections, enumerated here:
With target extended-remote mode: When the debugged program exits or
you detach from it, gdb remains connected to the target, even
though no program is running. You can rerun the program, attach to a
running program, or use
monitor commands specific to the target.
gdbserver in this case, it does not exit unless it was
invoked using the --once option. If the --once option
was not used, you can ask
gdbserver to exit using the
monitor exit command (see Monitor Commands for gdbserver).
filecommand to specify the program on the host system. If you are using
gdbserverthere are some differences in how to specify the location of the program on the target.
With target remote mode: You must either specify the program to debug
gdbserver command line or use the --attach option
(see Attaching to a Running Program).
With target extended-remote mode: You may specify the program to debug
gdbserver command line, or you can load the program or attach
to it using gdb commands after connecting to
You can start
gdbserver without supplying an initial command to run
or process ID to attach. To do this, use the --multi command line
option. Then you can connect using
target extended-remote and start
the program you want to debug (see below for details on using the
run command in this scenario). Note that the conditions under which
gdbserver terminates depend on how gdb connects to it
target remote or
target extended-remote). The
--multi option to
gdbserver has no influence on that.
runcommand is not supported. Once a connection has been established, you can use all the usual gdb commands to examine and change data. The remote program is already running, so you can use commands like step and continue.
With target extended-remote mode: The
run command is
run command uses the value set by
set remote exec-file (see set remote exec-file) to select
the program to run. Command line arguments are supported, except for
wildcard expansion and I/O redirection (see Arguments).
If you specify the program to debug on the command line, then the
run command is not required to start execution, and you can
resume using commands like step and continue as with
target remote mode.
attachis not supported. To attach to a running program using
gdbserver, you must use the --attach option (see Running gdbserver).
With target extended-remote mode: To attach to a running program,
you may use the
attach command after the connection has been
established. If you are using
gdbserver, you may also invoke
gdbserver using the --attach option
(see Running gdbserver).
gdb, running on the host, needs access to symbol and debugging
information for your program running on the target. This requires
access to an unstripped copy of your program, and possibly any associated
symbol files. Note that this section applies equally to both
remote mode and
target extended-remote mode.
Some remote targets (see qXfer executable filename read, and
see Host I/O Packets) allow gdb to access program files over
the same connection used to communicate with gdb. With such a
target, if the remote program is unstripped, the only command you need is
target remote (or
If the remote program is stripped, or the target does not support remote
program file access, start up gdb using the name of the local
unstripped copy of your program as the first argument, or use the
file command. Use
set sysroot to specify the location (on
the host) of target libraries (unless your gdb was compiled with
the correct sysroot using
--with-sysroot). Alternatively, you
set solib-search-path to specify how gdb locates
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
gdb can communicate with the target over a serial line, or
over an IP network using TCP or UDP. In
each case, gdb uses the same protocol for debugging your
program; only the medium carrying the debugging packets varies. The
target remote and
target extended-remote commands
establish a connection to the target. Both commands accept the same
arguments, which indicate the medium to use:
target remote /dev/ttyb
If you're using a serial line, you may want to give gdb the
‘--baud’ option, or use the
set serial baud command
(see set serial baud) before the
target remote tcp:host
target extended-remote tcp:host
For example, to connect to port 2828 on a terminal server named
target remote manyfarms:2828
If your remote target is actually running on the same machine as your debugger session (e.g. a simulator for your target running on the same host), you can omit the hostname. For example, to connect to port 1234 on your local machine:
target remote :1234
Note that the colon is still required here.
target remote udp:host
target extended-remote udp:host
target remote udp:manyfarms:2828
When using a UDP connection for remote debugging, you should
keep in mind that the `U' stands for “Unreliable”. UDP
can silently drop packets on busy or unreliable networks, which will
cause havoc with your debugging session.
target remote |command
target extended-remote |command
/bin/sh; it should expect remote protocol packets on its standard input, and send replies on its standard output. You could use this to run a stand-alone simulator that speaks the remote debugging protocol, to make net connections using programs like
ssh, or for other similar tricks.
If command closes its standard output (perhaps by exiting),
gdb will try to send it a
SIGTERM signal. (If the
program has already exited, this will have no effect.)
Whenever gdb is waiting for the remote program, if you type the interrupt character (often Ctrl-c), gdb attempts to stop the program. This may or may not succeed, depending in part on the hardware and the serial drivers the remote system uses. If you type the interrupt character once again, gdb displays this prompt:
Interrupted while waiting for the program. Give up (and stop debugging it)? (y or n)
target remote mode, if you type y, gdb abandons
the remote debugging session. (If you decide you want to try again later,
you can use target remote again to connect once more.) If you type
n, gdb goes back to waiting.
target extended-remote mode, typing n will leave
gdb connected to the target.
detachcommand to release it from gdb control. Detaching from the target normally resumes its execution, but the results will depend on your particular remote stub. After the
target remotemode, gdb is free to connect to another target. In
target extended-remotemode, gdb is still connected to the target.
disconnectcommand closes the connection to the target, and the target is generally not resumed. It will wait for gdb (this instance or another one) to connect and continue debugging. After the
disconnectcommand, gdb is again free to connect to another target.