17.2 Using the gdbserver Program

gdbserver is a control program for Unix-like systems, which allows you to connect your program with a remote No value for GDBN 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 No value for GDBN itself does. In fact, a system that can run gdbserver to connect to a remote No value for GDBN could also run No value for GDBN locally! gdbserver is sometimes useful nevertheless, because it is a much smaller program than No value for GDBN itself. It is also easier to port than all of No value for GDBN, 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.

No value for GDBN and gdbserver communicate via either a serial line or a TCP connection, using the standard No value for GDBN 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. No value for GDBN on the host system does all the symbol handling.

To use the server, you must tell it how to communicate with No value for GDBN; 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 No value for GDBN over the serial port ‘/dev/com1’:

target> gdbserver /dev/com1 emacs foo.txt

gdbserver waits passively for the host No value for GDBN 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 No value for GDBN 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).(7) You must use the same port number with the host No value for GDBN 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.

On the host machine,

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 No value for GDBN 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 section 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 No value for GDBN when using gdbserver, since the program is already on the target.