| <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-2019 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> |
| </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><a name="index-remote-debugging_002c-connecting-1332"></a><a name="index-g_t_0040code_007bgdbserver_007d_002c-connecting-1333"></a><a name="index-remote-debugging_002c-types-of-connections-1334"></a><a name="index-g_t_0040code_007bgdbserver_007d_002c-types-of-connections-1335"></a><a name="index-g_t_0040code_007bgdbserver_007d_002c-_0040code_007btarget-remote_007d-mode-1336"></a><a name="index-g_t_0040code_007bgdbserver_007d_002c-_0040code_007btarget-extended_002dremote_007d-mode-1337"></a> |
| This section describes how to connect to a remote target, including the |
| types of connections and their differences, how to set up executable and |
| symbol files on the host and target, and the commands used for |
| connecting to and disconnecting from the remote target. |
| |
| <h4 class="subsection">20.1.1 Types of Remote Connections</h4> |
| |
| <p><span class="sc">gdb</span> supports two types of remote connections, <code>target remote</code> |
| mode and <code>target extended-remote</code> mode. Note that many remote targets |
| support only <code>target remote</code> mode. There are several major |
| differences between the two types of connections, enumerated here: |
| |
| |
| <a name="index-remote-debugging_002c-detach-and-program-exit-1338"></a> |
| <dl><dt>Result of detach or program exit<dd><strong>With target remote mode:</strong> When the debugged program exits or you |
| detach from it, <span class="sc">gdb</span> disconnects from the target. When using |
| <code>gdbserver</code>, <code>gdbserver</code> will exit. |
| |
| <p><strong>With target extended-remote mode:</strong> When the debugged program exits or |
| you detach from it, <span class="sc">gdb</span> remains connected to the target, even |
| though no program is running. You can rerun the program, attach to a |
| running program, or use <code>monitor</code> commands specific to the target. |
| |
| <p>When using <code>gdbserver</code> in this case, it does not exit unless it was |
| invoked using the <samp><span class="option">--once</span></samp> option. If the <samp><span class="option">--once</span></samp> option |
| was not used, you can ask <code>gdbserver</code> to exit using the |
| <code>monitor exit</code> command (see <a href="Monitor-Commands-for-gdbserver.html#Monitor-Commands-for-gdbserver">Monitor Commands for gdbserver</a>). |
| |
| <br><dt>Specifying the program to debug<dd>For both connection types you use the <code>file</code> command to specify the |
| program on the host system. If you are using <code>gdbserver</code> there are |
| some differences in how to specify the location of the program on the |
| target. |
| |
| <p><strong>With target remote mode:</strong> You must either specify the program to debug |
| on the <code>gdbserver</code> command line or use the <samp><span class="option">--attach</span></samp> option |
| (see <a href="Attaching-to-a-program.html#Attaching-to-a-program">Attaching to a Running Program</a>). |
| |
| <p><a name="index-g_t_0040option_007b_002d_002dmulti_007d_002c-_0040code_007bgdbserver_007d-option-1339"></a><strong>With target extended-remote mode:</strong> You may specify the program to debug |
| on the <code>gdbserver</code> command line, or you can load the program or attach |
| to it using <span class="sc">gdb</span> commands after connecting to <code>gdbserver</code>. |
| |
| <p><a name="g_t_002d_002dmulti-Option-in-Types-of-Remote-Connnections"></a>You can start <code>gdbserver</code> without supplying an initial command to run |
| or process ID to attach. To do this, use the <samp><span class="option">--multi</span></samp> command line |
| option. Then you can connect using <code>target extended-remote</code> and start |
| the program you want to debug (see below for details on using the |
| <code>run</code> command in this scenario). Note that the conditions under which |
| <code>gdbserver</code> terminates depend on how <span class="sc">gdb</span> connects to it |
| (<code>target remote</code> or <code>target extended-remote</code>). The |
| <samp><span class="option">--multi</span></samp> option to <code>gdbserver</code> has no influence on that. |
| |
| <br><dt>The <code>run</code> command<dd><strong>With target remote mode:</strong> The <code>run</code> command is not |
| supported. Once a connection has been established, you can use all |
| the usual <span class="sc">gdb</span> commands to examine and change data. The |
| remote program is already running, so you can use commands like |
| <kbd>step</kbd> and <kbd>continue</kbd>. |
| |
| <p><strong>With target extended-remote mode:</strong> The <code>run</code> command is |
| supported. The <code>run</code> command uses the value set by |
| <code>set remote exec-file</code> (see <a href="set-remote-exec_002dfile.html#set-remote-exec_002dfile">set remote exec-file</a>) to select |
| the program to run. Command line arguments are supported, except for |
| wildcard expansion and I/O redirection (see <a href="Arguments.html#Arguments">Arguments</a>). |
| |
| <p>If you specify the program to debug on the command line, then the |
| <code>run</code> command is not required to start execution, and you can |
| resume using commands like <kbd>step</kbd> and <kbd>continue</kbd> as with |
| <code>target remote</code> mode. |
| |
| <p><a name="Attaching-in-Types-of-Remote-Connections"></a><br><dt>Attaching<dd><strong>With target remote mode:</strong> The <span class="sc">gdb</span> command <code>attach</code> is |
| not supported. To attach to a running program using <code>gdbserver</code>, you |
| must use the <samp><span class="option">--attach</span></samp> option (see <a href="Running-gdbserver.html#Running-gdbserver">Running gdbserver</a>). |
| |
| <p><strong>With target extended-remote mode:</strong> To attach to a running program, |
| you may use the <code>attach</code> command after the connection has been |
| established. If you are using <code>gdbserver</code>, you may also invoke |
| <code>gdbserver</code> using the <samp><span class="option">--attach</span></samp> option |
| (see <a href="Running-gdbserver.html#Running-gdbserver">Running gdbserver</a>). |
| |
| </dl> |
| |
| <p><a name="Host-and-target-files"></a> |
| |
| <h4 class="subsection">20.1.2 Host and Target Files</h4> |
| |
| <p><a name="index-remote-debugging_002c-symbol-files-1340"></a><a name="index-symbol-files_002c-remote-debugging-1341"></a> |
| <span class="sc">gdb</span>, running on the host, needs access to symbol and debugging |
| information for your program running on the target. This requires |
| access to an unstripped copy of your program, and possibly any associated |
| symbol files. Note that this section applies equally to both <code>target |
| remote</code> mode and <code>target extended-remote</code> mode. |
| |
| <p>Some remote targets (see <a href="qXfer-executable-filename-read.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 <span class="sc">gdb</span> to access program files over |
| the same connection used to communicate with <span class="sc">gdb</span>. With such a |
| target, if the remote program is unstripped, the only command you need is |
| <code>target remote</code> (or <code>target extended-remote</code>). |
| |
| <p>If the remote program is stripped, or the target does not support remote |
| program file access, start up <span class="sc">gdb</span> using the name of the local |
| unstripped copy of your program as the first argument, or use the |
| <code>file</code> command. Use <code>set sysroot</code> to specify the location (on |
| the host) of target libraries (unless your <span class="sc">gdb</span> was compiled with |
| the correct sysroot using <code>--with-sysroot</code>). Alternatively, you |
| may use <code>set solib-search-path</code> to specify how <span class="sc">gdb</span> locates |
| target libraries. |
| |
| <p>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 <span class="sc">gnu</span>/Linux targets, mismatched or missing |
| files may also prevent <code>gdbserver</code> from debugging multi-threaded |
| programs. |
| |
| <h4 class="subsection">20.1.3 Remote Connection Commands</h4> |
| |
| <p><a name="index-remote-connection-commands-1342"></a><span class="sc">gdb</span> can communicate with the target over a serial line, a |
| local Unix domain socket, 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> and <code>target extended-remote</code> commands |
| establish a connection to the target. Both commands accept the same |
| arguments, which indicate the medium to use: |
| |
| <dl> |
| <dt><code>target remote </code><var>serial-device</var><dt><code>target extended-remote </code><var>serial-device</var><dd><a name="index-serial-line_002c-_0040code_007btarget-remote_007d-1343"></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>’ 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. |
| |
| <br><dt><code>target remote </code><var>local-socket</var><dt><code>target extended-remote </code><var>local-socket</var><dd><a name="index-local-socket_002c-_0040code_007btarget-remote_007d-1344"></a><a name="index-Unix-domain-socket-1345"></a>Use <var>local-socket</var> to communicate with the target. For example, |
| to use a local Unix domain socket bound to the file system entry <samp><span class="file">/tmp/gdb-socket0</span></samp>: |
| |
| <pre class="smallexample"> target remote /tmp/gdb-socket0 |
| </pre> |
| <p>Note that this command has the same form as the command to connect |
| to a serial line. <span class="sc">gdb</span> will automatically determine which |
| kind of file you have specified and will make the appropriate kind |
| of connection. |
| This feature is not available if the host system does not support |
| Unix domain sockets. |
| |
| <br><dt><code>target remote </code><var>host</var><code>:</code><var>port</var><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><dt><code>target remote tcp:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target remote tcp4:</code><var>host</var><code>:</code><var>port</var><dt><code>target remote tcp6:</code><var>host</var><code>:</code><var>port</var><dt><code>target remote tcp6:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote </code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote </code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote tcp:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote tcp:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote tcp4:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote tcp6:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote tcp6:</code><var>[host]</var><code>:</code><var>port</var><dd><a name="index-g_t_0040acronym_007bTCP_007d-port_002c-_0040code_007btarget-remote_007d-1346"></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, a numeric <acronym>IPv4</acronym> |
| address, or a numeric <acronym>IPv6</acronym> address (with or without the |
| square brackets to separate the address from the port); <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>To connect to port 2828 on a terminal server whose address is |
| <code>2001:0db8:85a3:0000:0000:8a2e:0370:7334</code>, you can either use the |
| square bracket syntax: |
| |
| <pre class="smallexample"> target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828 |
| </pre> |
| <p class="noindent">or explicitly specify the <acronym>IPv6</acronym> protocol: |
| |
| <pre class="smallexample"> target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828 |
| </pre> |
| <p>This last example may be confusing to the reader, because there is no |
| visible separation between the hostname and the port number. |
| Therefore, we recommend the user to provide <acronym>IPv6</acronym> addresses |
| using square brackets for clarity. However, it is important to |
| mention that for <span class="sc">gdb</span> there is no ambiguity: the number after |
| the last colon is considered to be the port number. |
| |
| <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><dt><code>target remote udp:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target remote udp4:</code><var>host</var><code>:</code><var>port</var><dt><code>target remote udp6:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote udp:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote udp:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote udp:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote udp4:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote udp6:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote udp6:</code><var>[host]</var><code>:</code><var>port</var><dd><a name="index-g_t_0040acronym_007bUDP_007d-port_002c-_0040code_007btarget-remote_007d-1347"></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><dt><code>target extended-remote | </code><var>command</var><dd><a name="index-pipe_002c-_0040code_007btarget-remote_007d-to-1348"></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><a name="index-interrupting-remote-programs-1349"></a><a name="index-remote-programs_002c-interrupting-1350"></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>In <code>target remote</code> mode, 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 <kbd>target remote</kbd> again to connect once more.) If you type |
| <kbd>n</kbd>, <span class="sc">gdb</span> goes back to waiting. |
| |
| <p>In <code>target extended-remote</code> mode, typing <kbd>n</kbd> will leave |
| <span class="sc">gdb</span> connected to the target. |
| |
| |
| <a name="index-detach-_0028remote_0029-1351"></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 in <code>target remote</code> mode, <span class="sc">gdb</span> is free to connect to |
| another target. In <code>target extended-remote</code> mode, <span class="sc">gdb</span> is |
| still connected to the target. |
| |
| <p><a name="index-disconnect-1352"></a><br><dt><code>disconnect</code><dd>The <code>disconnect</code> command closes the connection to the target, and |
| 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-1353"></a><a name="index-extend-_0040value_007bGDBN_007d-for-remote-targets-1354"></a><a name="index-add-new-commands-for-external-monitor-1355"></a><a name="index-monitor-1356"></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> |
| |
