<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:&nbsp;<a rel="next" accesskey="n" href="File-Transfer.html#File-Transfer">File Transfer</a>,
Up:&nbsp;<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
&lsquo;<samp><span class="samp">--baud</span></samp>&rsquo;<!-- /@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 &ldquo;Unreliable&rdquo;.  <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 &lsquo;<samp><span class="samp">target
remote</span></samp>&rsquo; 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>&mdash;you
can add new commands that only the external monitor will understand
and implement. 
</dl>

   </body></html>