Next: File Transfer, Up: Remote Debugging

### 20.1 Connecting to a Remote Target

On the gdb host machine, you will need an unstripped copy of your program, since gdb needs symbol and debugging information. Start up gdb as usual, using the name of the local copy of your program as the first argument.

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` command establishes a connection to the target. Its arguments indicate which medium to use:

`target remote` serial-device
  Use serial-device to communicate with the target. For example, to use a serial line connected to the device named `/dev/ttyb`:

                target remote /dev/ttyb

  If you're using a serial line, you may want to give gdb the ‘`--baud`’ option, or use the `set remotebaud` command (see set remotebaud) before the `target` command.

`target remote` host`:`port
`target remote tcp:`host`:`port
  Debug using a TCP connection to port on host. The host may be either a host name or a numeric IP address; port must be a decimal number. The host could be the target machine itself, if it is directly connected to the net, or it might be a terminal server which in turn has a serial line to the target.

  For example, to connect to port 2828 on a terminal server named `manyfarms`:

                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`:`port
  Debug using UDP packets to port on host. For example, to connect to UDP port 2828 on a terminal server named `manyfarms`:

                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
  Run command in the background and communicate with it using a pipe. The command is a shell command, to be parsed and expanded by the system's command shell, `/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.)

Once the connection has been established, you can use all the usual commands to examine and change data. The remote program is already running; you can use `step` and `continue`, and you do not need to use `run`.

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)

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.

`detach`
  When you have finished debugging the remote program, you can use the `detach` command 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 `detach` command, gdb is free to connect to another target.

`disconnect`
  The `disconnect` command behaves like `detach`, except that the target is generally not resumed. It will wait for gdb (this instance or another one) to connect and continue debugging. After the `disconnect` command, gdb is again free to connect to another target.

`monitor` cmd
  This command allows you to send arbitrary commands directly to the remote monitor. Since gdb doesn't care about the commands it sends like this, this command is the way to extend gdb—you can add new commands that only the external monitor will understand and implement.