[doc patch] gdbserver.1: Document all the options and --multi

[doc patch] gdbserver.1: Document all the options and --multi

[Jan Kratochvil]

Hi Eli,

patch is dependent on the pending patch:
	Re: [patchv2+doc] New gdbinit.5 man page + converted gdb.1+gdbserver.1
	http://sourceware.org/ml/gdb-patches/2013-04/msg00120.html
	Message-ID: <20130405150101.GA15883@host2.jankratochvil.net>

gdbserver man page was missing various parts.

The text I usually took from their existing gdb.texinfo description although
I tried to make them more brief for the man page.


Thanks,
Jan


gdb/doc/
2013-04-05  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* gdb.texinfo (gdbserver man): Rename tty to comm.  Swap --attach
	parameters order.  Remove "On some targets" for --attach.  Document the
	--multi parameter and extended-remote command.  Document all the
	options.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 2f9c68a..6263dab 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -41864,9 +41864,11 @@ Richard M. Stallman and Roland H. Pesch, July 1991.
 @c man title gdbserver Remote Server for the GNU Debugger
 @format
 @c man begin SYNOPSIS gdbserver
-gdbserver @var{tty} @var{prog} [@var{args}@dots{}]
+gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
 
-gdbserver @var{tty} --attach @var{PID}
+gdbserver --attach @var{comm} @var{pid}
+
+gdbserver --multi @var{comm}
 @c man end
 @end format
 
@@ -41926,16 +41928,25 @@ ports on the target system.  This same port number must be used in the host
 you chose a port number that conflicts with another service, @command{gdbserver} will
 print an error message and exit.
 
-On some targets, @command{gdbserver} can also attach to running programs.
+@command{gdbserver} can also attach to running programs.
 This is accomplished via the @option{--attach} argument.  The syntax is:
 
 @smallexample
-target> gdbserver @var{comm} --attach @var{pid}
+target> gdbserver --attach @var{comm} @var{pid}
 @end smallexample
 
 @var{pid} is the process ID of a currently running process.  It isn't
 necessary to point @command{gdbserver} at a binary for the running process.
 
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use the @option{--multi} command line option.
+In such case you should connect using @kbd{target extended-remote} to start
+the program you want to debug.
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
 @ifclear man
 @subheading Usage (host side)
 @end ifclear
@@ -41948,7 +41959,8 @@ You need an unstripped copy of the target program on your host system, since
 would, with the target program as the first argument.  (You may need to use the
 @option{--baud} option if the serial line is running at anything except 9600 baud.)
 That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}.  After that, the only
-new command you need to know about is @code{target remote}.  It's argument is either
+new command you need to know about is @code{target remote}
+(or @code{target extended-remote}.  It's argument is either
 a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT}
 descriptor.  For example:
 
@@ -41975,12 +41987,112 @@ you previously started up @command{gdbserver} with the same port number.  Note t
 TCP connections, you must start up @command{gdbserver} prior to using the `target remote'
 command, otherwise you may get an error that looks something like
 `Connection refused'.
+
+@command{gdbserver} can also debug multiple inferiors at once,
+described in
+@ifset man
+the @value{GDBN} manual in node @code{Inferiors and Programs}
+-- shell command @code{info -f gdb -n 'Inferiors and Programs'}.
+@end ifset
+@ifclear man
+@ref{Inferiors and Programs}.
+@end ifclear
+In such case use the @code{extended-remote} @value{GDBN} command variant:
+
+@smallexample
+(gdb) target extended-remote the-target:2345
+@end smallexample
+
+The @command{gdbserver} option @option{--multi} may or may not be used in such
+case.
 @c man end
 
 @c man begin OPTIONS gdbserver
