Next: Remote Configuration, Previous: File Transfer, Up: Remote Debugging

### 20.3 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.

> Warning: `gdbserver` does not have any built-in security. Do not run `gdbserver` connected to any public network; a gdb connection to `gdbserver` provides access to the target system with the same privileges as the user running `gdbserver`.

#### 20.3.1 Running `gdbserver`

Run `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 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.

##### 20.3.1.1 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 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 --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.

##### 20.3.1.2 Multi-Process Mode for `gdbserver`

When you connect to `gdbserver` using `target remote`, `gdbserver` debugs the specified program only once. When the program exits, or you detach from it, gdb closes the connection and `gdbserver` exits.

If you connect using `target extended-remote`, `gdbserver` enters multi-process mode. When the debugged program exits, or you detach from it, gdb stays connected to `gdbserver` even though no program is running. The `run` and `attach` commands instruct `gdbserver` to run or attach to a new program. The `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).

To start `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 `monitor exit` (see Monitor Commands for gdbserver).

##### 20.3.1.3 Other Command-Line Arguments for `gdbserver`

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 `execve` with its arguments as a wrapper. Several standard Unix utilities do this, e.g. `env` and `nohup`. Any Unix shell script ending with `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`'s environment:

         $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog

#### 20.3.2 Connecting to `gdbserver`

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 `--with-sysroot`).

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`'. Don't use the `load` command in gdb when using `gdbserver`, since the program is already on the target.

#### 20.3.3 Monitor Commands for `gdbserver`

During a gdb session using `gdbserver`, you can use the `monitor` command to send special requests to `gdbserver`. Here are the available commands.

`monitor help`
  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 exit`
  Tell gdbserver to exit immediately. This command should be followed by `disconnect` to close the debugging session. `gdbserver` will detach from any attached processes and kill any processes it created. Use `monitor exit` to terminate `gdbserver` at the end of a multi-process mode debug session.

#### Footnotes

[1] If you choose a port number that conflicts with another service, `gdbserver` prints an error message and exits.