You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
501 lines
24 KiB
HTML
501 lines
24 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1988-2019 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." -->
|
||
|
|
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Server (Debugging with GDB)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Server (Debugging with GDB)">
|
||
|
|
<meta name="keywords" content="Server (Debugging with GDB)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<link href="index.html#Top" rel="start" title="Top">
|
||
|
|
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Remote-Debugging.html#Remote-Debugging" rel="up" title="Remote Debugging">
|
||
|
|
<link href="Remote-Configuration.html#Remote-Configuration" rel="next" title="Remote Configuration">
|
||
|
|
<link href="File-Transfer.html#File-Transfer" rel="prev" title="File Transfer">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.indentedblock {margin-right: 0em}
|
||
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smalllisp {margin-left: 3.2em}
|
||
|
|
kbd {font-style: oblique}
|
||
|
|
pre.display {font-family: inherit}
|
||
|
|
pre.format {font-family: inherit}
|
||
|
|
pre.menu-comment {font-family: serif}
|
||
|
|
pre.menu-preformatted {font-family: serif}
|
||
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smallexample {font-size: smaller}
|
||
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smalllisp {font-size: smaller}
|
||
|
|
span.nolinebreak {white-space: nowrap}
|
||
|
|
span.roman {font-family: initial; font-weight: normal}
|
||
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<a name="Server"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
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> [<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>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="Using-the-gdbserver-Program"></a>
|
||
|
|
<h3 class="section">20.3 Using the <code>gdbserver</code> Program</h3>
|
||
|
|
|
||
|
|
<a name="index-gdbserver"></a>
|
||
|
|
<a name="index-remote-connection-without-stubs"></a>
|
||
|
|
<p><code>gdbserver</code> is a control program for Unix-like systems, which
|
||
|
|
allows you to connect your program with a remote <small>GDB</small> via
|
||
|
|
<code>target remote</code> or <code>target extended-remote</code>—but without
|
||
|
|
linking in the usual debugging stub.
|
||
|
|
</p>
|
||
|
|
<p><code>gdbserver</code> is not a complete replacement for the debugging stubs,
|
||
|
|
because it requires essentially the same operating-system facilities
|
||
|
|
that <small>GDB</small> itself does. In fact, a system that can run
|
||
|
|
<code>gdbserver</code> to connect to a remote <small>GDB</small> could also run
|
||
|
|
<small>GDB</small> locally! <code>gdbserver</code> is sometimes useful nevertheless,
|
||
|
|
because it is a much smaller program than <small>GDB</small> itself. It is
|
||
|
|
also easier to port than all of <small>GDB</small>, so you may be able to get
|
||
|
|
started more quickly on a new system by using <code>gdbserver</code>.
|
||
|
|
Finally, if you develop code for real-time systems, you may find that
|
||
|
|
the tradeoffs involved in real-time operation make it more convenient to
|
||
|
|
do as much development work as possible on another system, for example
|
||
|
|
by cross-compiling. You can use <code>gdbserver</code> to make a similar
|
||
|
|
choice for debugging.
|
||
|
|
</p>
|
||
|
|
<p><small>GDB</small> and <code>gdbserver</code> communicate via either a serial line
|
||
|
|
or a TCP connection, using the standard <small>GDB</small> remote serial
|
||
|
|
protocol.
|
||
|
|
</p>
|
||
|
|
<blockquote>
|
||
|
|
<p><em>Warning:</em> <code>gdbserver</code> does not have any built-in security.
|
||
|
|
Do not run <code>gdbserver</code> connected to any public network; a
|
||
|
|
<small>GDB</small> connection to <code>gdbserver</code> provides access to the
|
||
|
|
target system with the same privileges as the user running
|
||
|
|
<code>gdbserver</code>.
|
||
|
|
</p></blockquote>
|
||
|
|
|
||
|
|
<a name="Running-gdbserver"></a><a name="Running-gdbserver-1"></a>
|
||
|
|
<h4 class="subsection">20.3.1 Running <code>gdbserver</code></h4>
|
||
|
|
<a name="index-arguments_002c-to-gdbserver"></a>
|
||
|
|
<a name="index-gdbserver_002c-command_002dline-arguments"></a>
|
||
|
|
|
||
|
|
<p>Run <code>gdbserver</code> on the target system. You need a copy of the
|
||
|
|
program you want to debug, including any libraries it requires.
|
||
|
|
<code>gdbserver</code> does not need your program’s symbol table, so you can
|
||
|
|
strip the program if necessary to save space. <small>GDB</small> on the host
|
||
|
|
system does all the symbol handling.
|
||
|
|
</p>
|
||
|
|
<p>To use the server, you must tell it how to communicate with <small>GDB</small>;
|
||
|
|
the name of your program; and the arguments for your program. The usual
|
||
|
|
syntax is:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">target> gdbserver <var>comm</var> <var>program</var> [ <var>args</var> … ]
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><var>comm</var> is either a device name (to use a serial line), or a TCP
|
||
|
|
hostname and portnumber, or <code>-</code> or <code>stdio</code> to use
|
||
|
|
stdin/stdout of <code>gdbserver</code>.
|
||
|
|
For example, to debug Emacs with the argument
|
||
|
|
‘<samp>foo.txt</samp>’ and communicate with <small>GDB</small> over the serial port
|
||
|
|
<samp>/dev/com1</samp>:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">target> gdbserver /dev/com1 emacs foo.txt
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code>gdbserver</code> waits passively for the host <small>GDB</small> to communicate
|
||
|
|
with it.
|
||
|
|
</p>
|
||
|
|
<p>To use a TCP connection instead of a serial line:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">target> gdbserver host:2345 emacs foo.txt
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The only difference from the previous example is the first argument,
|
||
|
|
specifying that you are communicating with the host <small>GDB</small> via
|
||
|
|
TCP. The ‘<samp>host:2345</samp>’ argument means that <code>gdbserver</code> is to
|
||
|
|
expect a TCP connection from machine ‘<samp>host</samp>’ to local TCP port 2345.
|
||
|
|
(Currently, the ‘<samp>host</samp>’ part is ignored.) You can choose any number
|
||
|
|
you want for the port number as long as it does not conflict with any
|
||
|
|
TCP ports already in use on the target system (for example, <code>23</code> is
|
||
|
|
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>
|
||
|
|
<code>target remote</code> command.
|
||
|
|
</p>
|
||
|
|
<p>The <code>stdio</code> connection is useful when starting <code>gdbserver</code>
|
||
|
|
with ssh:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">(gdb) target remote | ssh -T hostname gdbserver - hello
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The ‘<samp>-T</samp>’ option to ssh is provided because we don’t need a remote pty,
|
||
|
|
and we don’t want escape-character handling. Ssh does this by default when
|
||
|
|
a command is provided, the flag is provided to make it explicit.
|
||
|
|
You could elide it if you want to.
|
||
|
|
</p>
|
||
|
|
<p>Programs started with stdio-connected gdbserver have <samp>/dev/null</samp> for
|
||
|
|
<code>stdin</code>, and <code>stdout</code>,<code>stderr</code> are sent back to gdb for
|
||
|
|
display through a pipe connected to gdbserver.
|
||
|
|
Both <code>stdout</code> and <code>stderr</code> use the same pipe.
|
||
|
|
</p>
|
||
|
|
<a name="Attaching-to-a-program"></a><a name="Attaching-to-a-Running-Program"></a>
|
||
|
|
<h4 class="subsubsection">20.3.1.1 Attaching to a Running Program</h4>
|
||
|
|
<a name="index-attach-to-a-program_002c-gdbserver"></a>
|
||
|
|
<a name="index-_002d_002dattach_002c-gdbserver-option"></a>
|
||
|
|
|
||
|
|
<p>On some targets, <code>gdbserver</code> can also attach to running programs.
|
||
|
|
This is accomplished via the <code>--attach</code> argument. The syntax is:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">target> gdbserver --attach <var>comm</var> <var>pid</var>
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><var>pid</var> is the process ID of a currently running process. It isn’t
|
||
|
|
necessary to point <code>gdbserver</code> at a binary for the running process.
|
||
|
|
</p>
|
||
|
|
<p>In <code>target extended-remote</code> mode, you can also attach using the
|
||
|
|
<small>GDB</small> attach command
|
||
|
|
(see <a href="Connecting.html#Attaching-in-Types-of-Remote-Connections">Attaching in Types of Remote Connections</a>).
|
||
|
|
</p>
|
||
|
|
<a name="index-pidof"></a>
|
||
|
|
<p>You can debug processes by name instead of process ID if your target has the
|
||
|
|
<code>pidof</code> utility:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">target> gdbserver --attach <var>comm</var> `pidof <var>program</var>`
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>In case more than one copy of <var>program</var> is running, or <var>program</var>
|
||
|
|
has multiple threads, most versions of <code>pidof</code> support the
|
||
|
|
<code>-s</code> option to only return the first process ID.
|
||
|
|
</p>
|
||
|
|
<a name="TCP-port-allocation-lifecycle-of-gdbserver"></a>
|
||
|
|
<h4 class="subsubsection">20.3.1.2 TCP port allocation lifecycle of <code>gdbserver</code></h4>
|
||
|
|
|
||
|
|
<p>This section applies only when <code>gdbserver</code> is run to listen on a TCP
|
||
|
|
port.
|
||
|
|
</p>
|
||
|
|
<p><code>gdbserver</code> normally terminates after all of its debugged processes have
|
||
|
|
terminated in <kbd>target remote</kbd> mode. On the other hand, for <kbd>target
|
||
|
|
extended-remote</kbd>, <code>gdbserver</code> stays running even with no processes left.
|
||
|
|
<small>GDB</small> normally terminates the spawned debugged process on its exit,
|
||
|
|
which normally also terminates <code>gdbserver</code> in the <kbd>target remote</kbd>
|
||
|
|
mode. Therefore, when the connection drops unexpectedly, and <small>GDB</small>
|
||
|
|
cannot ask <code>gdbserver</code> to kill its debugged processes, <code>gdbserver</code>
|
||
|
|
stays running even in the <kbd>target remote</kbd> mode.
|
||
|
|
</p>
|
||
|
|
<p>When <code>gdbserver</code> stays running, <small>GDB</small> can connect to it again later.
|
||
|
|
Such reconnecting is useful for features like <a href="Starting-and-Stopping-Trace-Experiments.html#disconnected-tracing">disconnected tracing</a>. For
|
||
|
|
completeness, at most one <small>GDB</small> can be connected at a time.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002donce_002c-gdbserver-option"></a>
|
||
|
|
<p>By default, <code>gdbserver</code> keeps the listening TCP port open, so that
|
||
|
|
subsequent connections are possible. However, if you start <code>gdbserver</code>
|
||
|
|
with the <samp>--once</samp> option, it will stop listening for any further
|
||
|
|
connection attempts after connecting to the first <small>GDB</small> session. This
|
||
|
|
means no further connections to <code>gdbserver</code> will be possible after the
|
||
|
|
first one. It also means <code>gdbserver</code> will terminate after the first
|
||
|
|
connection with remote <small>GDB</small> has closed, even for unexpectedly closed
|
||
|
|
connections and even in the <kbd>target extended-remote</kbd> mode. The
|
||
|
|
<samp>--once</samp> option allows reusing the same port number for connecting to
|
||
|
|
multiple instances of <code>gdbserver</code> running on the same host, since each
|
||
|
|
instance closes its port after the first connection.
|
||
|
|
</p>
|
||
|
|
<a name="Other-Command_002dLine-Arguments-for-gdbserver"></a><a name="Other-Command_002dLine-Arguments-for-gdbserver-1"></a>
|
||
|
|
<h4 class="subsubsection">20.3.1.3 Other Command-Line Arguments for <code>gdbserver</code></h4>
|
||
|
|
|
||
|
|
<p>You can use the <samp>--multi</samp> option to start <code>gdbserver</code> without
|
||
|
|
specifying a program to debug or a process to attach to. Then you can
|
||
|
|
attach in <code>target extended-remote</code> mode and run or attach to a
|
||
|
|
program. For more information,
|
||
|
|
see <a href="Connecting.html#g_t_002d_002dmulti-Option-in-Types-of-Remote-Connnections">--multi Option in Types of Remote Connnections</a>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddebug_002c-gdbserver-option"></a>
|
||
|
|
<p>The <samp>--debug</samp> option tells <code>gdbserver</code> to display extra
|
||
|
|
status information about the debugging process.
|
||
|
|
<a name="index-_002d_002dremote_002ddebug_002c-gdbserver-option"></a>
|
||
|
|
The <samp>--remote-debug</samp> option tells <code>gdbserver</code> to display
|
||
|
|
remote protocol debug output. These options are intended for
|
||
|
|
<code>gdbserver</code> development and for bug reports to the developers.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddebug_002dformat_002c-gdbserver-option"></a>
|
||
|
|
<p>The <samp>--debug-format=option1[,option2,...]</samp> option tells
|
||
|
|
<code>gdbserver</code> to include additional information in each output.
|
||
|
|
Possible options are:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>none</code></dt>
|
||
|
|
<dd><p>Turn off all extra information in debugging output.
|
||
|
|
</p></dd>
|
||
|
|
<dt><code>all</code></dt>
|
||
|
|
<dd><p>Turn on all extra information in debugging output.
|
||
|
|
</p></dd>
|
||
|
|
<dt><code>timestamps</code></dt>
|
||
|
|
<dd><p>Include a timestamp in each line of debugging output.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Options are processed in order. Thus, for example, if <samp>none</samp>
|
||
|
|
appears last then no additional information is added to debugging output.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwrapper_002c-gdbserver-option"></a>
|
||
|
|
<p>The <samp>--wrapper</samp> option specifies a wrapper to launch programs
|
||
|
|
for debugging. The option should be followed by the name of the
|
||
|
|
wrapper, then any command-line arguments to pass to the wrapper, then
|
||
|
|
<kbd>--</kbd> indicating the end of the wrapper arguments.
|
||
|
|
</p>
|
||
|
|
<p><code>gdbserver</code> runs the specified wrapper program with a combined
|
||
|
|
command line including the wrapper arguments, then the name of the
|
||
|
|
program to debug, then any arguments to the program. The wrapper
|
||
|
|
runs until it executes your program, and then <small>GDB</small> gains control.
|
||
|
|
</p>
|
||
|
|
<p>You can use any program that eventually calls <code>execve</code> with
|
||
|
|
its arguments as a wrapper. Several standard Unix utilities do
|
||
|
|
this, e.g. <code>env</code> and <code>nohup</code>. Any Unix shell script ending
|
||
|
|
with <code>exec "$@"</code> will also work.
|
||
|
|
</p>
|
||
|
|
<p>For example, you can use <code>env</code> to pass an environment variable to
|
||
|
|
the debugged program, without setting the variable in <code>gdbserver</code>’s
|
||
|
|
environment:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<a name="index-_002d_002dselftest"></a>
|
||
|
|
<p>The <samp>--selftest</samp> option runs the self tests in <code>gdbserver</code>:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">$ gdbserver --selftest
|
||
|
|
Ran 2 unit tests, 0 failed
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>These tests are disabled in release.
|
||
|
|
</p><a name="Connecting-to-gdbserver"></a>
|
||
|
|
<h4 class="subsection">20.3.2 Connecting to <code>gdbserver</code></h4>
|
||
|
|
|
||
|
|
<p>The basic procedure for connecting to the remote target is:
|
||
|
|
</p><ul>
|
||
|
|
<li> Run <small>GDB</small> on the host system.
|
||
|
|
|
||
|
|
</li><li> Make sure you have the necessary symbol files
|
||
|
|
(see <a href="Connecting.html#Host-and-target-files">Host and target files</a>).
|
||
|
|
Load symbols for your application using the <code>file</code> command before you
|
||
|
|
connect. Use <code>set sysroot</code> to locate target libraries (unless your
|
||
|
|
<small>GDB</small> was compiled with the correct sysroot using
|
||
|
|
<code>--with-sysroot</code>).
|
||
|
|
|
||
|
|
</li><li> Connect to your target (see <a href="Connecting.html#Connecting">Connecting to a Remote Target</a>).
|
||
|
|
For TCP connections, you must start up <code>gdbserver</code> prior to using
|
||
|
|
the <code>target</code> command. Otherwise you may get an error whose
|
||
|
|
text depends on the host system, but which usually looks something like
|
||
|
|
‘<samp>Connection refused</samp>’. Don’t use the <code>load</code>
|
||
|
|
command in <small>GDB</small> when using <code>target remote</code> mode, since the
|
||
|
|
program is already on the target.
|
||
|
|
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
<a name="Monitor-Commands-for-gdbserver"></a><a name="Monitor-Commands-for-gdbserver-1"></a>
|
||
|
|
<h4 class="subsection">20.3.3 Monitor Commands for <code>gdbserver</code></h4>
|
||
|
|
<a name="index-monitor-commands_002c-for-gdbserver"></a>
|
||
|
|
|
||
|
|
<p>During a <small>GDB</small> session using <code>gdbserver</code>, you can use the
|
||
|
|
<code>monitor</code> command to send special requests to <code>gdbserver</code>.
|
||
|
|
Here are the available commands.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>monitor help</code></dt>
|
||
|
|
<dd><p>List the available monitor commands.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>monitor set debug 0</code></dt>
|
||
|
|
<dt><code>monitor set debug 1</code></dt>
|
||
|
|
<dd><p>Disable or enable general debugging messages.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>monitor set remote-debug 0</code></dt>
|
||
|
|
<dt><code>monitor set remote-debug 1</code></dt>
|
||
|
|
<dd><p>Disable or enable specific debugging messages associated with the remote
|
||
|
|
protocol (see <a href="Remote-Protocol.html#Remote-Protocol">Remote Protocol</a>).
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>monitor set debug-format option1<span class="roman">[</span>,option2,...<span class="roman">]</span></code></dt>
|
||
|
|
<dd><p>Specify additional text to add to debugging messages.
|
||
|
|
Possible options are:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>none</code></dt>
|
||
|
|
<dd><p>Turn off all extra information in debugging output.
|
||
|
|
</p></dd>
|
||
|
|
<dt><code>all</code></dt>
|
||
|
|
<dd><p>Turn on all extra information in debugging output.
|
||
|
|
</p></dd>
|
||
|
|
<dt><code>timestamps</code></dt>
|
||
|
|
<dd><p>Include a timestamp in each line of debugging output.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Options are processed in order. Thus, for example, if <samp>none</samp>
|
||
|
|
appears last then no additional information is added to debugging output.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>monitor set libthread-db-search-path [PATH]</code></dt>
|
||
|
|
<dd><a name="index-gdbserver_002c-search-path-for-libthread_005fdb"></a>
|
||
|
|
<p>When this command is issued, <var>path</var> is a colon-separated list of
|
||
|
|
directories 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>,
|
||
|
|
‘<samp>libthread-db-search-path</samp>’ will be reset to its default value.
|
||
|
|
</p>
|
||
|
|
<p>The special entry ‘<samp>$pdir</samp>’ for ‘<samp>libthread-db-search-path</samp>’ is
|
||
|
|
not supported in <code>gdbserver</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>monitor exit</code></dt>
|
||
|
|
<dd><p>Tell gdbserver to exit immediately. This command should be followed by
|
||
|
|
<code>disconnect</code> to close the debugging session. <code>gdbserver</code> will
|
||
|
|
detach from any attached processes and kill any processes it created.
|
||
|
|
Use <code>monitor exit</code> to terminate <code>gdbserver</code> at the end
|
||
|
|
of a multi-process mode debug session.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<a name="Tracepoints-support-in-gdbserver"></a>
|
||
|
|
<h4 class="subsection">20.3.4 Tracepoints support in <code>gdbserver</code></h4>
|
||
|
|
<a name="index-tracepoints-support-in-gdbserver"></a>
|
||
|
|
|
||
|
|
<p>On some targets, <code>gdbserver</code> supports tracepoints, fast
|
||
|
|
tracepoints and static tracepoints.
|
||
|
|
</p>
|
||
|
|
<p>For fast or static tracepoints to work, a special library called the
|
||
|
|
<em>in-process agent</em> (IPA), must be loaded in the inferior process.
|
||
|
|
This library is built and distributed as an integral part of
|
||
|
|
<code>gdbserver</code>. In addition, support for static tracepoints
|
||
|
|
requires building the in-process agent library with static tracepoints
|
||
|
|
support. At present, the UST (LTTng Userspace Tracer,
|
||
|
|
<a href="http://lttng.org/ust">http://lttng.org/ust</a>) tracing engine is supported. This support
|
||
|
|
is automatically available if UST development headers are found in the
|
||
|
|
standard include path when <code>gdbserver</code> is built, or if
|
||
|
|
<code>gdbserver</code> was explicitly configured using <samp>--with-ust</samp>
|
||
|
|
to point at such headers. You can explicitly disable the support
|
||
|
|
using <samp>--with-ust=no</samp>.
|
||
|
|
</p>
|
||
|
|
<p>There are several ways to load the in-process agent in your program:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>Specifying it as dependency at link time</code></dt>
|
||
|
|
<dd>
|
||
|
|
<p>You can link your program dynamically with the in-process agent
|
||
|
|
library. On most systems, this is accomplished by adding
|
||
|
|
<code>-linproctrace</code> to the link command.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>Using the system's preloading mechanisms</code></dt>
|
||
|
|
<dd>
|
||
|
|
<p>You can force loading the in-process agent at startup time by using
|
||
|
|
your system’s support for preloading shared libraries. Many Unixes
|
||
|
|
support the concept of preloading user defined libraries. In most
|
||
|
|
cases, you do that by specifying <code>LD_PRELOAD=libinproctrace.so</code>
|
||
|
|
in the environment. See also the description of <code>gdbserver</code>’s
|
||
|
|
<samp>--wrapper</samp> command line option.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>Using <small>GDB</small> to force loading the agent at run time</code></dt>
|
||
|
|
<dd>
|
||
|
|
<p>On some systems, you can force the inferior to load a shared library,
|
||
|
|
by calling a dynamic loader function in the inferior that takes care
|
||
|
|
of dynamically looking up and loading a shared library. On most Unix
|
||
|
|
systems, the function is <code>dlopen</code>. You’ll use the <code>call</code>
|
||
|
|
command for that. For example:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">(gdb) call dlopen ("libinproctrace.so", ...)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Note that on most Unix systems, for the <code>dlopen</code> function to be
|
||
|
|
available, the program needs to be linked with <code>-ldl</code>.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>On systems that have a userspace dynamic loader, like most Unix
|
||
|
|
systems, when you connect to <code>gdbserver</code> using <code>target
|
||
|
|
remote</code>, you’ll find that the program is stopped at the dynamic
|
||
|
|
loader’s entry point, and no shared library has been loaded in the
|
||
|
|
program’s address space yet, including the in-process agent. In that
|
||
|
|
case, before being able to use any of the fast or static tracepoints
|
||
|
|
features, you need to let the loader run and load the shared
|
||
|
|
libraries. The simplest way to do that is to run the program to the
|
||
|
|
main procedure. E.g., if debugging a C or C<tt>++</tt> program, start
|
||
|
|
<code>gdbserver</code> like so:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">$ gdbserver :9999 myprogram
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Start GDB and connect to <code>gdbserver</code> like so, and run to main:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">$ gdb myprogram
|
||
|
|
(gdb) target remote myhost:9999
|
||
|
|
0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2
|
||
|
|
(gdb) b main
|
||
|
|
(gdb) continue
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The in-process tracing agent library should now be loaded into the
|
||
|
|
process; you can confirm it with the <code>info sharedlibrary</code>
|
||
|
|
command, which will list <samp>libinproctrace.so</samp> as loaded in the
|
||
|
|
process. You are now ready to install fast tracepoints, list static
|
||
|
|
tracepoint markers, probe static tracepoints markers, and start
|
||
|
|
tracing.
|
||
|
|
</p>
|
||
|
|
<div class="footnote">
|
||
|
|
<hr>
|
||
|
|
<h4 class="footnotes-heading">Footnotes</h4>
|
||
|
|
|
||
|
|
<h3><a name="FOOT15" href="#DOCF15">(15)</a></h3>
|
||
|
|
<p>If you choose a port number that
|
||
|
|
conflicts with another service, <code>gdbserver</code> prints an error message
|
||
|
|
and exits.</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
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> [<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>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|