diff options
Diffstat (limited to 'share/doc/gdb/Server.html')
| -rw-r--r-- | share/doc/gdb/Server.html | 510 |
1 files changed, 510 insertions, 0 deletions
diff --git a/share/doc/gdb/Server.html b/share/doc/gdb/Server.html new file mode 100644 index 0000000..5cfeb52 --- /dev/null +++ b/share/doc/gdb/Server.html @@ -0,0 +1,510 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 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 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Debugging with GDB: Server</title> + +<meta name="description" content="Debugging with GDB: Server"> +<meta name="keywords" content="Debugging with GDB: Server"> +<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="previous" title="File Transfer"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +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.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<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="previous">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="DOCF16" href="#FOOT16"><sup>16</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. +<a name="index-_002d_002ddebug_002dfile_002c-gdbserver-option"></a> +<a name="index-gdbserver_002c-send-all-debug-output-to-a-single-file"></a> +The <samp>--debug-file=<var>filename</var></samp> option tells <code>gdbserver</code> to +write any debug output to the given <var>filename</var>. 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-file filename</code></dt> +<dt><code>monitor set debug-file</code></dt> +<dd><p>Send any debug output to the given file, or to stderr. +</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="FOOT16" href="#DOCF16">(16)</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="previous">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> |