1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: gdbserver man</title> 18 19<meta name="description" content="Debugging with GDB: gdbserver man"> 20<meta name="keywords" content="Debugging with GDB: gdbserver man"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Man-Pages.html#Man-Pages" rel="up" title="Man Pages"> 29<link href="gcore-man.html#gcore-man" rel="next" title="gcore man"> 30<link href="gdb-man.html#gdb-man" rel="previous" title="gdb man"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="gdbserver-man"></a> 65<div class="header"> 66<p> 67Next: <a href="gcore-man.html#gcore-man" accesskey="n" rel="next">gcore man</a>, Previous: <a href="gdb-man.html#gdb-man" accesskey="p" rel="previous">gdb man</a>, Up: <a href="Man-Pages.html#Man-Pages" accesskey="u" rel="up">Man Pages</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> 68</div> 69<hr> 70<h4 class="node-heading">gdbserver man</h4> 71<a name="gdbserver-man-1"></a> 72<h3 class="heading">gdbserver man</h3> 73 74<div class="format"> 75<pre class="format">gdbserver <var>comm</var> <var>prog</var> [<var>args</var>…] 76 77gdbserver –attach <var>comm</var> <var>pid</var> 78 79gdbserver –multi <var>comm</var> 80</pre></div> 81 82<p><code>gdbserver</code> is a program that allows you to run <small>GDB</small> on a different machine 83than the one which is running the program being debugged. 84</p> 85<a name="Usage-_0028server-_0028target_0029-side_0029"></a> 86<h4 class="subheading">Usage (server (target) side)</h4> 87 88<p>First, you need to have a copy of the program you want to debug put onto 89the target system. The program can be stripped to save space if needed, as 90<code>gdbserver</code> doesn’t care about symbols. All symbol handling is taken care of by 91the <small>GDB</small> running on the host system. 92</p> 93<p>To use the server, you log on to the target system, and run the <code>gdbserver</code> 94program. You must tell it (a) how to communicate with <small>GDB</small>, (b) the name of 95your program, and (c) its arguments. The general syntax is: 96</p> 97<div class="smallexample"> 98<pre class="smallexample">target> gdbserver <var>comm</var> <var>program</var> [<var>args</var> ...] 99</pre></div> 100 101<p>For example, using a serial port, you might say: 102</p> 103<div class="smallexample"> 104<pre class="smallexample">target> gdbserver <samp>/dev/com1</samp> emacs foo.txt 105</pre></div> 106 107<p>This tells <code>gdbserver</code> to debug emacs with an argument of foo.txt, and 108to communicate with <small>GDB</small> via <samp>/dev/com1</samp>. <code>gdbserver</code> now 109waits patiently for the host <small>GDB</small> to communicate with it. 110</p> 111<p>To use a TCP connection, you could say: 112</p> 113<div class="smallexample"> 114<pre class="smallexample">target> gdbserver host:2345 emacs foo.txt 115</pre></div> 116 117<p>This says pretty much the same thing as the last example, except that we are 118going to communicate with the <code>host</code> <small>GDB</small> via TCP. The <code>host:2345</code> argument means 119that we are expecting to see a TCP connection from <code>host</code> to local TCP port 1202345. (Currently, the <code>host</code> part is ignored.) You can choose any number you 121want for the port number as long as it does not conflict with any existing TCP 122ports on the target system. This same port number must be used in the host 123<small>GDB</small>s <code>target remote</code> command, which will be described shortly. Note that if 124you chose a port number that conflicts with another service, <code>gdbserver</code> will 125print an error message and exit. 126</p> 127<p><code>gdbserver</code> can also attach to running programs. 128This is accomplished via the <samp>--attach</samp> argument. The syntax is: 129</p> 130<div class="smallexample"> 131<pre class="smallexample">target> gdbserver --attach <var>comm</var> <var>pid</var> 132</pre></div> 133 134<p><var>pid</var> is the process ID of a currently running process. It isn’t 135necessary to point <code>gdbserver</code> at a binary for the running process. 136</p> 137<p>To start <code>gdbserver</code> without supplying an initial command to run 138or process ID to attach, use the <samp>--multi</samp> command line option. 139In such case you should connect using <kbd>target extended-remote</kbd> to start 140the program you want to debug. 141</p> 142<div class="smallexample"> 143<pre class="smallexample">target> gdbserver --multi <var>comm</var> 144</pre></div> 145 146<a name="Usage-_0028host-side_0029"></a> 147<h4 class="subheading">Usage (host side)</h4> 148 149<p>You need an unstripped copy of the target program on your host system, since 150<small>GDB</small> needs to examine its symbol tables and such. Start up <small>GDB</small> as you normally 151would, with the target program as the first argument. (You may need to use the 152<samp>--baud</samp> option if the serial line is running at anything except 9600 baud.) 153That is <code>gdb TARGET-PROG</code>, or <code>gdb --baud BAUD TARGET-PROG</code>. After that, the only 154new command you need to know about is <code>target remote</code> 155(or <code>target extended-remote</code>). Its argument is either 156a device name (usually a serial device, like <samp>/dev/ttyb</samp>), or a <code>HOST:PORT</code> 157descriptor. For example: 158</p> 159<div class="smallexample"> 160<pre class="smallexample">(gdb) target remote <samp>/dev/ttyb</samp> 161</pre></div> 162 163<p>communicates with the server via serial line <samp>/dev/ttyb</samp>, and: 164</p> 165<div class="smallexample"> 166<pre class="smallexample">(gdb) target remote the-target:2345 167</pre></div> 168 169<p>communicates via a TCP connection to port 2345 on host ‘the-target’, where 170you previously started up <code>gdbserver</code> with the same port number. Note that for 171TCP connections, you must start up <code>gdbserver</code> prior to using the ‘target remote’ 172command, otherwise you may get an error that looks something like 173‘Connection refused’. 174</p> 175<p><code>gdbserver</code> can also debug multiple inferiors at once, 176described in 177<a href="Inferiors-Connections-and-Programs.html#Inferiors-Connections-and-Programs">Inferiors Connections and Programs</a>. 178In such case use the <code>extended-remote</code> <small>GDB</small> command variant: 179</p> 180<div class="smallexample"> 181<pre class="smallexample">(gdb) target extended-remote the-target:2345 182</pre></div> 183 184<p>The <code>gdbserver</code> option <samp>--multi</samp> may or may not be used in such 185case. 186</p> 187<p>There are three different modes for invoking <code>gdbserver</code>: 188</p> 189<ul> 190<li> Debug a specific program specified by its program name: 191 192<div class="smallexample"> 193<pre class="smallexample">gdbserver <var>comm</var> <var>prog</var> [<var>args</var>…] 194</pre></div> 195 196<p>The <var>comm</var> parameter specifies how should the server communicate 197with <small>GDB</small>; it is either a device name (to use a serial line), 198a TCP port number (<code>:1234</code>), or <code>-</code> or <code>stdio</code> to use 199stdin/stdout of <code>gdbserver</code>. Specify the name of the program to 200debug in <var>prog</var>. Any remaining arguments will be passed to the 201program verbatim. When the program exits, <small>GDB</small> will close the 202connection, and <code>gdbserver</code> will exit. 203</p> 204</li><li> Debug a specific program by specifying the process ID of a running 205program: 206 207<div class="smallexample"> 208<pre class="smallexample">gdbserver --attach <var>comm</var> <var>pid</var> 209</pre></div> 210 211<p>The <var>comm</var> parameter is as described above. Supply the process ID 212of a running program in <var>pid</var>; <small>GDB</small> will do everything 213else. Like with the previous mode, when the process <var>pid</var> exits, 214<small>GDB</small> will close the connection, and <code>gdbserver</code> will exit. 215</p> 216</li><li> Multi-process mode – debug more than one program/process: 217 218<div class="smallexample"> 219<pre class="smallexample">gdbserver --multi <var>comm</var> 220</pre></div> 221 222<p>In this mode, <small>GDB</small> can instruct <code>gdbserver</code> which 223command(s) to run. Unlike the other 2 modes, <small>GDB</small> will not 224close the connection when a process being debugged exits, so you can 225debug several processes in the same session. 226</p></li></ul> 227 228<p>In each of the modes you may specify these options: 229</p> 230<dl compact="compact"> 231<dt><code>--help</code></dt> 232<dd><p>List all options, with brief explanations. 233</p> 234</dd> 235<dt><code>--version</code></dt> 236<dd><p>This option causes <code>gdbserver</code> to print its version number and exit. 237</p> 238</dd> 239<dt><code>--attach</code></dt> 240<dd><p><code>gdbserver</code> will attach to a running program. The syntax is: 241</p> 242<div class="smallexample"> 243<pre class="smallexample">target> gdbserver --attach <var>comm</var> <var>pid</var> 244</pre></div> 245 246<p><var>pid</var> is the process ID of a currently running process. It isn’t 247necessary to point <code>gdbserver</code> at a binary for the running process. 248</p> 249</dd> 250<dt><code>--multi</code></dt> 251<dd><p>To start <code>gdbserver</code> without supplying an initial command to run 252or process ID to attach, use this command line option. 253Then you can connect using <kbd>target extended-remote</kbd> and start 254the program you want to debug. The syntax is: 255</p> 256<div class="smallexample"> 257<pre class="smallexample">target> gdbserver --multi <var>comm</var> 258</pre></div> 259 260</dd> 261<dt><code>--debug</code></dt> 262<dd><p>Instruct <code>gdbserver</code> to display extra status information about the debugging 263process. 264This option is intended for <code>gdbserver</code> development and for bug reports to 265the developers. 266</p> 267</dd> 268<dt><code>--remote-debug</code></dt> 269<dd><p>Instruct <code>gdbserver</code> to display remote protocol debug output. 270This option is intended for <code>gdbserver</code> development and for bug reports to 271the developers. 272</p> 273</dd> 274<dt><code>--debug-file=<var>filename</var></code></dt> 275<dd><p>Instruct <code>gdbserver</code> to send any debug output to the given <var>filename</var>. 276This option is intended for <code>gdbserver</code> development and for bug reports to 277the developers. 278</p> 279</dd> 280<dt><code>--debug-format=option1<span class="roman">[</span>,option2,...<span class="roman">]</span></code></dt> 281<dd><p>Instruct <code>gdbserver</code> to include extra information in each line 282of debugging output. 283See <a href="Server.html#Other-Command_002dLine-Arguments-for-gdbserver">Other Command-Line Arguments for gdbserver</a>. 284</p> 285</dd> 286<dt><code>--wrapper</code></dt> 287<dd><p>Specify a wrapper to launch programs 288for debugging. The option should be followed by the name of the 289wrapper, then any command-line arguments to pass to the wrapper, then 290<kbd>--</kbd> indicating the end of the wrapper arguments. 291</p> 292</dd> 293<dt><code>--once</code></dt> 294<dd><p>By default, <code>gdbserver</code> keeps the listening TCP port open, so that 295additional connections are possible. However, if you start <code>gdbserver</code> 296with the <samp>--once</samp> option, it will stop listening for any further 297connection attempts after connecting to the first <small>GDB</small> session. 298</p> 299 300 301</dd> 302</dl> 303 304 305<hr> 306<div class="header"> 307<p> 308Next: <a href="gcore-man.html#gcore-man" accesskey="n" rel="next">gcore man</a>, Previous: <a href="gdb-man.html#gdb-man" accesskey="p" rel="previous">gdb man</a>, Up: <a href="Man-Pages.html#Man-Pages" accesskey="u" rel="up">Man Pages</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> 309</div> 310 311 312 313</body> 314</html> 315