-You have to supply the name of the program to debug
-and the tty to communicate on; the remote @value{GDBN} will do everything else.
-Any remaining arguments will be passed to the program verbatim.
+The three mode of executing @command{gdbserver} has the following three modes
+of execution.
+
+The @var{comm} parameter always specifies how to communicate with @value{GDBN},
+users typically use local TCP port 1234 specified as a @code{:1234} string.
+
+@table @env
+
+@item gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
+You have to supply how to communicate with @value{GDBN} (typically local TCP
+port @code{:1234}) and the name of the program to debug; the remote
+@value{GDBN} will do everything else.  Any remaining arguments will be passed
+to the program verbatim.
+
+@item gdbserver --attach @var{comm} @var{pid}
+You have to supply how to communicate with @value{GDBN} (typically local TCP
+port @code{:1234}) and @var{pid} of a running program; @value{GDBN} will do
+everything else.
+
+@item gdbserver --multi @var{comm}
+You have to supply how to communicate with @value{GDBN} (typically local TCP
+port @code{:1234}); @value{GDBN} can then instruct @command{gdbserver} which
+command(s) to run.
+
+@end table
+
+In each of the modes one may specify these options:
+
+@table @env
+
+@item --help
+List all options, with brief explanations.
+
+@item --version
+This option causes @command{gdbserver} to print its version number and exit.
+
+@item --attach
+@command{gdbserver} will attach to a running program.  The syntax is:
+
+@smallexample
+target> gdbserver --attach @var{comm} @var{pid}
+@end smallexample
+
+@var{pid} is the process ID of a currently running process.  It isn't
+necessary to point @command{gdbserver} at a binary for the running process.
+
+@item --multi
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use this command line option.
+Then you can connect using @kbd{target extended-remote} and start
+the program you want to debug.  The syntax is:
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
+@item --debug
+Enable @code{gdbserver} to display extra status information about the debugging
+process.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --remote-debug
+Enable @code{gdbserver} to display remote protocol debug output.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --wrapper
+Specify 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{--} indicating the end of the wrapper arguments.
+
+@item --once
+By default, @command{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.
+
+@c --disable-packet is not documented for users.
+
+@c --disable-randomization and --no-disable-randomization are superseded by
+@c QDisableRandomization.
+
+@end table
 @c man end
 
 @c man begin SEEALSO gdbserver

Re: [doc patch] gdbserver.1: Document all the options and --multi

[Eli Zaretskii]

> Date: Fri, 5 Apr 2013 20:13:16 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> 
> patch is dependent on the pending patch:
> 	Re: [patchv2+doc] New gdbinit.5 man page + converted gdb.1+gdbserver.1
> 	http://sourceware.org/ml/gdb-patches/2013-04/msg00120.html
> 	Message-ID: <20130405150101.GA15883@host2.jankratochvil.net>
> 
> gdbserver man page was missing various parts.
> 
> The text I usually took from their existing gdb.texinfo description although
> I tried to make them more brief for the man page.

Thanks.

>  That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}.  After that, the only
> -new command you need to know about is @code{target remote}.  It's argument is either
> +new command you need to know about is @code{target remote}
> +(or @code{target extended-remote}.  It's argument is either
   ^                                   ^^^^
First, that left parenthesis doesn't seem to have a matching right
one.  Also, you want "Its", not "It's".

> +The three mode of executing @command{gdbserver} has the following three modes
> +of execution.

Hmmm... one of the "three modes" here should be removed, I think.

> +The @var{comm} parameter always specifies how to communicate with @value{GDBN},
> +users typically use local TCP port 1234 specified as a @code{:1234} string.

This should probably moved after the @table which describes the 3
modes, otherwise it gets in the way of the flow.  Also, you can remove
the identical text at the beginning of each mode sdescription:

> +You have to supply how to communicate with @value{GDBN} (typically local TCP
> +port @code{:1234})

It is enough to describe everything except the 'comm' parameter.

> +In each of the modes one may specify these options:
                        ^^^
It was "you" before; let's be consistent.

> +@item --debug
> +Enable @code{gdbserver} to display extra status information about the debugging
> +process.

"Enable ... to display" is not right.  How about "Instruct" instead.

> +@item --remote-debug
> +Enable @code{gdbserver} to display remote protocol debug output.

Likewise here.

Re: [doc patch] gdbserver.1: Document all the options and --multi

[Jan Kratochvil]

On Fri, 05 Apr 2013 20:40:08 +0200, Eli Zaretskii wrote:
> > +The three mode of executing @command{gdbserver} has the following three modes
> > +of execution.
> 
> Hmmm... one of the "three modes" here should be removed, I think.

Sorry, now:

The three mode of executing @command{gdbserver} have the following options.


> > +The @var{comm} parameter always specifies how to communicate with @value{GDBN},
> > +users typically use local TCP port 1234 specified as a @code{:1234} string.
> 
> This should probably moved after the @table which describes the 3
> modes, otherwise it gets in the way of the flow.  Also, you can remove
> the identical text at the beginning of each mode sdescription:

This patch I made too fast I see.


A new one is below.


Thanks,
Jan


gdb/doc/
2013-04-05  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* gdb.texinfo (gdbserver man): Rename tty to comm.  Swap --attach
	parameters order.  Remove "On some targets" for --attach.  Document the
	--multi parameter and extended-remote command.  Document all the
	options.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 2f9c68a..481e475 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -41864,9 +41864,11 @@ Richard M. Stallman and Roland H. Pesch, July 1991.
 @c man title gdbserver Remote Server for the GNU Debugger
 @format
 @c man begin SYNOPSIS gdbserver
-gdbserver @var{tty} @var{prog} [@var{args}@dots{}]
+gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
 
-gdbserver @var{tty} --attach @var{PID}
+gdbserver --attach @var{comm} @var{pid}
+
+gdbserver --multi @var{comm}
 @c man end
 @end format
 
@@ -41926,16 +41928,25 @@ ports on the target system.  This same port number must be used in the host
 you chose a port number that conflicts with another service, @command{gdbserver} will
 print an error message and exit.
 
-On some targets, @command{gdbserver} can also attach to running programs.
+@command{gdbserver} can also attach to running programs.
 This is accomplished via the @option{--attach} argument.  The syntax is:
 
 @smallexample
-target> gdbserver @var{comm} --attach @var{pid}
+target> gdbserver --attach @var{comm} @var{pid}
 @end smallexample
 
 @var{pid} is the process ID of a currently running process.  It isn't
 necessary to point @command{gdbserver} at a binary for the running process.
 
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use the @option{--multi} command line option.
+In such case you should connect using @kbd{target extended-remote} to start
+the program you want to debug.
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
 @ifclear man
 @subheading Usage (host side)
 @end ifclear
@@ -41948,7 +41959,8 @@ You need an unstripped copy of the target program on your host system, since
 would, with the target program as the first argument.  (You may need to use the
 @option{--baud} option if the serial line is running at anything except 9600 baud.)
 That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}.  After that, the only
