Server.html 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501
  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-2019 Free Software Foundation, Inc.
  4. Permission is granted to copy, distribute and/or modify this document
  5. under the terms of the GNU Free Documentation License, Version 1.3 or
  6. any later version published by the Free Software Foundation; with the
  7. Invariant Sections being "Free Software" and "Free Software Needs
  8. Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
  9. and with the Back-Cover Texts as in (a) below.
  10. (a) The FSF's Back-Cover Text is: "You are free to copy and modify
  11. this GNU Manual. Buying copies from GNU Press supports the FSF in
  12. developing GNU and promoting software freedom." -->
  13. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  14. <head>
  15. <title>Debugging with GDB: Server</title>
  16. <meta name="description" content="Debugging with GDB: Server">
  17. <meta name="keywords" content="Debugging with GDB: Server">
  18. <meta name="resource-type" content="document">
  19. <meta name="distribution" content="global">
  20. <meta name="Generator" content="makeinfo">
  21. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  22. <link href="index.html#Top" rel="start" title="Top">
  23. <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
  24. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  25. <link href="Remote-Debugging.html#Remote-Debugging" rel="up" title="Remote Debugging">
  26. <link href="Remote-Configuration.html#Remote-Configuration" rel="next" title="Remote Configuration">
  27. <link href="File-Transfer.html#File-Transfer" rel="prev" title="File Transfer">
  28. <style type="text/css">
  29. <!--
  30. a.summary-letter {text-decoration: none}
  31. blockquote.smallquotation {font-size: smaller}
  32. div.display {margin-left: 3.2em}
  33. div.example {margin-left: 3.2em}
  34. div.indentedblock {margin-left: 3.2em}
  35. div.lisp {margin-left: 3.2em}
  36. div.smalldisplay {margin-left: 3.2em}
  37. div.smallexample {margin-left: 3.2em}
  38. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  39. div.smalllisp {margin-left: 3.2em}
  40. kbd {font-style:oblique}
  41. pre.display {font-family: inherit}
  42. pre.format {font-family: inherit}
  43. pre.menu-comment {font-family: serif}
  44. pre.menu-preformatted {font-family: serif}
  45. pre.smalldisplay {font-family: inherit; font-size: smaller}
  46. pre.smallexample {font-size: smaller}
  47. pre.smallformat {font-family: inherit; font-size: smaller}
  48. pre.smalllisp {font-size: smaller}
  49. span.nocodebreak {white-space:nowrap}
  50. span.nolinebreak {white-space:nowrap}
  51. span.roman {font-family:serif; font-weight:normal}
  52. span.sansserif {font-family:sans-serif; font-weight:normal}
  53. ul.no-bullet {list-style: none}
  54. -->
  55. </style>
  56. </head>
  57. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  58. <a name="Server"></a>
  59. <div class="header">
  60. <p>
  61. Next: <a href="Remote-Configuration.html#Remote-Configuration" accesskey="n" rel="next">Remote Configuration</a>, Previous: <a href="File-Transfer.html#File-Transfer" accesskey="p" rel="prev">File Transfer</a>, Up: <a href="Remote-Debugging.html#Remote-Debugging" accesskey="u" rel="up">Remote Debugging</a> &nbsp; [<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>
  62. </div>
  63. <hr>
  64. <a name="Using-the-gdbserver-Program"></a>
  65. <h3 class="section">20.3 Using the <code>gdbserver</code> Program</h3>
  66. <a name="index-gdbserver"></a>
  67. <a name="index-remote-connection-without-stubs"></a>
  68. <p><code>gdbserver</code> is a control program for Unix-like systems, which
  69. allows you to connect your program with a remote <small>GDB</small> via
  70. <code>target remote</code> or <code>target extended-remote</code>&mdash;but without
  71. linking in the usual debugging stub.
  72. </p>
  73. <p><code>gdbserver</code> is not a complete replacement for the debugging stubs,
  74. because it requires essentially the same operating-system facilities
  75. that <small>GDB</small> itself does. In fact, a system that can run
  76. <code>gdbserver</code> to connect to a remote <small>GDB</small> could also run
  77. <small>GDB</small> locally! <code>gdbserver</code> is sometimes useful nevertheless,
  78. because it is a much smaller program than <small>GDB</small> itself. It is
  79. also easier to port than all of <small>GDB</small>, so you may be able to get
  80. started more quickly on a new system by using <code>gdbserver</code>.
  81. Finally, if you develop code for real-time systems, you may find that
  82. the tradeoffs involved in real-time operation make it more convenient to
  83. do as much development work as possible on another system, for example
  84. by cross-compiling. You can use <code>gdbserver</code> to make a similar
  85. choice for debugging.
  86. </p>
  87. <p><small>GDB</small> and <code>gdbserver</code> communicate via either a serial line
  88. or a TCP connection, using the standard <small>GDB</small> remote serial
  89. protocol.
  90. </p>
  91. <blockquote>
  92. <p><em>Warning:</em> <code>gdbserver</code> does not have any built-in security.
  93. Do not run <code>gdbserver</code> connected to any public network; a
  94. <small>GDB</small> connection to <code>gdbserver</code> provides access to the
  95. target system with the same privileges as the user running
  96. <code>gdbserver</code>.
  97. </p></blockquote>
  98. <a name="Running-gdbserver"></a><a name="Running-gdbserver-1"></a>
  99. <h4 class="subsection">20.3.1 Running <code>gdbserver</code></h4>
  100. <a name="index-arguments_002c-to-gdbserver"></a>
  101. <a name="index-gdbserver_002c-command_002dline-arguments"></a>
  102. <p>Run <code>gdbserver</code> on the target system. You need a copy of the
  103. program you want to debug, including any libraries it requires.
  104. <code>gdbserver</code> does not need your program&rsquo;s symbol table, so you can
  105. strip the program if necessary to save space. <small>GDB</small> on the host
  106. system does all the symbol handling.
  107. </p>
  108. <p>To use the server, you must tell it how to communicate with <small>GDB</small>;
  109. the name of your program; and the arguments for your program. The usual
  110. syntax is:
  111. </p>
  112. <div class="smallexample">
  113. <pre class="smallexample">target&gt; gdbserver <var>comm</var> <var>program</var> [ <var>args</var> &hellip; ]
  114. </pre></div>
  115. <p><var>comm</var> is either a device name (to use a serial line), or a TCP
  116. hostname and portnumber, or <code>-</code> or <code>stdio</code> to use
  117. stdin/stdout of <code>gdbserver</code>.
  118. For example, to debug Emacs with the argument
  119. &lsquo;<samp>foo.txt</samp>&rsquo; and communicate with <small>GDB</small> over the serial port
  120. <samp>/dev/com1</samp>:
  121. </p>
  122. <div class="smallexample">
  123. <pre class="smallexample">target&gt; gdbserver /dev/com1 emacs foo.txt
  124. </pre></div>
  125. <p><code>gdbserver</code> waits passively for the host <small>GDB</small> to communicate
  126. with it.
  127. </p>
  128. <p>To use a TCP connection instead of a serial line:
  129. </p>
  130. <div class="smallexample">
  131. <pre class="smallexample">target&gt; gdbserver host:2345 emacs foo.txt
  132. </pre></div>
  133. <p>The only difference from the previous example is the first argument,
  134. specifying that you are communicating with the host <small>GDB</small> via
  135. TCP. The &lsquo;<samp>host:2345</samp>&rsquo; argument means that <code>gdbserver</code> is to
  136. expect a TCP connection from machine &lsquo;<samp>host</samp>&rsquo; to local TCP port 2345.
  137. (Currently, the &lsquo;<samp>host</samp>&rsquo; part is ignored.) You can choose any number
  138. you want for the port number as long as it does not conflict with any
  139. TCP ports already in use on the target system (for example, <code>23</code> is
  140. reserved for <code>telnet</code>).<a name="DOCF15" href="#FOOT15"><sup>15</sup></a> You must use the same port number with the host <small>GDB</small>
  141. <code>target remote</code> command.
  142. </p>
  143. <p>The <code>stdio</code> connection is useful when starting <code>gdbserver</code>
  144. with ssh:
  145. </p>
  146. <div class="smallexample">
  147. <pre class="smallexample">(gdb) target remote | ssh -T hostname gdbserver - hello
  148. </pre></div>
  149. <p>The &lsquo;<samp>-T</samp>&rsquo; option to ssh is provided because we don&rsquo;t need a remote pty,
  150. and we don&rsquo;t want escape-character handling. Ssh does this by default when
  151. a command is provided, the flag is provided to make it explicit.
  152. You could elide it if you want to.
  153. </p>
  154. <p>Programs started with stdio-connected gdbserver have <samp>/dev/null</samp> for
  155. <code>stdin</code>, and <code>stdout</code>,<code>stderr</code> are sent back to gdb for
  156. display through a pipe connected to gdbserver.
  157. Both <code>stdout</code> and <code>stderr</code> use the same pipe.
  158. </p>
  159. <a name="Attaching-to-a-program"></a><a name="Attaching-to-a-Running-Program"></a>
  160. <h4 class="subsubsection">20.3.1.1 Attaching to a Running Program</h4>
  161. <a name="index-attach-to-a-program_002c-gdbserver"></a>
  162. <a name="index-_002d_002dattach_002c-gdbserver-option"></a>
  163. <p>On some targets, <code>gdbserver</code> can also attach to running programs.
  164. This is accomplished via the <code>--attach</code> argument. The syntax is:
  165. </p>
  166. <div class="smallexample">
  167. <pre class="smallexample">target&gt; gdbserver --attach <var>comm</var> <var>pid</var>
  168. </pre></div>
  169. <p><var>pid</var> is the process ID of a currently running process. It isn&rsquo;t
  170. necessary to point <code>gdbserver</code> at a binary for the running process.
  171. </p>
  172. <p>In <code>target extended-remote</code> mode, you can also attach using the
  173. <small>GDB</small> attach command
  174. (see <a href="Connecting.html#Attaching-in-Types-of-Remote-Connections">Attaching in Types of Remote Connections</a>).
  175. </p>
  176. <a name="index-pidof"></a>
  177. <p>You can debug processes by name instead of process ID if your target has the
  178. <code>pidof</code> utility:
  179. </p>
  180. <div class="smallexample">
  181. <pre class="smallexample">target&gt; gdbserver --attach <var>comm</var> `pidof <var>program</var>`
  182. </pre></div>
  183. <p>In case more than one copy of <var>program</var> is running, or <var>program</var>
  184. has multiple threads, most versions of <code>pidof</code> support the
  185. <code>-s</code> option to only return the first process ID.
  186. </p>
  187. <a name="TCP-port-allocation-lifecycle-of-gdbserver"></a>
  188. <h4 class="subsubsection">20.3.1.2 TCP port allocation lifecycle of <code>gdbserver</code></h4>
  189. <p>This section applies only when <code>gdbserver</code> is run to listen on a TCP
  190. port.
  191. </p>
  192. <p><code>gdbserver</code> normally terminates after all of its debugged processes have
  193. terminated in <kbd>target remote</kbd> mode. On the other hand, for <kbd>target
  194. extended-remote</kbd>, <code>gdbserver</code> stays running even with no processes left.
  195. <small>GDB</small> normally terminates the spawned debugged process on its exit,
  196. which normally also terminates <code>gdbserver</code> in the <kbd>target remote</kbd>
  197. mode. Therefore, when the connection drops unexpectedly, and <small>GDB</small>
  198. cannot ask <code>gdbserver</code> to kill its debugged processes, <code>gdbserver</code>
  199. stays running even in the <kbd>target remote</kbd> mode.
  200. </p>
  201. <p>When <code>gdbserver</code> stays running, <small>GDB</small> can connect to it again later.
  202. Such reconnecting is useful for features like <a href="Starting-and-Stopping-Trace-Experiments.html#disconnected-tracing">disconnected tracing</a>. For
  203. completeness, at most one <small>GDB</small> can be connected at a time.
  204. </p>
  205. <a name="index-_002d_002donce_002c-gdbserver-option"></a>
  206. <p>By default, <code>gdbserver</code> keeps the listening TCP port open, so that
  207. subsequent connections are possible. However, if you start <code>gdbserver</code>
  208. with the <samp>--once</samp> option, it will stop listening for any further
  209. connection attempts after connecting to the first <small>GDB</small> session. This
  210. means no further connections to <code>gdbserver</code> will be possible after the
  211. first one. It also means <code>gdbserver</code> will terminate after the first
  212. connection with remote <small>GDB</small> has closed, even for unexpectedly closed
  213. connections and even in the <kbd>target extended-remote</kbd> mode. The
  214. <samp>--once</samp> option allows reusing the same port number for connecting to
  215. multiple instances of <code>gdbserver</code> running on the same host, since each
  216. instance closes its port after the first connection.
  217. </p>
  218. <a name="Other-Command_002dLine-Arguments-for-gdbserver"></a><a name="Other-Command_002dLine-Arguments-for-gdbserver-1"></a>
  219. <h4 class="subsubsection">20.3.1.3 Other Command-Line Arguments for <code>gdbserver</code></h4>
  220. <p>You can use the <samp>--multi</samp> option to start <code>gdbserver</code> without
  221. specifying a program to debug or a process to attach to. Then you can
  222. attach in <code>target extended-remote</code> mode and run or attach to a
  223. program. For more information,
  224. see <a href="Connecting.html#g_t_002d_002dmulti-Option-in-Types-of-Remote-Connnections">--multi Option in Types of Remote Connnections</a>.
  225. </p>
  226. <a name="index-_002d_002ddebug_002c-gdbserver-option"></a>
  227. <p>The <samp>--debug</samp> option tells <code>gdbserver</code> to display extra
  228. status information about the debugging process.
  229. <a name="index-_002d_002dremote_002ddebug_002c-gdbserver-option"></a>
  230. The <samp>--remote-debug</samp> option tells <code>gdbserver</code> to display
  231. remote protocol debug output. These options are intended for
  232. <code>gdbserver</code> development and for bug reports to the developers.
  233. </p>
  234. <a name="index-_002d_002ddebug_002dformat_002c-gdbserver-option"></a>
  235. <p>The <samp>--debug-format=option1[,option2,...]</samp> option tells
  236. <code>gdbserver</code> to include additional information in each output.
  237. Possible options are:
  238. </p>
  239. <dl compact="compact">
  240. <dt><code>none</code></dt>
  241. <dd><p>Turn off all extra information in debugging output.
  242. </p></dd>
  243. <dt><code>all</code></dt>
  244. <dd><p>Turn on all extra information in debugging output.
  245. </p></dd>
  246. <dt><code>timestamps</code></dt>
  247. <dd><p>Include a timestamp in each line of debugging output.
  248. </p></dd>
  249. </dl>
  250. <p>Options are processed in order. Thus, for example, if <samp>none</samp>
  251. appears last then no additional information is added to debugging output.
  252. </p>
  253. <a name="index-_002d_002dwrapper_002c-gdbserver-option"></a>
  254. <p>The <samp>--wrapper</samp> option specifies a wrapper to launch programs
  255. for debugging. The option should be followed by the name of the
  256. wrapper, then any command-line arguments to pass to the wrapper, then
  257. <kbd>--</kbd> indicating the end of the wrapper arguments.
  258. </p>
  259. <p><code>gdbserver</code> runs the specified wrapper program with a combined
  260. command line including the wrapper arguments, then the name of the
  261. program to debug, then any arguments to the program. The wrapper
  262. runs until it executes your program, and then <small>GDB</small> gains control.
  263. </p>
  264. <p>You can use any program that eventually calls <code>execve</code> with
  265. its arguments as a wrapper. Several standard Unix utilities do
  266. this, e.g. <code>env</code> and <code>nohup</code>. Any Unix shell script ending
  267. with <code>exec &quot;$@&quot;</code> will also work.
  268. </p>
  269. <p>For example, you can use <code>env</code> to pass an environment variable to
  270. the debugged program, without setting the variable in <code>gdbserver</code>&rsquo;s
  271. environment:
  272. </p>
  273. <div class="smallexample">
  274. <pre class="smallexample">$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
  275. </pre></div>
  276. <a name="index-_002d_002dselftest"></a>
  277. <p>The <samp>--selftest</samp> option runs the self tests in <code>gdbserver</code>:
  278. </p>
  279. <div class="smallexample">
  280. <pre class="smallexample">$ gdbserver --selftest
  281. Ran 2 unit tests, 0 failed
  282. </pre></div>
  283. <p>These tests are disabled in release.
  284. </p><a name="Connecting-to-gdbserver"></a>
  285. <h4 class="subsection">20.3.2 Connecting to <code>gdbserver</code></h4>
  286. <p>The basic procedure for connecting to the remote target is:
  287. </p><ul>
  288. <li> Run <small>GDB</small> on the host system.
  289. </li><li> Make sure you have the necessary symbol files
  290. (see <a href="Connecting.html#Host-and-target-files">Host and target files</a>).
  291. Load symbols for your application using the <code>file</code> command before you
  292. connect. Use <code>set sysroot</code> to locate target libraries (unless your
  293. <small>GDB</small> was compiled with the correct sysroot using
  294. <code>--with-sysroot</code>).
  295. </li><li> Connect to your target (see <a href="Connecting.html#Connecting">Connecting to a Remote Target</a>).
  296. For TCP connections, you must start up <code>gdbserver</code> prior to using
  297. the <code>target</code> command. Otherwise you may get an error whose
  298. text depends on the host system, but which usually looks something like
  299. &lsquo;<samp>Connection refused</samp>&rsquo;. Don&rsquo;t use the <code>load</code>
  300. command in <small>GDB</small> when using <code>target remote</code> mode, since the
  301. program is already on the target.
  302. </li></ul>
  303. <a name="Monitor-Commands-for-gdbserver"></a><a name="Monitor-Commands-for-gdbserver-1"></a>
  304. <h4 class="subsection">20.3.3 Monitor Commands for <code>gdbserver</code></h4>
  305. <a name="index-monitor-commands_002c-for-gdbserver"></a>
  306. <p>During a <small>GDB</small> session using <code>gdbserver</code>, you can use the
  307. <code>monitor</code> command to send special requests to <code>gdbserver</code>.
  308. Here are the available commands.
  309. </p>
  310. <dl compact="compact">
  311. <dt><code>monitor help</code></dt>
  312. <dd><p>List the available monitor commands.
  313. </p>
  314. </dd>
  315. <dt><code>monitor set debug 0</code></dt>
  316. <dt><code>monitor set debug 1</code></dt>
  317. <dd><p>Disable or enable general debugging messages.
  318. </p>
  319. </dd>
  320. <dt><code>monitor set remote-debug 0</code></dt>
  321. <dt><code>monitor set remote-debug 1</code></dt>
  322. <dd><p>Disable or enable specific debugging messages associated with the remote
  323. protocol (see <a href="Remote-Protocol.html#Remote-Protocol">Remote Protocol</a>).
  324. </p>
  325. </dd>
  326. <dt><code>monitor set debug-format option1<span class="roman">[</span>,option2,...<span class="roman">]</span></code></dt>
  327. <dd><p>Specify additional text to add to debugging messages.
  328. Possible options are:
  329. </p>
  330. <dl compact="compact">
  331. <dt><code>none</code></dt>
  332. <dd><p>Turn off all extra information in debugging output.
  333. </p></dd>
  334. <dt><code>all</code></dt>
  335. <dd><p>Turn on all extra information in debugging output.
  336. </p></dd>
  337. <dt><code>timestamps</code></dt>
  338. <dd><p>Include a timestamp in each line of debugging output.
  339. </p></dd>
  340. </dl>
  341. <p>Options are processed in order. Thus, for example, if <samp>none</samp>
  342. appears last then no additional information is added to debugging output.
  343. </p>
  344. </dd>
  345. <dt><code>monitor set libthread-db-search-path [PATH]</code></dt>
  346. <dd><a name="index-gdbserver_002c-search-path-for-libthread_005fdb"></a>
  347. <p>When this command is issued, <var>path</var> is a colon-separated list of
  348. directories to search for <code>libthread_db</code> (see <a href="Threads.html#Threads">set
  349. libthread-db-search-path</a>). If you omit <var>path</var>,
  350. &lsquo;<samp>libthread-db-search-path</samp>&rsquo; will be reset to its default value.
  351. </p>
  352. <p>The special entry &lsquo;<samp>$pdir</samp>&rsquo; for &lsquo;<samp>libthread-db-search-path</samp>&rsquo; is
  353. not supported in <code>gdbserver</code>.
  354. </p>
  355. </dd>
  356. <dt><code>monitor exit</code></dt>
  357. <dd><p>Tell gdbserver to exit immediately. This command should be followed by
  358. <code>disconnect</code> to close the debugging session. <code>gdbserver</code> will
  359. detach from any attached processes and kill any processes it created.
  360. Use <code>monitor exit</code> to terminate <code>gdbserver</code> at the end
  361. of a multi-process mode debug session.
  362. </p>
  363. </dd>
  364. </dl>
  365. <a name="Tracepoints-support-in-gdbserver"></a>
  366. <h4 class="subsection">20.3.4 Tracepoints support in <code>gdbserver</code></h4>
  367. <a name="index-tracepoints-support-in-gdbserver"></a>
  368. <p>On some targets, <code>gdbserver</code> supports tracepoints, fast
  369. tracepoints and static tracepoints.
  370. </p>
  371. <p>For fast or static tracepoints to work, a special library called the
  372. <em>in-process agent</em> (IPA), must be loaded in the inferior process.
  373. This library is built and distributed as an integral part of
  374. <code>gdbserver</code>. In addition, support for static tracepoints
  375. requires building the in-process agent library with static tracepoints
  376. support. At present, the UST (LTTng Userspace Tracer,
  377. <a href="http://lttng.org/ust">http://lttng.org/ust</a>) tracing engine is supported. This support
  378. is automatically available if UST development headers are found in the
  379. standard include path when <code>gdbserver</code> is built, or if
  380. <code>gdbserver</code> was explicitly configured using <samp>--with-ust</samp>
  381. to point at such headers. You can explicitly disable the support
  382. using <samp>--with-ust=no</samp>.
  383. </p>
  384. <p>There are several ways to load the in-process agent in your program:
  385. </p>
  386. <dl compact="compact">
  387. <dt><code>Specifying it as dependency at link time</code></dt>
  388. <dd>
  389. <p>You can link your program dynamically with the in-process agent
  390. library. On most systems, this is accomplished by adding
  391. <code>-linproctrace</code> to the link command.
  392. </p>
  393. </dd>
  394. <dt><code>Using the system's preloading mechanisms</code></dt>
  395. <dd>
  396. <p>You can force loading the in-process agent at startup time by using
  397. your system&rsquo;s support for preloading shared libraries. Many Unixes
  398. support the concept of preloading user defined libraries. In most
  399. cases, you do that by specifying <code>LD_PRELOAD=libinproctrace.so</code>
  400. in the environment. See also the description of <code>gdbserver</code>&rsquo;s
  401. <samp>--wrapper</samp> command line option.
  402. </p>
  403. </dd>
  404. <dt><code>Using <small>GDB</small> to force loading the agent at run time</code></dt>
  405. <dd>
  406. <p>On some systems, you can force the inferior to load a shared library,
  407. by calling a dynamic loader function in the inferior that takes care
  408. of dynamically looking up and loading a shared library. On most Unix
  409. systems, the function is <code>dlopen</code>. You&rsquo;ll use the <code>call</code>
  410. command for that. For example:
  411. </p>
  412. <div class="smallexample">
  413. <pre class="smallexample">(gdb) call dlopen (&quot;libinproctrace.so&quot;, ...)
  414. </pre></div>
  415. <p>Note that on most Unix systems, for the <code>dlopen</code> function to be
  416. available, the program needs to be linked with <code>-ldl</code>.
  417. </p></dd>
  418. </dl>
  419. <p>On systems that have a userspace dynamic loader, like most Unix
  420. systems, when you connect to <code>gdbserver</code> using <code>target
  421. remote</code>, you&rsquo;ll find that the program is stopped at the dynamic
  422. loader&rsquo;s entry point, and no shared library has been loaded in the
  423. program&rsquo;s address space yet, including the in-process agent. In that
  424. case, before being able to use any of the fast or static tracepoints
  425. features, you need to let the loader run and load the shared
  426. libraries. The simplest way to do that is to run the program to the
  427. main procedure. E.g., if debugging a C or C<tt>++</tt> program, start
  428. <code>gdbserver</code> like so:
  429. </p>
  430. <div class="smallexample">
  431. <pre class="smallexample">$ gdbserver :9999 myprogram
  432. </pre></div>
  433. <p>Start GDB and connect to <code>gdbserver</code> like so, and run to main:
  434. </p>
  435. <div class="smallexample">
  436. <pre class="smallexample">$ gdb myprogram
  437. (gdb) target remote myhost:9999
  438. 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2
  439. (gdb) b main
  440. (gdb) continue
  441. </pre></div>
  442. <p>The in-process tracing agent library should now be loaded into the
  443. process; you can confirm it with the <code>info sharedlibrary</code>
  444. command, which will list <samp>libinproctrace.so</samp> as loaded in the
  445. process. You are now ready to install fast tracepoints, list static
  446. tracepoint markers, probe static tracepoints markers, and start
  447. tracing.
  448. </p>
  449. <div class="footnote">
  450. <hr>
  451. <h4 class="footnotes-heading">Footnotes</h4>
  452. <h3><a name="FOOT15" href="#DOCF15">(15)</a></h3>
  453. <p>If you choose a port number that
  454. conflicts with another service, <code>gdbserver</code> prints an error message
  455. and exits.</p>
  456. </div>
  457. <hr>
  458. <div class="header">
  459. <p>
  460. Next: <a href="Remote-Configuration.html#Remote-Configuration" accesskey="n" rel="next">Remote Configuration</a>, Previous: <a href="File-Transfer.html#File-Transfer" accesskey="p" rel="prev">File Transfer</a>, Up: <a href="Remote-Debugging.html#Remote-Debugging" accesskey="u" rel="up">Remote Debugging</a> &nbsp; [<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>
  461. </div>
  462. </body>
  463. </html>