mingw/info/gdb/Server.html

   1 <html lang="en">
   2 <head>
   3 <title>Debugging with GDB</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="Debugging with GDB">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="Server">Server</a>,
  13 Next:<a rel="next" accesskey="n" href="NetWare.html#NetWare">NetWare</a>,
  14 Up:<a rel="up" accesskey="u" href="Remote-Debugging.html#Remote%20Debugging">Remote Debugging</a>
  15 <hr><br>
  16 </div>
  17
  18 <h3 class="section">Using the <code>gdbserver</code> program</h3>
  19
  20    <p><code>gdbserver</code> is a control program for Unix-like systems, which
  21 allows you to connect your program with a remote GDB via
  22 <code>target remote</code>--but without linking in the usual debugging stub.
  23
  24    <p><code>gdbserver</code> is not a complete replacement for the debugging stubs,
  25 because it requires essentially the same operating-system facilities
  26 that GDB itself does.  In fact, a system that can run
  27 <code>gdbserver</code> to connect to a remote GDB could also run
  28 GDB locally!  <code>gdbserver</code> is sometimes useful nevertheless,
  29 because it is a much smaller program than GDB itself.  It is
  30 also easier to port than all of GDB, so you may be able to get
  31 started more quickly on a new system by using <code>gdbserver</code>.
  32 Finally, if you develop code for real-time systems, you may find that
  33 the tradeoffs involved in real-time operation make it more convenient to
  34 do as much development work as possible on another system, for example
  35 by cross-compiling.  You can use <code>gdbserver</code> to make a similar
  36 choice for debugging.
  37
  38    GDB and <code>gdbserver</code> communicate via either a serial line
  39 or a TCP connection, using the standard GDB remote serial
  40 protocol.
  41
  42      <dl>
  43 <dt><em>On the target machine,</em>
  44      <dd>you need to have a copy of the program you want to debug.
  45 <code>gdbserver</code> does not need your program's symbol table, so you can
  46 strip the program if necessary to save space.  GDB on the host
  47 system does all the symbol handling.
  48
  49      <p>To use the server, you must tell it how to communicate with GDB;
  50 the name of your program; and the arguments for your program.  The usual
  51 syntax is:
  52
  53      <pre class="smallexample">          target&gt; gdbserver <var>comm</var> <var>program</var> [ <var>args</var> ... ]
  54           </pre>
  55
  56      <p><var>comm</var> is either a device name (to use a serial line) or a TCP
  57 hostname and portnumber.  For example, to debug Emacs with the argument
  58 <code>foo.txt</code> and communicate with GDB over the serial port
  59 <code>/dev/com1</code>:
  60
  61      <pre class="smallexample">          target&gt; gdbserver /dev/com1 emacs foo.txt
  62           </pre>
  63
  64      <p><code>gdbserver</code> waits passively for the host GDB to communicate
  65 with it.
  66
  67      <p>To use a TCP connection instead of a serial line:
  68
  69      <pre class="smallexample">          target&gt; gdbserver host:2345 emacs foo.txt
  70           </pre>
  71
  72      <p>The only difference from the previous example is the first argument,
  73 specifying that you are communicating with the host GDB via
  74 TCP.  The <code>host:2345</code> argument means that <code>gdbserver</code> is to
  75 expect a TCP connection from machine <code>host</code> to local TCP port 2345.
  76 (Currently, the <code>host</code> part is ignored.)  You can choose any number
  77 you want for the port number as long as it does not conflict with any
  78 TCP ports already in use on the target system (for example, <code>23</code> is
  79 reserved for <code>telnet</code>).<a rel="footnote" href="#fn-1"><sup>1</sup></a>  You must use the same port number with the host GDB
  80 <code>target remote</code> command.
  81
  82      <p>On some targets, <code>gdbserver</code> can also attach to running programs.
  83 This is accomplished via the <code>--attach</code> argument.  The syntax is:
  84
  85      <pre class="smallexample">          target&gt; gdbserver <var>comm</var> --attach <var>pid</var>
  86           </pre>
  87
  88      <p><var>pid</var> is the process ID of a currently running process.  It isn't necessary
  89 to point <code>gdbserver</code> at a binary for the running process.
  90
  91      <br><dt><em>On the GDB host machine,</em>
  92      <dd>you need an unstripped copy of your program, since GDB needs
  93 symbols and debugging information.  Start up GDB as usual,
  94 using the name of the local copy of your program as the first argument.
  95 (You may also need the <code>--baud</code> option if the serial line is
  96 running at anything other than 9600bps.)  After that, use <code>target
  97 remote</code> to establish communications with <code>gdbserver</code>.  Its argument
  98 is either a device name (usually a serial device, like
  99 <code>/dev/ttyb</code>), or a TCP port descriptor in the form
 100 <code></code><var>host</var><code>:</code><var>PORT</var><code></code>.  For example:
 101
 102      <pre class="smallexample">          (gdb) target remote /dev/ttyb
 103           </pre>
 104
 105      <p>communicates with the server via serial line <code>/dev/ttyb</code>, and
 106
 107      <pre class="smallexample">          (gdb) target remote the-target:2345
 108           </pre>
 109
 110      <p>communicates via a TCP connection to port 2345 on host <code>the-target</code>.
 111 For TCP connections, you must start up <code>gdbserver</code> prior to using
 112 the <code>target remote</code> command.  Otherwise you may get an error whose
 113 text depends on the host system, but which usually looks something like
 114 <code>Connection refused</code>.
 115 </dl>
 116
 117    <div class="footnote">
 118 <hr>
 119 <h4>Footnotes</h4>
 120 <ol type="1">
 121 <li><a name="fn-1"></a>
 122 <p>If you choose a port number that
 123 conflicts with another service, <code>gdbserver</code> prints an error message
 124 and exits.</p>
 125
 126    </ol><hr></div>
 127
 128    </body></html>
 129