20.3 Using the
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
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
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.
gdbserver communicate via either a serial line
or a TCP connection, using the standard gdb remote serial
gdbserverdoes not have any built-in security. Do not run
gdbserverconnected to any public network; a gdb connection to
gdbserverprovides access to the target system with the same privileges as the user running
gdbserver on the target system. You need a copy of the
program you want to debug, including any libraries it requires.
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
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,
telnet).1 You must use the same port number with the host gdb
target remote command.
188.8.131.52 Attaching to a Running Program
On some targets,
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
gdbserver at a binary for the running process.
target> gdbserver --attach comm `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.
184.108.40.206 Multi-Process Mode for
If you connect using target extended-remote,
enters multi-process mode. When the debugged program exits, or you
detach from it, gdb stays connected to
though no program is running. The
gdbserver to run or attach to a new program.
run command uses
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).
gdbserver without supplying an initial command to run
or process ID to attach, use the --multi command line option.
Then you can connect using target extended-remote and start
the program you want to debug.
gdbserver does not automatically exit in multi-process mode.
You can terminate it by using
(see Monitor Commands for gdbserver).
220.127.116.11 Other Command-Line Arguments for
The --debug option tells
gdbserver to display extra
status information about the debugging process. The
--remote-debug option tells
gdbserver to display
remote protocol debug output. These options are intended for
gdbserver development and for bug reports to the developers.
The --wrapper option specifies 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.
gdbserver runs the specified wrapper program with a combined
command line including the wrapper arguments, then the name of the
program to debug, then any arguments to the program. The wrapper
runs until it executes your program, and then gdb gains control.
You can use any program that eventually calls
its arguments as a wrapper. Several standard Unix utilities do
nohup. Any Unix shell script ending
exec "$@" will also work.
For example, you can use
env to pass an environment variable to
the debugged program, without setting the variable in
$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
20.3.2 Connecting to
Run gdb on the host system.
First make sure you have the necessary symbol files. Load symbols for
your application using the
file command before you connect. Use
set sysroot to locate target libraries (unless your gdb
was compiled with the correct sysroot using
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
Connect to your target (see Connecting to a Remote Target).
For TCP connections, you must start up
gdbserver prior to using
target remote command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
Connection refused. Don't use the
command in gdb when using
gdbserver, since the program is
already on the target.
20.3.3 Monitor Commands for
During a gdb session using
gdbserver, you can use the
monitor command to send special requests to
Here are the available commands.
- List the available monitor commands.
monitor set debug 0
monitor set debug 1
- Disable or enable general debugging messages.
monitor set remote-debug 0
monitor set remote-debug 1
- Disable or enable specific debugging messages associated with the remote
protocol (see Remote Protocol).
monitor set libthread-db-search-path [PATH]
- When this command is issued, path is a colon-separated list of
directories to search for
libthread_db(see set libthread-db-search-path). If you omit path, libthread-db-search-path will be reset to an empty list.
- Tell gdbserver to exit immediately. This command should be followed by
disconnectto close the debugging session.
gdbserverwill detach from any attached processes and kill any processes it created. Use
monitor exitto terminate
gdbserverat the end of a multi-process mode debug session.
20.3.4 Tracepoints support in
For fast or static tracepoints to work, a special library called the
in-process agent (IPA), must be loaded in the inferior process.
This library is built and distributed as an integral part of
gdbserver. In addition, support for static tracepoints
requires building the in-process agent library with static tracepoints
support. At present, the UST (LTTng Userspace Tracer,
http://lttng.org/ust) tracing engine is supported. This support
is automatically available if UST development headers are found in the
standard include path when
gdbserver is built, or if
gdbserver was explicitly configured using --with-ust
to point at such headers. You can explicitly disable the support
There are several ways to load the in-process agent in your program:
Specifying it as dependency at link time
You can link your program dynamically with the in-process agent
library. On most systems, this is accomplished by adding
-linproctraceto the link command.
Using the system's preloading mechanisms
You can force loading the in-process agent at startup time by using
your system's support for preloading shared libraries. Many Unixes
support the concept of preloading user defined libraries. In most
cases, you do that by specifying
LD_PRELOAD=libinproctrace.soin the environment. See also the description of
gdbserver's --wrapper command line option.
to force loading the agent at run time
On some systems, you can force the inferior to load a shared library,
by calling a dynamic loader function in the inferior that takes care
of dynamically looking up and loading a shared library. On most Unix
systems, the function is
dlopen. You'll use the
callcommand for that. For example:
(gdb) call dlopen ("libinproctrace.so", ...)
Note that on most Unix systems, for the
dlopenfunction to be available, the program needs to be linked with
On systems that have a userspace dynamic loader, like most Unix
systems, when you connect to
remote, you'll find that the program is stopped at the dynamic
loader's entry point, and no shared library has been loaded in the
program's address space yet, including the in-process agent. In that
case, before being able to use any of the fast or static tracepoints
features, you need to let the loader run and load the shared
libraries. The simplest way to do that is to run the program to the
main procedure. E.g., if debugging a C or C++ program, start
gdbserver like so:
$ gdbserver :9999 myprogram
Start GDB and connect to
gdbserver like so, and run to main:
$ gdb myprogram (gdb) target remote myhost:9999 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 (gdb) b main (gdb) continue
The in-process tracing agent library should now be loaded into the
process; you can confirm it with the
command, which will list libinproctrace.so as loaded in the
process. You are now ready to install fast tracepoints, list static
tracepoint markers, probe static tracepoints markers, and start
 If you choose a port number that
conflicts with another service,
gdbserver prints an error message