-new command you need to know about is @code{target remote}.  It's argument is either
+new command you need to know about is @code{target remote}
+(or @code{target extended-remote}).  Its argument is either
 a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT}
 descriptor.  For example:
 
@@ -41975,12 +41987,109 @@ you previously started up @command{gdbserver} with the same port number.  Note t
 TCP connections, you must start up @command{gdbserver} prior to using the `target remote'
 command, otherwise you may get an error that looks something like
 `Connection refused'.
+
+@command{gdbserver} can also debug multiple inferiors at once,
+described in
+@ifset man
+the @value{GDBN} manual in node @code{Inferiors and Programs}
+-- shell command @code{info -f gdb -n 'Inferiors and Programs'}.
+@end ifset
+@ifclear man
+@ref{Inferiors and Programs}.
+@end ifclear
+In such case use the @code{extended-remote} @value{GDBN} command variant:
+
+@smallexample
+(gdb) target extended-remote the-target:2345
+@end smallexample
+
+The @command{gdbserver} option @option{--multi} may or may not be used in such
+case.
 @c man end
 
 @c man begin OPTIONS gdbserver
-You have to supply the name of the program to debug
-and the tty to communicate on; the remote @value{GDBN} will do everything else.
-Any remaining arguments will be passed to the program verbatim.
+The three mode of executing @command{gdbserver} have the following options.
+
+@table @env
+
+@item gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
+For the @var{comm} parameter see below, then supply name of the program to
+debug; the remote @value{GDBN} will do everything else.  Any remaining
+arguments will be passed to the program verbatim.
+
+@item gdbserver --attach @var{comm} @var{pid}
+For the @var{comm} parameter see below, then supply @var{pid} of a running
+program; @value{GDBN} will do everything else.
+
+@item gdbserver --multi @var{comm}
+For the @var{comm} parameter see below; @value{GDBN} can then instruct
+@command{gdbserver} which command(s) to run.
+
+@end table
+
+The @var{comm} parameter  is either a device name (to use a serial line),
+or a TCP portnumber (string @code{:1234}), or @code{-} or @code{stdio} to use
+stdin/stdout of @code{gdbserver}.
+
+In each of the modes you may specify these options:
+
+@table @env
+
+@item --help
+List all options, with brief explanations.
+
+@item --version
+This option causes @command{gdbserver} to print its version number and exit.
+
+@item --attach
+@command{gdbserver} will attach to a running program.  The syntax is:
+
+@smallexample
+target> gdbserver --attach @var{comm} @var{pid}
+@end smallexample
+
+@var{pid} is the process ID of a currently running process.  It isn't
+necessary to point @command{gdbserver} at a binary for the running process.
+
+@item --multi
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use this command line option.
+Then you can connect using @kbd{target extended-remote} and start
+the program you want to debug.  The syntax is:
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
+@item --debug
+Instruct @code{gdbserver} to display extra status information about the debugging
+process.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --remote-debug
+Instruct @code{gdbserver} to display remote protocol debug output.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --wrapper
+Specify 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{--} indicating the end of the wrapper arguments.
+
+@item --once
+By default, @command{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.
+
+@c --disable-packet is not documented for users.
+
+@c --disable-randomization and --no-disable-randomization are superseded by
+@c QDisableRandomization.
+
+@end table
 @c man end
 
 @c man begin SEEALSO gdbserver

Re: [doc patch] gdbserver.1: Document all the options and --multi

[Eli Zaretskii]

> Date: Fri, 5 Apr 2013 22:20:33 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: gdb-patches@sourceware.org
> 
> +The three mode of executing @command{gdbserver} have the following options.
             ^^^^
"modes"

> +@table @env
> +
> +@item gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
> +For the @var{comm} parameter see below, then supply name of the program to
> +debug; the remote @value{GDBN} will do everything else.  Any remaining
> +arguments will be passed to the program verbatim.
> +
> +@item gdbserver --attach @var{comm} @var{pid}
> +For the @var{comm} parameter see below, then supply @var{pid} of a running
> +program; @value{GDBN} will do everything else.
> +
> +@item gdbserver --multi @var{comm}
> +For the @var{comm} parameter see below; @value{GDBN} can then instruct
> +@command{gdbserver} which command(s) to run.
> +
> +@end table
> +
> +The @var{comm} parameter  is either a device name (to use a serial line),
> +or a TCP portnumber (string @code{:1234}), or @code{-} or @code{stdio} to use
> +stdin/stdout of @code{gdbserver}.

This is OK, but perhaps will be even better if you describe the last
mode first.  Then you can put the description of @var{comm} there, and
in the other 2 modes say something like "In addition to @var{comm} as
above, supply ...".

No other comments, thanks.

Re: [doc patch] gdbserver.1: Document all the options and --multi

[Jan Kratochvil]

On Sat, 06 Apr 2013 08:16:51 +0200, Eli Zaretskii wrote:
> > +@table @env
> > +
> > +@item gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
> > +For the @var{comm} parameter see below, then supply name of the program to
> > +debug; the remote @value{GDBN} will do everything else.  Any remaining
> > +arguments will be passed to the program verbatim.
> > +
> > +@item gdbserver --attach @var{comm} @var{pid}
> > +For the @var{comm} parameter see below, then supply @var{pid} of a running
> > +program; @value{GDBN} will do everything else.
> > +
> > +@item gdbserver --multi @var{comm}
> > +For the @var{comm} parameter see below; @value{GDBN} can then instruct
> > +@command{gdbserver} which command(s) to run.
> > +
> > +@end table
> > +
> > +The @var{comm} parameter  is either a device name (to use a serial line),
> > +or a TCP portnumber (string @code{:1234}), or @code{-} or @code{stdio} to use
> > +stdin/stdout of @code{gdbserver}.
> 
> This is OK, but perhaps will be even better if you describe the last
> mode first.  Then you can put the description of @var{comm} there, and
> in the other 2 modes say something like "In addition to @var{comm} as
> above, supply ...".

I do not think it would be good, (1) the --multi mode is IMO an unusual one,
a special case and (2) I also tried to generally keep the "gdbserver --help"
output order.


Thanks,
Jan

Re: [doc patch] gdbserver.1: Document all the options and --multi

[Eli Zaretskii]

> Date: Sat, 6 Apr 2013 08:47:24 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: gdb-patches@sourceware.org
> 
> > This is OK, but perhaps will be even better if you describe the last
> > mode first.  Then you can put the description of @var{comm} there, and
> > in the other 2 modes say something like "In addition to @var{comm} as
> > above, supply ...".
> 
> I do not think it would be good, (1) the --multi mode is IMO an unusual one,
> a special case and (2) I also tried to generally keep the "gdbserver --help"
> output order.

Then let me suggest something specific:

  There are three different modes for invoking @command{gdbserver}:

  @itemize @bullet

  @item
  Debug a specific program specified by its program name:

  @smallexample
  gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
  @end smallexample

  The @var{comm} parameter specifies how should the server communicate
  with @value{GDBN}; it is either a device name (to use a serial line),
  a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use
  stdin/stdout of @code{gdbserver}.  Specify the name of the program to
  debug in @var{prog}.  Any remaining arguments will be passed to the
  program verbatim.  When the program exits, @value{GDBN} will close the
  connection, and @code{gdbserver} will exit.

  @item
  Debug a specific program by specifying the process ID of a running
  program:

  @smallexample
  gdbserver --attach @var{comm} @var{pid}
  @end smallexample

  The @var{comm} parameter is as described above.  Supply the process ID
  of a running program in @var{pid}; @value{GDBN} will do everything
  else.  Like with the previous mode, when the process @var{pid} exits,
  @value{GDBN} will close the connection, and @code{gdbserver} will exit.

  @item
  Multi-process mode -- debug more than one program/process:

  @smallexample
  gdbserver --multi @var{comm}
  @end smallexample

  In this mode, @value{GDBN} can instruct @command{gdbserver} which
  command(s) to run.  Unlike the other 2 modes, @value{GDBN} will not
  close the connection when a process being debugged exits, so you can
  debug several processes in the same session.
  @end itemize

  In each of the modes you may specify these options:

[commit] [doc patch] gdbserver.1: Document all the options and --multi

[Jan Kratochvil]

On Sat, 06 Apr 2013 10:44:55 +0200, Eli Zaretskii wrote:
> > I do not think it would be good, (1) the --multi mode is IMO an unusual one,
> > a special case and (2) I also tried to generally keep the "gdbserver --help"
> > output order.
> 
> Then let me suggest something specific:

That is most readable, thanks for the work.

Checked in.


Jan


http://sourceware.org/ml/gdb-cvs/2013-04/msg00064.html

--- src/gdb/doc/ChangeLog	2013/04/05 20:02:58	1.1434
+++ src/gdb/doc/ChangeLog	2013/04/06 08:58:53	1.1435
@@ -1,3 +1,11 @@
+2013-04-06  Jan Kratochvil  <jan.kratochvil@redhat.com>
+	    Eli Zaretskii  <eliz@gnu.org>
+
+	* gdb.texinfo (gdbserver man): Rename tty to comm.  Swap --attach
+	parameters order.  Remove "On some targets" for --attach.  Document the
+	--multi parameter and extended-remote command.  Document all the
+	options.
+
 2013-04-05  Jan Kratochvil  <jan.kratochvil@redhat.com>
 
 	* gdb.texinfo (gdb man): Mention option -p.  Include Fortran to
--- src/gdb/doc/gdb.texinfo	2013/04/05 20:02:58	1.1071
+++ src/gdb/doc/gdb.texinfo	2013/04/06 08:58:53	1.1072
@@ -41867,9 +41867,11 @@
 @c man title gdbserver Remote Server for the GNU Debugger
 @format
 @c man begin SYNOPSIS gdbserver
-gdbserver @var{tty} @var{prog} [@var{args}@dots{}]
+gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
 
-gdbserver @var{tty} --attach @var{PID}
+gdbserver --attach @var{comm} @var{pid}
+
+gdbserver --multi @var{comm}
 @c man end
 @end format
 
@@ -41929,16 +41931,25 @@
 you chose a port number that conflicts with another service, @command{gdbserver} will
 print an error message and exit.
 
-On some targets, @command{gdbserver} can also attach to running programs.
+@command{gdbserver} can also attach to running programs.
 This is accomplished via the @option{--attach} argument.  The syntax is:
 
 @smallexample
-target> gdbserver @var{comm} --attach @var{pid}
+target> gdbserver --attach @var{comm} @var{pid}
 @end smallexample
 
 @var{pid} is the process ID of a currently running process.  It isn't
 necessary to point @command{gdbserver} at a binary for the running process.
 
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use the @option{--multi} command line option.
+In such case you should connect using @kbd{target extended-remote} to start
+the program you want to debug.
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
 @ifclear man
 @subheading Usage (host side)
 @end ifclear
@@ -41951,7 +41962,8 @@
 would, with the target program as the first argument.  (You may need to use the
 @option{--baud} option if the serial line is running at anything except 9600 baud.)
 That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}.  After that, the only
