GNU Info
(gdb.info)Server
Using the `gdbserver' program
=============================
`gdbserver' 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.
_On the target machine,_
you need to have a copy of the program you want to debug.
`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.
_On the GDB host machine,_
you need an unstripped copy of your program, since GDB needs
symbols and debugging information. Start up GDB as usual, using
the name of the local copy of your program as the first argument.
(You may also need the `--baud' option if the serial line is
running at anything other than 9600bps.) After that, use `target
remote' to establish communications with `gdbserver'. Its argument
is either a device name (usually a serial device, like
`/dev/ttyb'), or a TCP port descriptor in the form `HOST:PORT'.
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'. 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'.
---------- Footnotes ----------
(1) If you choose a port number that conflicts with another service,
`gdbserver' prints an error message and exits.
automatically generated by info2www version 1.2.2.9