| <html lang="en"> |
| <head> |
| <title>Connecting - Debugging with GDB</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="Debugging with GDB"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Remote-Debugging.html#Remote-Debugging" title="Remote Debugging"> |
| <link rel="next" href="File-Transfer.html#File-Transfer" title="File Transfer"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software'' and ``Free Software Needs |
| Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' |
| and with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: ``You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Connecting"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="File-Transfer.html#File-Transfer">File Transfer</a>, |
| Up: <a rel="up" accesskey="u" href="Remote-Debugging.html#Remote-Debugging">Remote Debugging</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">20.1 Connecting to a Remote Target</h3> |
| |
| <p>On the <span class="sc">gdb</span> host machine, you will need an unstripped copy of |
| your program, since <span class="sc">gdb</span> needs symbol and debugging information. |
| Start up <span class="sc">gdb</span> as usual, using the name of the local copy of your |
| program as the first argument. |
| |
| <p><a name="index-g_t_0040code_007btarget-remote_007d-1060"></a><span class="sc">gdb</span> can communicate with the target over a serial line, or |
| over an <acronym>IP</acronym> network using <acronym>TCP</acronym> or <acronym>UDP</acronym>. In |
| each case, <span class="sc">gdb</span> uses the same protocol for debugging your |
| program; only the medium carrying the debugging packets varies. The |
| <code>target remote</code> command establishes a connection to the target. |
| Its arguments indicate which medium to use: |
| |
| <dl> |
| <dt><code>target remote </code><var>serial-device</var><dd><a name="index-serial-line_002c-_0040code_007btarget-remote_007d-1061"></a>Use <var>serial-device</var> to communicate with the target. For example, |
| to use a serial line connected to the device named <samp><span class="file">/dev/ttyb</span></samp>: |
| |
| <pre class="smallexample"> target remote /dev/ttyb |
| </pre> |
| <p>If you're using a serial line, you may want to give <span class="sc">gdb</span> the |
| ‘<samp><span class="samp">--baud</span></samp>’<!-- /@w --> option, or use the <code>set remotebaud</code> command |
| (see <a href="Remote-Configuration.html#Remote-Configuration">set remotebaud</a>) before the |
| <code>target</code> command. |
| |
| <br><dt><code>target remote </code><var>host</var><code>:</code><var>port</var><dt><code>target remote tcp:</code><var>host</var><code>:</code><var>port</var><dd><a name="index-g_t_0040acronym_007bTCP_007d-port_002c-_0040code_007btarget-remote_007d-1062"></a>Debug using a <acronym>TCP</acronym> connection to <var>port</var> on <var>host</var>. |
| The <var>host</var> may be either a host name or a numeric <acronym>IP</acronym> |
| address; <var>port</var> must be a decimal number. The <var>host</var> 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. |
| |
| <p>For example, to connect to port 2828 on a terminal server named |
| <code>manyfarms</code>: |
| |
| <pre class="smallexample"> target remote manyfarms:2828 |
| </pre> |
| <p>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: |
| |
| <pre class="smallexample"> target remote :1234 |
| </pre> |
| <p class="noindent">Note that the colon is still required here. |
| |
| <br><dt><code>target remote udp:</code><var>host</var><code>:</code><var>port</var><dd><a name="index-g_t_0040acronym_007bUDP_007d-port_002c-_0040code_007btarget-remote_007d-1063"></a>Debug using <acronym>UDP</acronym> packets to <var>port</var> on <var>host</var>. For example, to |
| connect to <acronym>UDP</acronym> port 2828 on a terminal server named <code>manyfarms</code>: |
| |
| <pre class="smallexample"> target remote udp:manyfarms:2828 |
| </pre> |
| <p>When using a <acronym>UDP</acronym> connection for remote debugging, you should |
| keep in mind that the `U' stands for “Unreliable”. <acronym>UDP</acronym> |
| can silently drop packets on busy or unreliable networks, which will |
| cause havoc with your debugging session. |
| |
| <br><dt><code>target remote | </code><var>command</var><dd><a name="index-pipe_002c-_0040code_007btarget-remote_007d-to-1064"></a>Run <var>command</var> in the background and communicate with it using a |
| pipe. The <var>command</var> is a shell command, to be parsed and expanded |
| by the system's command shell, <code>/bin/sh</code>; 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 <code>ssh</code>, or for other similar tricks. |
| |
| <p>If <var>command</var> closes its standard output (perhaps by exiting), |
| <span class="sc">gdb</span> will try to send it a <code>SIGTERM</code> signal. (If the |
| program has already exited, this will have no effect.) |
| |
| </dl> |
| |
| <p>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 <kbd>step</kbd> and <kbd>continue</kbd>, and you do not |
| need to use <kbd>run</kbd>. |
| |
| <p><a name="index-interrupting-remote-programs-1065"></a><a name="index-remote-programs_002c-interrupting-1066"></a>Whenever <span class="sc">gdb</span> is waiting for the remote program, if you type the |
| interrupt character (often <kbd>Ctrl-c</kbd>), <span class="sc">gdb</span> 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, <span class="sc">gdb</span> displays this prompt: |
| |
| <pre class="smallexample"> Interrupted while waiting for the program. |
| Give up (and stop debugging it)? (y or n) |
| </pre> |
| <p>If you type <kbd>y</kbd>, <span class="sc">gdb</span> abandons the remote debugging session. |
| (If you decide you want to try again later, you can use ‘<samp><span class="samp">target |
| remote</span></samp>’ again to connect once more.) If you type <kbd>n</kbd>, <span class="sc">gdb</span> |
| goes back to waiting. |
| |
| |
| <a name="index-detach-_0028remote_0029-1067"></a> |
| <dl><dt><code>detach</code><dd>When you have finished debugging the remote program, you can use the |
| <code>detach</code> command to release it from <span class="sc">gdb</span> control. |
| Detaching from the target normally resumes its execution, but the results |
| will depend on your particular remote stub. After the <code>detach</code> |
| command, <span class="sc">gdb</span> is free to connect to another target. |
| |
| <p><a name="index-disconnect-1068"></a><br><dt><code>disconnect</code><dd>The <code>disconnect</code> command behaves like <code>detach</code>, except that |
| the target is generally not resumed. It will wait for <span class="sc">gdb</span> |
| (this instance or another one) to connect and continue debugging. After |
| the <code>disconnect</code> command, <span class="sc">gdb</span> is again free to connect to |
| another target. |
| |
| <p><a name="index-send-command-to-remote-monitor-1069"></a><a name="index-extend-_0040value_007bGDBN_007d-for-remote-targets-1070"></a><a name="index-add-new-commands-for-external-monitor-1071"></a><a name="index-monitor-1072"></a><br><dt><code>monitor </code><var>cmd</var><dd>This command allows you to send arbitrary commands directly to the |
| remote monitor. Since <span class="sc">gdb</span> doesn't care about the commands it |
| sends like this, this command is the way to extend <span class="sc">gdb</span>—you |
| can add new commands that only the external monitor will understand |
| and implement. |
| </dl> |
| |
| </body></html> |
| |
