1<html lang="en"> 2<head> 3<title>Server - 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.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Remote-Debugging.html#Remote-Debugging" title="Remote Debugging"> 9<link rel="prev" href="File-Transfer.html#File-Transfer" title="File Transfer"> 10<link rel="next" href="Remote-Configuration.html#Remote-Configuration" title="Remote Configuration"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 15Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Free Software'' and ``Free Software Needs 21Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 22and with the Back-Cover Texts as in (a) below. 23 24(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 25this GNU Manual. Buying copies from GNU Press supports the FSF in 26developing GNU and promoting software freedom.''--> 27<meta http-equiv="Content-Style-Type" content="text/css"> 28<style type="text/css"><!-- 29 pre.display { font-family:inherit } 30 pre.format { font-family:inherit } 31 pre.smalldisplay { font-family:inherit; font-size:smaller } 32 pre.smallformat { font-family:inherit; font-size:smaller } 33 pre.smallexample { font-size:smaller } 34 pre.smalllisp { font-size:smaller } 35 span.sc { font-variant:small-caps } 36 span.roman { font-family:serif; font-weight:normal; } 37 span.sansserif { font-family:sans-serif; font-weight:normal; } 38--></style> 39<link rel="stylesheet" type="text/css" href="../cs.css"> 40</head> 41<body> 42<div class="node"> 43<a name="Server"></a> 44<p> 45Next: <a rel="next" accesskey="n" href="Remote-Configuration.html#Remote-Configuration">Remote Configuration</a>, 46Previous: <a rel="previous" accesskey="p" href="File-Transfer.html#File-Transfer">File Transfer</a>, 47Up: <a rel="up" accesskey="u" href="Remote-Debugging.html#Remote-Debugging">Remote Debugging</a> 48<hr> 49</div> 50 51<h3 class="section">20.3 Using the <code>gdbserver</code> Program</h3> 52 53<p><a name="index-gdbserver-1079"></a><a name="index-remote-connection-without-stubs-1080"></a><code>gdbserver</code> is a control program for Unix-like systems, which 54allows you to connect your program with a remote <span class="sc">gdb</span> via 55<code>target remote</code>—but without linking in the usual debugging stub. 56 57 <p><code>gdbserver</code> is not a complete replacement for the debugging stubs, 58because it requires essentially the same operating-system facilities 59that <span class="sc">gdb</span> itself does. In fact, a system that can run 60<code>gdbserver</code> to connect to a remote <span class="sc">gdb</span> could also run 61<span class="sc">gdb</span> locally! <code>gdbserver</code> is sometimes useful nevertheless, 62because it is a much smaller program than <span class="sc">gdb</span> itself. It is 63also easier to port than all of <span class="sc">gdb</span>, so you may be able to get 64started more quickly on a new system by using <code>gdbserver</code>. 65Finally, if you develop code for real-time systems, you may find that 66the tradeoffs involved in real-time operation make it more convenient to 67do as much development work as possible on another system, for example 68by cross-compiling. You can use <code>gdbserver</code> to make a similar 69choice for debugging. 70 71 <p><span class="sc">gdb</span> and <code>gdbserver</code> communicate via either a serial line 72or a TCP connection, using the standard <span class="sc">gdb</span> remote serial 73protocol. 74 75 <blockquote> 76<em>Warning:</em> <code>gdbserver</code> does not have any built-in security. 77Do not run <code>gdbserver</code> connected to any public network; a 78<span class="sc">gdb</span> connection to <code>gdbserver</code> provides access to the 79target system with the same privileges as the user running 80<code>gdbserver</code>. 81</blockquote> 82 83<h4 class="subsection">20.3.1 Running <code>gdbserver</code></h4> 84 85<p><a name="index-arguments_002c-to-_0040code_007bgdbserver_007d-1081"></a> 86Run <code>gdbserver</code> on the target system. You need a copy of the 87program you want to debug, including any libraries it requires. 88<code>gdbserver</code> does not need your program's symbol table, so you can 89strip the program if necessary to save space. <span class="sc">gdb</span> on the host 90system does all the symbol handling. 91 92 <p>To use the server, you must tell it how to communicate with <span class="sc">gdb</span>; 93the name of your program; and the arguments for your program. The usual 94syntax is: 95 96<pre class="smallexample"> target> gdbserver <var>comm</var> <var>program</var> [ <var>args</var> ... ] 97</pre> 98 <p><var>comm</var> is either a device name (to use a serial line) or a TCP 99hostname and portnumber. For example, to debug Emacs with the argument 100‘<samp><span class="samp">foo.txt</span></samp>’ and communicate with <span class="sc">gdb</span> over the serial port 101<samp><span class="file">/dev/com1</span></samp>: 102 103<pre class="smallexample"> target> gdbserver /dev/com1 emacs foo.txt 104</pre> 105 <p><code>gdbserver</code> waits passively for the host <span class="sc">gdb</span> to communicate 106with it. 107 108 <p>To use a TCP connection instead of a serial line: 109 110<pre class="smallexample"> target> gdbserver host:2345 emacs foo.txt 111</pre> 112 <p>The only difference from the previous example is the first argument, 113specifying that you are communicating with the host <span class="sc">gdb</span> via 114TCP. The ‘<samp><span class="samp">host:2345</span></samp>’ argument means that <code>gdbserver</code> is to 115expect a TCP connection from machine ‘<samp><span class="samp">host</span></samp>’ to local TCP port 2345. 116(Currently, the ‘<samp><span class="samp">host</span></samp>’ part is ignored.) You can choose any number 117you want for the port number as long as it does not conflict with any 118TCP ports already in use on the target system (for example, <code>23</code> is 119reserved for <code>telnet</code>).<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> You must use the same port number with the host <span class="sc">gdb</span> 120<code>target remote</code> command. 121 122<h5 class="subsubsection">20.3.1.1 Attaching to a Running Program</h5> 123 124<p>On some targets, <code>gdbserver</code> can also attach to running programs. 125This is accomplished via the <code>--attach</code> argument. The syntax is: 126 127<pre class="smallexample"> target> gdbserver --attach <var>comm</var> <var>pid</var> 128</pre> 129 <p><var>pid</var> is the process ID of a currently running process. It isn't necessary 130to point <code>gdbserver</code> at a binary for the running process. 131 132 <p><a name="index-pidof-1082"></a><a name="index-attach-to-a-program-by-name-1083"></a>You can debug processes by name instead of process ID if your target has the 133<code>pidof</code> utility: 134 135<pre class="smallexample"> target> gdbserver --attach <var>comm</var> `pidof <var>program</var>` 136</pre> 137 <p>In case more than one copy of <var>program</var> is running, or <var>program</var> 138has multiple threads, most versions of <code>pidof</code> support the 139<code>-s</code> option to only return the first process ID. 140 141<h5 class="subsubsection">20.3.1.2 Multi-Process Mode for <code>gdbserver</code></h5> 142 143<p><a name="index-gdbserver_002c-multiple-processes-1084"></a><a name="index-multiple-processes-with-gdbserver-1085"></a> 144When you connect to <code>gdbserver</code> using <code>target remote</code>, 145<code>gdbserver</code> debugs the specified program only once. When the 146program exits, or you detach from it, <span class="sc">gdb</span> closes the connection 147and <code>gdbserver</code> exits. 148 149 <p>If you connect using <kbd>target extended-remote</kbd>, <code>gdbserver</code> 150enters multi-process mode. When the debugged program exits, or you 151detach from it, <span class="sc">gdb</span> stays connected to <code>gdbserver</code> even 152though no program is running. The <code>run</code> and <code>attach</code> 153commands instruct <code>gdbserver</code> to run or attach to a new program. 154The <code>run</code> command uses <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 155arguments are supported, except for wildcard expansion and I/O 156redirection (see <a href="Arguments.html#Arguments">Arguments</a>). 157 158 <p>To start <code>gdbserver</code> without supplying an initial command to run 159or process ID to attach, use the <samp><span class="option">--multi</span></samp> command line option. 160Then you can connect using <kbd>target extended-remote</kbd> and start 161the program you want to debug. 162 163 <p><code>gdbserver</code> does not automatically exit in multi-process mode. 164You can terminate it by using <code>monitor exit</code> 165(see <a href="Monitor-Commands-for-gdbserver.html#Monitor-Commands-for-gdbserver">Monitor Commands for gdbserver</a>). 166 167<h5 class="subsubsection">20.3.1.3 Other Command-Line Arguments for <code>gdbserver</code></h5> 168 169<p>The <samp><span class="option">--debug</span></samp> option tells <code>gdbserver</code> to display extra 170status information about the debugging process. The 171<samp><span class="option">--remote-debug</span></samp> option tells <code>gdbserver</code> to display 172remote protocol debug output. These options are intended for 173<code>gdbserver</code> development and for bug reports to the developers. 174 175 <p>The <samp><span class="option">--wrapper</span></samp> option specifies a wrapper to launch programs 176for debugging. The option should be followed by the name of the 177wrapper, then any command-line arguments to pass to the wrapper, then 178<kbd>--</kbd> indicating the end of the wrapper arguments. 179 180 <p><code>gdbserver</code> runs the specified wrapper program with a combined 181command line including the wrapper arguments, then the name of the 182program to debug, then any arguments to the program. The wrapper 183runs until it executes your program, and then <span class="sc">gdb</span> gains control. 184 185 <p>You can use any program that eventually calls <code>execve</code> with 186its arguments as a wrapper. Several standard Unix utilities do 187this, e.g. <code>env</code> and <code>nohup</code>. Any Unix shell script ending 188with <code>exec "$@"</code> will also work. 189 190 <p>For example, you can use <code>env</code> to pass an environment variable to 191the debugged program, without setting the variable in <code>gdbserver</code>'s 192environment: 193 194<pre class="smallexample"> $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog 195</pre> 196 <h4 class="subsection">20.3.2 Connecting to <code>gdbserver</code></h4> 197 198<p>Run <span class="sc">gdb</span> on the host system. 199 200 <p>First make sure you have the necessary symbol files. Load symbols for 201your application using the <code>file</code> command before you connect. Use 202<code>set sysroot</code> to locate target libraries (unless your <span class="sc">gdb</span> 203was compiled with the correct sysroot using <code>--with-sysroot</code>). 204 205 <p>The symbol file and target libraries must exactly match the executable 206and libraries on the target, with one exception: the files on the host 207system should not be stripped, even if the files on the target system 208are. Mismatched or missing files will lead to confusing results 209during debugging. On <span class="sc">gnu</span>/Linux targets, mismatched or missing 210files may also prevent <code>gdbserver</code> from debugging multi-threaded 211programs. 212 213 <p>Connect to your target (see <a href="Connecting.html#Connecting">Connecting to a Remote Target</a>). 214For TCP connections, you must start up <code>gdbserver</code> prior to using 215the <code>target remote</code> command. Otherwise you may get an error whose 216text depends on the host system, but which usually looks something like 217‘<samp><span class="samp">Connection refused</span></samp>’. Don't use the <code>load</code> 218command in <span class="sc">gdb</span> when using <code>gdbserver</code>, since the program is 219already on the target. 220 221<h4 class="subsection">20.3.3 Monitor Commands for <code>gdbserver</code></h4> 222 223<p><a name="index-monitor-commands_002c-for-_0040code_007bgdbserver_007d-1086"></a><a name="Monitor-Commands-for-gdbserver"></a>During a <span class="sc">gdb</span> session using <code>gdbserver</code>, you can use the 224<code>monitor</code> command to send special requests to <code>gdbserver</code>. 225Here are the available commands. 226 227 <dl> 228<dt><code>monitor help</code><dd>List the available monitor commands. 229 230 <br><dt><code>monitor set debug 0</code><dt><code>monitor set debug 1</code><dd>Disable or enable general debugging messages. 231 232 <br><dt><code>monitor set remote-debug 0</code><dt><code>monitor set remote-debug 1</code><dd>Disable or enable specific debugging messages associated with the remote 233protocol (see <a href="Remote-Protocol.html#Remote-Protocol">Remote Protocol</a>). 234 235 <br><dt><code>monitor set libthread-db-search-path [PATH]</code><dd><a name="index-gdbserver_002c-search-path-for-_0040code_007blibthread_005fdb_007d-1087"></a>When this command is issued, <var>path</var> is a colon-separated list of 236directories to search for <code>libthread_db</code> (see <a href="Threads.html#Threads">set libthread-db-search-path</a>). If you omit <var>path</var>, 237‘<samp><span class="samp">libthread-db-search-path</span></samp>’ will be reset to an empty list. 238 239 <br><dt><code>monitor exit</code><dd>Tell gdbserver to exit immediately. This command should be followed by 240<code>disconnect</code> to close the debugging session. <code>gdbserver</code> will 241detach from any attached processes and kill any processes it created. 242Use <code>monitor exit</code> to terminate <code>gdbserver</code> at the end 243of a multi-process mode debug session. 244 245 </dl> 246 247<h4 class="subsection">20.3.4 Tracepoints support in <code>gdbserver</code></h4> 248 249<p><a name="index-tracepoints-support-in-_0040code_007bgdbserver_007d-1088"></a> 250On some targets, <code>gdbserver</code> supports tracepoints, fast 251tracepoints and static tracepoints. 252 253 <p>For fast or static tracepoints to work, a special library called the 254<dfn>in-process agent</dfn> (IPA), must be loaded in the inferior process. 255This library is built and distributed as an integral part of 256<code>gdbserver</code>. In addition, support for static tracepoints 257requires building the in-process agent library with static tracepoints 258support. At present, the UST (LTTng Userspace Tracer, 259<a href="http://lttng.org/ust">http://lttng.org/ust</a>) tracing engine is supported. This support 260is automatically available if UST development headers are found in the 261standard include path when <code>gdbserver</code> is built, or if 262<code>gdbserver</code> was explicitly configured using <samp><span class="option">--with-ust</span></samp> 263to point at such headers. You can explicitly disable the support 264using <samp><span class="option">--with-ust=no</span></samp>. 265 266 <p>There are several ways to load the in-process agent in your program: 267 268 <dl> 269<dt><code>Specifying it as dependency at link time</code><dd> 270You can link your program dynamically with the in-process agent 271library. On most systems, this is accomplished by adding 272<code>-linproctrace</code> to the link command. 273 274 <br><dt><code>Using the system's preloading mechanisms</code><dd> 275You can force loading the in-process agent at startup time by using 276your system's support for preloading shared libraries. Many Unixes 277support the concept of preloading user defined libraries. In most 278cases, you do that by specifying <code>LD_PRELOAD=libinproctrace.so</code> 279in the environment. See also the description of <code>gdbserver</code>'s 280<samp><span class="option">--wrapper</span></samp> command line option. 281 282 <br><dt><code>Using </code><span class="sc">gdb</span><code> to force loading the agent at run time</code><dd> 283On some systems, you can force the inferior to load a shared library, 284by calling a dynamic loader function in the inferior that takes care 285of dynamically looking up and loading a shared library. On most Unix 286systems, the function is <code>dlopen</code>. You'll use the <code>call</code> 287command for that. For example: 288 289 <pre class="smallexample"> (gdb) call dlopen ("libinproctrace.so", ...) 290</pre> 291 <p>Note that on most Unix systems, for the <code>dlopen</code> function to be 292available, the program needs to be linked with <code>-ldl</code>. 293</dl> 294 295 <p>On systems that have a userspace dynamic loader, like most Unix 296systems, when you connect to <code>gdbserver</code> using <code>target 297remote</code>, you'll find that the program is stopped at the dynamic 298loader's entry point, and no shared library has been loaded in the 299program's address space yet, including the in-process agent. In that 300case, before being able to use any of the fast or static tracepoints 301features, you need to let the loader run and load the shared 302libraries. The simplest way to do that is to run the program to the 303main procedure. E.g., if debugging a C or C<tt>++</tt> program, start 304<code>gdbserver</code> like so: 305 306<pre class="smallexample"> $ gdbserver :9999 myprogram 307</pre> 308 <p>Start GDB and connect to <code>gdbserver</code> like so, and run to main: 309 310<pre class="smallexample"> $ gdb myprogram 311 (gdb) target remote myhost:9999 312 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 313 (gdb) b main 314 (gdb) continue 315</pre> 316 <p>The in-process tracing agent library should now be loaded into the 317process; you can confirm it with the <code>info sharedlibrary</code> 318command, which will list <samp><span class="file">libinproctrace.so</span></samp> as loaded in the 319process. You are now ready to install fast tracepoints, list static 320tracepoint markers, probe static tracepoints markers, and start 321tracing. 322 323 <div class="footnote"> 324<hr> 325<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> If you choose a port number that 326conflicts with another service, <code>gdbserver</code> prints an error message 327and exits.</p> 328 329 <hr></div> 330 331 </body></html> 332 333