From 03f2bd594285c4077619f9039748ac7389cffaef Mon Sep 17 00:00:00 2001 From: Jan Kratochvil Date: Sun, 24 Apr 2011 08:02:21 +0000 Subject: gdb/ * NEWS: Document the new gdbserver --once option. gdb/doc/ * gdb.texinfo (Starting and Stopping Trace Experiments): New anchor for disconnected tracing. (Multi-Process Mode for @code{gdbserver}): Mention --multi and extended-remote relationship. Mention --once. (TCP port allocation lifecycle of @code{gdbserver}): New. gdb/gdbserver/ * remote-utils.c (handle_accept_event): Close LISTEN_DESC only if RUN_ONCE. Comment for the LISTEN_DESC delete_file_handler call. (remote_prepare): New function with most of the TCP code from ... (remote_open): ... here. Detect PORT here unconditionally. Move also setting transport_is_reliable. * server.c (run_once): New variable. (gdbserver_usage): Document it. (main): Set run_once for `--once'. Call remote_prepare. Exit after the first run if RUN_ONCE. * server.h (run_once, remote_prepare): New declarations. gdb/testsuite/ * gdb.base/solib-disc.exp: Set gdbserver_reconnect_p. * lib/gdb.exp (gdb_init): Clear gdbserver_reconnect_p. * lib/gdbserver-support.exp (gdbserver_start): Add `--once' if !gdbserver_reconnect_p.. (gdbserver_reconnect): Call error if !gdbserver_reconnect_p.. --- gdb/doc/ChangeLog | 9 +++++++++ gdb/doc/gdb.texinfo | 40 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 46 insertions(+), 3 deletions(-) (limited to 'gdb/doc') diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 1fdf0fd..aa3c893 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,12 @@ +2011-04-24 Jan Kratochvil + Eli Zaretskii + + * gdb.texinfo (Starting and Stopping Trace Experiments): New anchor + for disconnected tracing. + (Multi-Process Mode for @code{gdbserver}): Mention --multi and + extended-remote relationship. Mention --once. + (TCP port allocation lifecycle of @code{gdbserver}): New. + 2011-04-23 Eli Zaretskii * gdb.texinfo (Server): Improve indexing. Index all optional diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index ec9803d..e58dd57 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -10435,6 +10435,7 @@ Enter actions for tracepoint #1, one per line. (@value{GDBP}) @b{tstop} @end smallexample +@anchor{disconnected tracing} @cindex disconnected tracing You can choose to continue running the trace experiment even if @value{GDBN} disconnects from the target, voluntarily or @@ -16232,9 +16233,42 @@ or process ID to attach, use the @option{--multi} command line option. Then you can connect using @kbd{target extended-remote} and start the program you want to debug. -@code{gdbserver} does not automatically exit in multi-process mode. -You can terminate it by using @code{monitor exit} -(@pxref{Monitor Commands for gdbserver}). +In multi-process mode @code{gdbserver} does not automatically exit unless you +use the option @option{--once}. You can terminate it by using +@code{monitor exit} (@pxref{Monitor Commands for gdbserver}). Note that the +conditions under which @code{gdbserver} terminates depend on how @value{GDBN} +connects to it (@kbd{target remote} or @kbd{target extended-remote}). The +@option{--multi} option to @code{gdbserver} has no influence on that. + +@subsubsection TCP port allocation lifecycle of @code{gdbserver} + +This section applies only when @code{gdbserver} is run to listen on a TCP port. + +@code{gdbserver} normally terminates after all of its debugged processes have +terminated in @kbd{target remote} mode. On the other hand, for @kbd{target +extended-remote}, @code{gdbserver} stays running even with no processes left. +@value{GDBN} normally terminates the spawned debugged process on its exit, +which normally also terminates @code{gdbserver} in the @kbd{target remote} +mode. Therefore, when the connection drops unexpectedly, and @value{GDBN} +cannot ask @code{gdbserver} to kill its debugged processes, @code{gdbserver} +stays running even in the @kbd{target remote} mode. + +When @code{gdbserver} stays running, @value{GDBN} can connect to it again later. +Such reconnecting is useful for features like @ref{disconnected tracing}. For +completeness, at most one @value{GDBN} can be connected at a time. + +@cindex @option{--once}, @code{gdbserver} option +By default, @code{gdbserver} keeps the listening TCP port open, so that +additional connections are possible. However, if you start @code{gdbserver} +with the @option{--once} option, it will stop listening for any further +connection attempts after connecting to the first @value{GDBN} session. This +means no further connections to @code{gdbserver} will be possible after the +first one. It also means @code{gdbserver} will terminate after the first +connection with remote @value{GDBN} has closed, even for unexpectedly closed +connections and even in the @kbd{target extended-remote} mode. The +@option{--once} option allows reusing the same port number for connecting to +multiple instances of @code{gdbserver} running on the same host, since each +instance closes its port after the first connection. @subsubsection Other Command-Line Arguments for @code{gdbserver} -- cgit v1.1