-new command you need to know about is @code{target remote}.  It's argument is either
+new command you need to know about is @code{target remote}
+(or @code{target extended-remote}).  Its argument is either
 a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT}
 descriptor.  For example:
 
@@ -41978,12 +41990,131 @@
 TCP connections, you must start up @command{gdbserver} prior to using the `target remote'
 command, otherwise you may get an error that looks something like
 `Connection refused'.
+
+@command{gdbserver} can also debug multiple inferiors at once,
+described in
+@ifset man
+the @value{GDBN} manual in node @code{Inferiors and Programs}
+-- shell command @code{info -f gdb -n 'Inferiors and Programs'}.
+@end ifset
+@ifclear man
+@ref{Inferiors and Programs}.
+@end ifclear
+In such case use the @code{extended-remote} @value{GDBN} command variant:
+
+@smallexample
+(gdb) target extended-remote the-target:2345
+@end smallexample
+
+The @command{gdbserver} option @option{--multi} may or may not be used in such
+case.
 @c man end
 
 @c man begin OPTIONS gdbserver
-You have to supply the name of the program to debug
-and the tty to communicate on; the remote @value{GDBN} will do everything else.
-Any remaining arguments will be passed to the program verbatim.
+There are three different modes for invoking @command{gdbserver}:
+
+@itemize @bullet
+
+@item
+Debug a specific program specified by its program name:
+
+@smallexample
+gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
+@end smallexample
+
+The @var{comm} parameter specifies how should the server communicate
+with @value{GDBN}; it is either a device name (to use a serial line),
+a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use
+stdin/stdout of @code{gdbserver}.  Specify the name of the program to
+debug in @var{prog}.  Any remaining arguments will be passed to the
+program verbatim.  When the program exits, @value{GDBN} will close the
+connection, and @code{gdbserver} will exit.
+
+@item
+Debug a specific program by specifying the process ID of a running
+program:
+
+@smallexample
+gdbserver --attach @var{comm} @var{pid}
+@end smallexample
+
+The @var{comm} parameter is as described above.  Supply the process ID
+of a running program in @var{pid}; @value{GDBN} will do everything
+else.  Like with the previous mode, when the process @var{pid} exits,
+@value{GDBN} will close the connection, and @code{gdbserver} will exit.
+
+@item
+Multi-process mode -- debug more than one program/process:
+
+@smallexample
+gdbserver --multi @var{comm}
+@end smallexample
+
+In this mode, @value{GDBN} can instruct @command{gdbserver} which
+command(s) to run.  Unlike the other 2 modes, @value{GDBN} will not
+close the connection when a process being debugged exits, so you can
+debug several processes in the same session.
+@end itemize
+
+In each of the modes you may specify these options:
+
+@table @env
+
+@item --help
+List all options, with brief explanations.
+
+@item --version
+This option causes @command{gdbserver} to print its version number and exit.
+
+@item --attach
+@command{gdbserver} will attach to a running program.  The syntax is:
+
+@smallexample
+target> gdbserver --attach @var{comm} @var{pid}
+@end smallexample
+
+@var{pid} is the process ID of a currently running process.  It isn't
+necessary to point @command{gdbserver} at a binary for the running process.
+
+@item --multi
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use this command line option.
+Then you can connect using @kbd{target extended-remote} and start
+the program you want to debug.  The syntax is:
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
+@item --debug
+Instruct @code{gdbserver} to display extra status information about the debugging
+process.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --remote-debug
+Instruct @code{gdbserver} to display remote protocol debug output.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --wrapper
+Specify 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{--} indicating the end of the wrapper arguments.
+
+@item --once
+By default, @command{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.
+
+@c --disable-packet is not documented for users.
+
+@c --disable-randomization and --no-disable-randomization are superseded by
+@c QDisableRandomization.
+
+@end table
 @c man end
 
 @c man begin SEEALSO gdbserver

Re: [commit] [doc patch] gdbserver.1: Document all the options and --multi

[Eli Zaretskii]

> Date: Sat, 6 Apr 2013 11:01:27 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: gdb-patches@sourceware.org
> 
> On Sat, 06 Apr 2013 10:44:55 +0200, Eli Zaretskii wrote:
> > > I do not think it would be good, (1) the --multi mode is IMO an unusual one,
> > > a special case and (2) I also tried to generally keep the "gdbserver --help"
> > > output order.
> > 
> > Then let me suggest something specific:
> 
> That is most readable, thanks for the work.
> 
> Checked in.

Thanks.

When formatted, the generated man pages have something weird on their
last line:

  gdb-                              2013-04-06                      GDB(1)

It seems to come from this line in gdb.1:

.TH GDB 1 "2013-04-06" "gdb-" "GNU Development Tools"

Is that "gdb-" part due to some local problem on my system?  (I
produced the man pages without running configure, using Makefile.in,
so perhaps that screws up the results.)

Re: [commit] [doc patch] gdbserver.1: Document all the options and --multi

[Jan Kratochvil]

On Sat, 06 Apr 2013 11:31:42 +0200, Eli Zaretskii wrote:
> It seems to come from this line in gdb.1:
> 
> .TH GDB 1 "2013-04-06" "gdb-" "GNU Development Tools"

True, I have introduced a copy-paste bug.


Thanks,
Jan


gdb/doc/
2013-04-06  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* Makefile.in (POD2MAN1, POD2MAN5): Replace $(VERSION) by ../version.in.

diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index b016740..c3c5130 100644
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -172,9 +172,9 @@ TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl \
 		$(MAKEINFOFLAGS) $(MAKEINFO_EXTRA_FLAGS)
 
 POD2MAN1 = pod2man --center="GNU Development Tools" \
-		   --release="gdb-$(VERSION)" --section=1
+		   --release="gdb-`sed q $(srcdir)/../version.in`" --section=1
 POD2MAN5 = pod2man --center="GNU Development Tools" \
-		   --release="gdb-$(VERSION)" --section=5
+		   --release="gdb-`sed q $(srcdir)/../version.in`" --section=5
 
 # List of man pages generated from gdb.texi
 MAN1S = gdb.1 gdbserver.1

[commit#2] [doc patch] gdbserver.1: Document all the options and --multi

[Jan Kratochvil]

On Sat, 06 Apr 2013 13:24:43 +0200, Jan Kratochvil wrote:
> gdb/doc/
> 2013-04-06  Jan Kratochvil  <jan.kratochvil@redhat.com>
> 
> 	* Makefile.in (POD2MAN1, POD2MAN5): Replace $(VERSION) by ../version.in.

Checked in:
	http://sourceware.org/ml/gdb-cvs/2013-04/msg00065.html


Jan