| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 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." --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>Debugging with GDB: Connecting</title> |
| |
| <meta name="description" content="Debugging with GDB: Connecting"> |
| <meta name="keywords" content="Debugging with GDB: Connecting"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="index.html#Top" rel="start" title="Top"> |
| <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> |
| <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="Remote-Debugging.html#Remote-Debugging" rel="up" title="Remote Debugging"> |
| <link href="File-Transfer.html#File-Transfer" rel="next" title="File Transfer"> |
| <link href="Remote-Debugging.html#Remote-Debugging" rel="prev" title="Remote Debugging"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <a name="Connecting"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="File-Transfer.html#File-Transfer" accesskey="n" rel="next">File Transfer</a>, Up: <a href="Remote-Debugging.html#Remote-Debugging" accesskey="u" rel="up">Remote Debugging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <hr> |
| <a name="Connecting-to-a-Remote-Target"></a> |
| <h3 class="section">20.1 Connecting to a Remote Target</h3> |
| |
| <p><small>GDB</small> needs an unstripped copy of your program to access symbol |
| and debugging information. Some remote targets (see <a href="General-Query-Packets.html#qXfer-executable-filename-read">qXfer executable filename read</a>, and see <a href="Host-I_002fO-Packets.html#Host-I_002fO-Packets">Host I/O Packets</a>) allow |
| <small>GDB</small> to access program files over the same connection used to |
| communicate with <small>GDB</small>. With such a target, if the remote |
| program is unstripped, the only command you need is <code>target |
| remote</code>. Otherwise, start up <small>GDB</small> using the name of the local |
| unstripped copy of your program as the first argument, or use the |
| <code>file</code> command. |
| </p> |
| <a name="index-target-remote"></a> |
| <p><small>GDB</small> 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, <small>GDB</small> 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: |
| </p> |
| <dl compact="compact"> |
| <dt><code>target remote <var>serial-device</var></code></dt> |
| <dd><a name="index-serial-line_002c-target-remote"></a> |
| <p>Use <var>serial-device</var> to communicate with the target. For example, |
| to use a serial line connected to the device named <samp>/dev/ttyb</samp>: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">target remote /dev/ttyb |
| </pre></div> |
| |
| <p>If you’re using a serial line, you may want to give <small>GDB</small> the |
| ‘<samp>--baud</samp>’ option, or use the <code>set serial baud</code> command |
| (see <a href="Remote-Configuration.html#Remote-Configuration">set serial baud</a>) before the |
| <code>target</code> command. |
| </p> |
| </dd> |
| <dt><code>target remote <code><var>host</var>:<var>port</var></code></code></dt> |
| <dt><code>target remote <code>tcp:<var>host</var>:<var>port</var></code></code></dt> |
| <dd><a name="index-TCP-port_002c-target-remote"></a> |
| <p>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> |
| <p>For example, to connect to port 2828 on a terminal server named |
| <code>manyfarms</code>: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">target remote manyfarms:2828 |
| </pre></div> |
| |
| <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: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">target remote :1234 |
| </pre></div> |
| |
| <p>Note that the colon is still required here. |
| </p> |
| </dd> |
| <dt><code>target remote <code>udp:<var>host</var>:<var>port</var></code></code></dt> |
| <dd><a name="index-UDP-port_002c-target-remote"></a> |
| <p>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>: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">target remote udp:manyfarms:2828 |
| </pre></div> |
| |
| <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. |
| </p> |
| </dd> |
| <dt><code>target remote | <var>command</var></code></dt> |
| <dd><a name="index-pipe_002c-target-remote-to"></a> |
| <p>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> |
| <p>If <var>command</var> closes its standard output (perhaps by exiting), |
| <small>GDB</small> will try to send it a <code>SIGTERM</code> signal. (If the |
| program has already exited, this will have no effect.) |
| </p> |
| </dd> |
| </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"></a> |
| <a name="index-remote-programs_002c-interrupting"></a> |
| <p>Whenever <small>GDB</small> is waiting for the remote program, if you type the |
| interrupt character (often <kbd>Ctrl-c</kbd>), <small>GDB</small> 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, <small>GDB</small> displays this prompt: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">Interrupted while waiting for the program. |
| Give up (and stop debugging it)? (y or n) |
| </pre></div> |
| |
| <p>If you type <kbd>y</kbd>, <small>GDB</small> abandons the remote debugging session. |
| (If you decide you want to try again later, you can use ‘<samp>target |
| remote</samp>’ again to connect once more.) If you type <kbd>n</kbd>, <small>GDB</small> |
| goes back to waiting. |
| </p> |
| <dl compact="compact"> |
| <dd><a name="index-detach-_0028remote_0029"></a> |
| </dd> |
| <dt><code>detach</code></dt> |
| <dd><p>When you have finished debugging the remote program, you can use the |
| <code>detach</code> command to release it from <small>GDB</small> 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, <small>GDB</small> is free to connect to another target. |
| </p> |
| <a name="index-disconnect"></a> |
| </dd> |
| <dt><code>disconnect</code></dt> |
| <dd><p>The <code>disconnect</code> command behaves like <code>detach</code>, except that |
| the target is generally not resumed. It will wait for <small>GDB</small> |
| (this instance or another one) to connect and continue debugging. After |
| the <code>disconnect</code> command, <small>GDB</small> is again free to connect to |
| another target. |
| </p> |
| <a name="index-send-command-to-remote-monitor"></a> |
| <a name="index-extend-GDB-for-remote-targets"></a> |
| <a name="index-add-new-commands-for-external-monitor"></a> |
| <a name="index-monitor"></a> |
| </dd> |
| <dt><code>monitor <var>cmd</var></code></dt> |
| <dd><p>This command allows you to send arbitrary commands directly to the |
| remote monitor. Since <small>GDB</small> doesn’t care about the commands it |
| sends like this, this command is the way to extend <small>GDB</small>—you |
| can add new commands that only the external monitor will understand |
| and implement. |
| </p></dd> |
| </dl> |
| |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <a href="File-Transfer.html#File-Transfer" accesskey="n" rel="next">File Transfer</a>, Up: <a href="Remote-Debugging.html#Remote-Debugging" accesskey="u" rel="up">Remote Debugging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| |
| |
| |
| </body> |
| </html> |
