Re: [patchv2+doc] New gdbinit.5 man page + converted gdb.1+gdbserver.1

Jan Kratochvil
2013-04-05T15:05:07Z

On Fri, 05 Apr 2013 17:01:01 +0200, Jan Kratochvil wrote:
> Sending FYI, I will check it in without further comments.

And here is an incremental form.

Jan

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index eebfc85..2f9c68a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -41650,10 +41650,10 @@ Change things in your program, so you can experiment with correcting the
effects of one bug and go on to learn about another.
@end itemize

-You can use @value{GDBN} to debug programs written in C, C++, and Modula-2.
+You can use @value{GDBN} to debug programs written in C, C@t{++}, and Modula-2.
Fortran support will be added when a GNU Fortran compiler is ready.

-GDB is invoked with the shell command @code{gdb}. Once started, it reads
+@value{GDBN} is invoked with the shell command @code{gdb}. Once started, it reads
commands from the terminal until you tell it to exit with the @value{GDBN}
command @code{quit}. You can get online help from @value{GDBN} itself
by using the command @code{help}.
@@ -41679,6 +41679,7 @@ to debug a running process:
gdb program 1234
@end smallexample

+@noindent
would attach @value{GDBN} to process @code{1234} (unless you also have a file
named @file{1234}; @value{GDBN} does check for a core file first).

@@ -41811,6 +41812,7 @@ more useful, the message
Program exited normally.
@end smallexample

+@noindent
(which is ordinarily issued whenever a program running under @value{GDBN} control
terminates) is not issued when running in batch mode.

@@ -41848,6 +41850,7 @@ documentation are properly installed at your site, the command
info gdb
@end smallexample

+@noindent
should give you access to the complete manual.

@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
@@ -41888,18 +41891,24 @@ program. You must tell it (a) how to communicate with @value{GDBN}, (b) the nam
your program, and (c) its arguments. The general syntax is:

@smallexample
-target> gdbserver COMM PROGRAM [ARGS ...]
+target> gdbserver @var{comm} @var{program} [@var{args} ...]
@end smallexample

For example, using a serial port, you might say:

@smallexample
+@ifset man
+@c @file would wrap it as F</dev/com1>.
target> gdbserver /dev/com1 emacs foo.txt
+@end ifset
+@ifclear man
+target> gdbserver @file{/dev/com1} emacs foo.txt
+@end ifclear
@end smallexample

-This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and to
-communicate with @value{GDBN} via /dev/com1. @command{gdbserver} now waits patiently for the
-host @value{GDBN} to communicate with it.
+This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and
+to communicate with @value{GDBN} via @file{/dev/com1}. @command{gdbserver} now
+waits patiently for the host @value{GDBN} to communicate with it.

To use a TCP connection, you could say:

@@ -41908,23 +41917,23 @@ target> gdbserver host:2345 emacs foo.txt
@end smallexample

This says pretty much the same thing as the last example, except that we are
-going to communicate with the host @value{GDBN} via TCP. The `host:2345' argument means
-that we are expecting to see a TCP connection from `host' to local TCP port
-2345. (Currently, the `host' part is ignored.) You can choose any number you
+going to communicate with the @code{host} @value{GDBN} via TCP. The @code{host:2345} argument means
+that we are expecting to see a TCP connection from @code{host} to local TCP port
+2345. (Currently, the @code{host} part is ignored.) You can choose any number you
want for the port number as long as it does not conflict with any existing TCP
ports on the target system. This same port number must be used in the host
-@value{GDBN}s `target remote' command, which will be described shortly. Note that if
+@value{GDBN}s @code{target remote} command, which will be described shortly. Note that if
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.
-This is accomplished via the --attach argument. The syntax is:
+This is accomplished via the @option{--attach} argument. The syntax is:

@smallexample
-target> gdbserver COMM --attach PID
+target> gdbserver @var{comm} --attach @var{pid}
@end smallexample

-PID is the process ID of a currently running process. It isn't
+@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.

@ifclear man
@@ -41937,22 +41946,30 @@ Usage (host side):
You need an unstripped copy of the target program on your host system, since
@value{GDBN} needs to examine it's symbol tables and such. Start up @value{GDBN} as you normally
would, with the target program as the first argument. (You may need to use the
---baud option if the serial line is running at anything except 9600 baud.)
-Ie: `gdb TARGET-PROG', or `gdb --baud BAUD TARGET-PROG'. After that, the only
-new command you need to know about is `target remote'. It's argument is either
-a device name (usually a serial device, like `/dev/ttyb'), or a HOST:PORT
+@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
+a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT}
descriptor. For example:

@smallexample
+@ifset man
+@c @file would wrap it as F</dev/ttyb>.
(gdb) target remote /dev/ttyb
+@end ifset
+@ifclear man
+(gdb) target remote @file{/dev/ttyb}
+@end ifclear
@end smallexample

-communicates with the server via serial line /dev/ttyb, and:
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and:

@smallexample
(gdb) target remote the-target:2345
@end smallexample

+@noindent
communicates via a TCP connection to port 2345 on host `the-target', where
you previously started up @command{gdbserver} with the same port number. Note that for
TCP connections, you must start up @command{gdbserver} prior to using the `target remote'