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

Jan Kratochvil
2013-04-04T17:15:04Z

On Thu, 04 Apr 2013 19:01:04 +0200, Eli Zaretskii wrote:
> These are the only 2 changes and the only comments I had, right? If
> so, this is ready to go in, thanks.

For gdbinit.5 it is true but in this patch I also added the gdb.1 and
gdbserver.1 conversion (so that no *.[0-9] files are in the repository
anymore).

Sorry for not splitting it but you can follow the incremental diff below where
the gdbinit.5 change is no longer visible.

Thanks,
Jan

diff --git a/README.archer b/README.archer
new file mode 100644
index 0000000..1723606
--- /dev/null
+++ b/README.archer
@@ -0,0 +1,2 @@
+Unify man pages into texinfo format:
+https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=881892
diff --git a/gdb/Makefile.in b/gdb/Makefile.in
index 47b4338..9a0a624 100644
--- a/gdb/Makefile.in
+++ b/gdb/Makefile.in
@@ -1019,11 +1019,6 @@ check//%: force
info install-info clean-info dvi pdf install-pdf html install-html: force
@$(MAKE) $(FLAGS_TO_PASS) DO=$@ "DODIRS=$(SUBDIRS)" subdir_do

-gdb.z:gdb.1
- nroff -man $(srcdir)/gdb.1 | col -b > gdb.t
- pack gdb.t ; rm -f gdb.t
- mv gdb.t.z gdb.z
-
# Traditionally "install" depends on "all". But it may be useful
# not to; for example, if the user has made some trivial change to a
# source file and doesn't care about rebuilding or just wants to save the
@@ -1043,10 +1038,6 @@ install-only: $(CONFIG_INSTALL)
$(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(bindir) ; \
$(INSTALL_PROGRAM) gdb$(EXEEXT) \
$(DESTDIR)$(bindir)/$$transformed_name$(EXEEXT) ; \
- $(SHELL) $(srcdir)/../mkinstalldirs \
- $(DESTDIR)$(man1dir) ; \
- $(INSTALL_DATA) $(srcdir)/gdb.1 \
- $(DESTDIR)$(man1dir)/$$transformed_name.1 ; \
$(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(includedir)/gdb ; \
$(INSTALL_DATA) jit-reader.h $(DESTDIR)$(includedir)/gdb/jit-reader.h
@$(MAKE) DO=install "DODIRS=$(SUBDIRS)" $(FLAGS_TO_PASS) subdir_do
diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index 4572041..b016740 100644
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -27,6 +27,7 @@ docdir = @docdir@
pdfdir = @pdfdir@
htmldir = @htmldir@
mandir = @mandir@
+man1dir = $(mandir)/man1
man5dir = $(mandir)/man5

SHELL = @SHELL@
@@ -170,14 +171,15 @@ MANCONF = -Dman
TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl \
$(MAKEINFOFLAGS) $(MAKEINFO_EXTRA_FLAGS)

+POD2MAN1 = pod2man --center="GNU Development Tools" \
+ --release="gdb-$(VERSION)" --section=1
POD2MAN5 = pod2man --center="GNU Development Tools" \
--release="gdb-$(VERSION)" --section=5

# List of man pages generated from gdb.texi
-MAN5S = \
- gdbinit.5
-
-MANS = $(MAN5S)
+MAN1S = gdb.1 gdbserver.1
+MAN5S = gdbinit.5
+MANS = $(MAN1S) $(MAN5S)

#### Host, target, and site specific Makefile fragments come in here.
###
@@ -262,7 +264,16 @@ install-pdf: $(PDFFILES)
$(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \
done

-install-man: install-man5
+install-man: install-man1 install-man5
+
+install-man1: $(MAN1S)
+ test -z "$(man1dir)" || $(mkinstalldirs) "$(DESTDIR)$(man1dir)"
+ @list='$(MANS)'; for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ f=`echo $$p | sed -e 's|^.*/||'`; \
+ echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(man1dir)/$$f'"; \
+ $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(man1dir)/$$f"; \
+ done

install-man5: $(MAN5S)
test -z "$(man5dir)" || $(mkinstalldirs) "$(DESTDIR)$(man5dir)"
@@ -273,7 +284,17 @@ install-man5: $(MAN5S)
$(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(man5dir)/$$f"; \
done

-uninstall-man: uninstall-man5
+uninstall-man: uninstall-man1 uninstall-man5
+
+uninstall-man1:
+ @test -n "$(man1dir)" || exit 0; \
+ files=`{ l2='$(MANS)'; for i in $$l2; do echo "$$i"; done | \
+ sed -n '/\.1[a-z]*$$/p'; \
+ } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
+ -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
+ test -z "$$files" || { \
+ echo " ( cd '$(DESTDIR)$(man1dir)' && rm -f" $$files ")"; \
+ cd "$(DESTDIR)$(man1dir)" && rm -f $$files; }

uninstall-man5:
@test -n "$(man5dir)" || exit 0; \
@@ -285,7 +306,7 @@ uninstall-man5:
echo " ( cd '$(DESTDIR)$(man5dir)' && rm -f" $$files ")"; \
cd "$(DESTDIR)$(man5dir)" && rm -f $$files; }

-STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi *.pdf *.5
+STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi *.pdf *.1 *.5

# Copy the object files from a particular stage into a subdirectory.
stage1: force
@@ -570,6 +591,20 @@ annotate/index.html: $(ANNOTATE_DOC_FILES)
$(MAKEHTML) $(MAKEHTMLFLAGS) -I $(srcdir) $(srcdir)/annotate.texinfo

# Man pages
+gdb.1: $(GDB_DOC_FILES)
+ touch $@
+ -$(TEXI2POD) $(MANCONF) -Dgdb < gdb.texinfo > gdb.pod
+ -($(POD2MAN1) gdb.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+ mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+ rm -f gdb.pod
+
+gdbserver.1: $(GDB_DOC_FILES)
+ touch $@
+ -$(TEXI2POD) $(MANCONF) -Dgdbserver < gdb.texinfo > gdbserver.pod
+ -($(POD2MAN1) gdbserver.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+ mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+ rm -f gdbserver.pod
+
gdbinit.5: $(GDB_DOC_FILES)
touch $@
-$(TEXI2POD) $(MANCONF) -Dgdbinit < gdb.texinfo > gdbinit.pod
@@ -607,6 +642,6 @@ distclean: clean
maintainer-clean realclean: distclean
rm -f GDBvn.texi *.info* *.dvi *.ps *.html *.pdf $(MANS)

-install: install-info
+install: install-info install-man

-uninstall: uninstall-info
+uninstall: uninstall-info uninstall-man
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 6bc3c06..eebfc85 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -41602,51 +41602,442 @@ switch (die->tag)
@}
@end smallexample

-@include gpl.texi
-
@node Man Pages
@appendix Manual pages
@cindex Man pages

@menu
+* gdb man:: The GNU Debugger man page
+* gdbserver man:: Remote Server for the GNU Debugger man page
* gdbinit man:: gdbinit scripts
@end menu

-@node gdbinit man,,,Man Pages
+@node gdb man
+@heading gdb man
+
+@c man title gdb The GNU Debugger
+
+@c man begin SYNOPSIS gdb
+gdb [@option{-help}] [@option{-nh}] [@option{-nx}] [@option{-q}]
+[@option{-batch}] [@option{-cd=}@var{dir}] [@option{-f}]
+[@option{-b}@w{ }@var{bps}]
+ [@option{-tty=}@var{dev}] [@option{-s} @var{symfile}]
+[@option{-e}@w{ }@var{prog}] [@option{-se}@w{ }@var{prog}]
+[@option{-c}@w{ }@var{core}] [@option{-x}@w{ }@var{cmds}]
+ [@option{-d}@w{ }@var{dir}] [@var{prog}|@var{core}|@var{procID}]
+@c man end
+
+@c man begin DESCRIPTION gdb
+The purpose of a debugger such as @value{GDBN} is to allow you to see what is
+going on ``inside'' another program while it executes -- or what another
+program was doing at the moment it crashed.
+
+@value{GDBN} can do four main kinds of things (plus other things in support of
+these) to help you catch bugs in the act:
+
+@itemize @bullet
+@item
+Start your program, specifying anything that might affect its behavior.
+
+@item
+Make your program stop on specified conditions.
+
+@item
+Examine what has happened, when your program has stopped.
+
+@item
+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.
+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
+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}.
+
+You can run @code{gdb} with no arguments or options; but the most
+usual way to start @value{GDBN} is with one argument or two, specifying an
+executable program as the argument:
+
+@smallexample
+gdb program
+@end smallexample
+
+You can also start with both an executable program and a core file specified:
+
+@smallexample
+gdb program core
+@end smallexample
+
+You can, instead, specify a process ID as a second argument, if you want
+to debug a running process:
+
+@smallexample
+gdb program 1234
+@end smallexample
+
+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).
+
+Here are some of the most frequently needed @value{GDBN} commands:
+
+@c pod2man highlights the right hand side of the @item lines.
+@table @env
+@item break [@var{file}:]@var{functiop}
+Set a breakpoint at @var{function} (in @var{file}).
+
+@item run [@var{arglist}]
+Start your program (with @var{arglist}, if specified).
+
+@item bt
+Backtrace: display the program stack.
+
+@item print @var{expr}
+Display the value of an expression.
+
+@item c
+Continue running your program (after stopping, e.g. at a breakpoint).
+
+@item next
+Execute next program line (after stopping); step @emph{over} any
+function calls in the line.
+
+@item edit [@var{file}:]@var{function}
+look at the program line where it is presently stopped.
+
+@item list [@var{file}:]@var{function}
+type the text of the program in the vicinity of where it is presently stopped.
+
+@item step
+Execute next program line (after stopping); step @emph{into} any
+function calls in the line.
+
+@item help [@var{name}]
+Show information about @value{GDBN} command @var{name}, or general information
+about using @value{GDBN}.
+
+@item quit
+Exit from @value{GDBN}.
+@end table
+
+@ifset man
+For full details on @value{GDBN},
+see @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+by Richard M. Stallman and Roland H. Pesch. The same text is available online
+as the @code{gdb} entry in the @code{info} program.
+@end ifset
+@c man end
+
+@c man begin OPTIONS gdb
+Any arguments other than options specify an executable
+file and core file (or process ID); that is, the first argument
+encountered with no
+associated option flag is equivalent to a @option{-se} option, and the second,
+if any, is equivalent to a @option{-c} option if it's the name of a file.
+Many options have
+both long and short forms; both are shown here. The long forms are also
+recognized if you truncate them, so long as enough of the option is
+present to be unambiguous. (If you prefer, you can flag option
+arguments with @option{+} rather than @option{-}, though we illustrate the
+more usual convention.)
+
+All the options and command line arguments you give are processed
+in sequential order. The order makes a difference when the @option{-x}
+option is used.
+
+@table @env
+@item -help
+@itemx -h
+List all options, with brief explanations.
+
+@item -symbols=@var{file}
+@itemx -s @var{file}
+Read symbol table from file @var{file}.
+
+@item -write
+Enable writing into executable and core files.
+
+@item -exec=@var{file}
+@itemx -e @var{file}
+Use file @var{file} as the executable file to execute when
+appropriate, and for examining pure data in conjunction with a core
+dump.
+
+@item -se=@var{file}
+Read symbol table from file @var{file} and use it as the executable
+file.
+
+@item -core=@var{file}
+@itemx -c @var{file}
+Use file @var{file} as a core dump to examine.
+
+@item -command=@var{file}
+@itemx -x @var{file}
+Execute @value{GDBN} commands from file @var{file}.
+
+@item -ex @var{command}
+Execute given @value{GDBN} @var{command}.
+
+@item -directory=@var{directory}
+@itemx -d @var{directory}
+Add @var{directory} to the path to search for source files.
+
+@item -nh
+Do not execute commands from @file{~/.gdbinit}.
+
+@item -nx
+@itemx -n
+Do not execute commands from any @file{.gdbinit} initialization files.
+
+@item -quiet
+@itemx -q
+``Quiet''. Do not print the introductory and copyright messages. These
+messages are also suppressed in batch mode.
+
+@item -batch
+Run in batch mode. Exit with status @code{0} after processing all the command
+files specified with @option{-x} (and @file{.gdbinit}, if not inhibited).
+Exit with nonzero status if an error occurs in executing the @value{GDBN}
+commands in the command files.
+
+Batch mode may be useful for running @value{GDBN} as a filter, for example to
+download and run a program on another computer; in order to make this
+more useful, the message
+
+@smallexample
+Program exited normally.
+@end smallexample
+
+(which is ordinarily issued whenever a program running under @value{GDBN} control
+terminates) is not issued when running in batch mode.
+
+@item -cd=@var{directory}
+Run @value{GDBN} using @var{directory} as its working directory,
+instead of the current directory.
+
+@item -fullname
+@itemx -f
+Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells
+@value{GDBN} to output the full file name and line number in a standard,
+recognizable fashion each time a stack frame is displayed (which
+includes each time the program stops). This recognizable format looks
+like two @samp{\032} characters, followed by the file name, line number
+and character position separated by colons, and a newline. The
+Emacs-to-@value{GDBN} interface program uses the two @samp{\032}
+characters as a signal to display the source code for the frame.
+
+@item -b @var{bps}
+Set the line speed (baud rate or bits per second) of any serial
+interface used by @value{GDBN} for remote debugging.
+
+@item -tty=@var{device}
+Run using @var{device} for your program's standard input and output.
+@end table
+@c man end
+
+@c man begin SEEALSO gdb
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
+@node gdbserver man
+@heading gdbserver man
+
+@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{tty} --attach @var{PID}
+@c man end
+@end format
+
+@c man begin DESCRIPTION gdbserver
+@command{gdbserver} is a program that allows you to run @value{GDBN} on a different machine
+than the one which is running the program being debugged.
+
+@ifclear man
+@subheading Usage (server (target) side)
+@end ifclear
+@ifset man
+Usage (server (target) side):
+@end ifset
+
+First, you need to have a copy of the program you want to debug put onto
+the target system. The program can be stripped to save space if needed, as
+@command{gdbserver} doesn't care about symbols. All symbol handling is taken care of by
+the @value{GDBN} running on the host system.
+
+To use the server, you log on to the target system, and run the @command{gdbserver}
+program. You must tell it (a) how to communicate with @value{GDBN}, (b) the name of
+your program, and (c) its arguments. The general syntax is:
+
+@smallexample
+target> gdbserver COMM PROGRAM [ARGS ...]
+@end smallexample
+
+For example, using a serial port, you might say:
+
+@smallexample
+target> gdbserver /dev/com1 emacs foo.txt
+@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.
+
+To use a TCP connection, you could say:
+
+@smallexample
+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
+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
+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:
+
+@smallexample
+target> gdbserver COMM --attach PID
+@end smallexample
+
+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
+@subheading Usage (host side)
+@end ifclear
+@ifset man
+Usage (host side):
+@end ifset
+
+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
+descriptor. For example:
+
+@smallexample
+(gdb) target remote /dev/ttyb
+@end smallexample
+
+communicates with the server via serial line /dev/ttyb, and:
+
+@smallexample
+(gdb) target remote the-target:2345
+@end smallexample
+
+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'
+command, otherwise you may get an error that looks something like
+`Connection refused'.
+@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.
+@c man end
+
+@c man begin SEEALSO gdbserver
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
+@node gdbinit man
@heading gdbinit

@c man title gdbinit GDB initialization scripts

+@format
@c man begin SYNOPSIS gdbinit
-@table @env
@ifset SYSTEM_GDBINIT
-@itemx @value{SYSTEM_GDBINIT}
+@value{SYSTEM_GDBINIT}
@end ifset
-@itemx ~/.gdbinit
-@itemx ./.gdbinit
-@end table
+
+~/.gdbinit
+
+./.gdbinit
@c man end
+@end format

@c man begin DESCRIPTION gdbinit
These files contain @value{GDBN} commands to automatically execute during
@value{GDBN} startup. The lines of contents are canned sequences of commands,
-described in the @value{GDBN} manual in node @code{Sequences}, accessible by
-shell command @code{info -f gdb -n Sequences}.
+described in
+@ifset man
+the @value{GDBN} manual in node @code{Sequences}
+-- shell command @code{info -f gdb -n Sequences}.
+@end ifset
+@ifclear man
+@ref{Sequences}.
+@end ifclear

-Please read more in the @value{GDBN} manual in node @code{Startup},
-accessible by shell command @code{info -f gdb -n Startup}.
+Please read more in
+@ifset man
+the @value{GDBN} manual in node @code{Startup}
+-- shell command @code{info -f gdb -n Startup}.
+@end ifset
+@ifclear man
+@ref{Startup}.
+@end ifclear

@table @env
@ifset SYSTEM_GDBINIT
@item @value{SYSTEM_GDBINIT}
@end ifset
@ifclear SYSTEM_GDBINIT
-@item (not enabled during @value{GDBN} compilation with @code{--with-system-gdbinit})
+@item (not enabled with @code{--with-system-gdbinit} during compilation)
@end ifclear
System-wide initialization file. It is executed unless user specified
@value{GDBN} option @code{-nx} or @code{-n}.
-See more in the @value{GDBN} manual in node @code{System-wide configuration},
-accessible by shell command @code{info -f gdb -n 'System-wide configuration'}.
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{System-wide configuration}
+-- shell command @code{info -f gdb -n 'System-wide configuration'}.
+@end ifset
+@ifclear man
+@ref{System-wide configuration}.
+@end ifclear

@item ~/.gdbinit
User initialization file. It is executed unless user specified
@@ -41655,17 +42046,37 @@ User initialization file. It is executed unless user specified
@item ./.gdbinit
Initialization file for current directory. It may need to be enabled with
@value{GDBN} security command @code{set auto-load local-gdbinit}.
-See more in the @value{GDBN} manual in node @code{Init File in the Current
-Directory} - shell command
-@code{info -f gdb -n 'Init File in the Current Directory'}.
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{Init File in the Current Directory}
+-- shell command @code{info -f gdb -n 'Init File in the Current Directory'}.
+@end ifset
+@ifclear man
+@ref{Init File in the Current Directory}.
+@end ifclear
@end table
@c man end

-@ignore
@c man begin SEEALSO gdbinit
+@ifset man
gdb(1), @code{info -f gdb -n Startup}
+
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
@c man end
-@end ignore
+
+@include gpl.texi

@node GNU Free Documentation License
@appendix GNU Free Documentation License
diff --git a/gdb/gdb.1 b/gdb/gdb.1
deleted file mode 100644
index ec6c02a..0000000
--- a/gdb/gdb.1
+++ /dev/null
@@ -1,403 +0,0 @@
-.\" Copyright (C) 1991-2013 Free Software Foundation, Inc.
-.\" See section COPYING for conditions for redistribution
-.\" $Id$
-.TH gdb 1 "22may2002" "GNU Tools" "GNU Tools"
-.SH NAME
-gdb \- The GNU Debugger
-.SH SYNOPSIS
-.na
-.TP
-.B gdb
-.RB "[\|" \-help "\|]"
-.RB "[\|" \-nh "\|]"
-.RB "[\|" \-nx "\|]"
-.RB "[\|" \-q "\|]"
-.RB "[\|" \-batch "\|]"
-.RB "[\|" \-cd=\c
-.I dir\c
-\|]
-.RB "[\|" \-f "\|]"
-.RB "[\|" "\-b\ "\c
-.IR bps "\|]"
-.RB "[\|" "\-tty="\c
-.IR dev "\|]"
-.RB "[\|" "\-s "\c
-.I symfile\c
-\&\|]
-.RB "[\|" "\-e "\c
-.I prog\c
-\&\|]
-.RB "[\|" "\-se "\c
-.I prog\c
-\&\|]
-.RB "[\|" "\-c "\c
-.I core\c
-\&\|]
-.RB "[\|" "\-x "\c
-.I file\c
-\&\|]
-.RB "[\|" "\-ex "\c
-.I cmd\c
-\&\|]
-.RB "[\|" "\-d "\c
-.I dir\c
-\&\|]
-.RB "[\|" \c
-.I prog\c
-.RB "[\|" \c
-.IR core \||\| procID\c
-\&\|]\&\|]
-.ad b
-.SH DESCRIPTION
-The purpose of a debugger such as GDB is to allow you to see what is
-going on ``inside'' another program while it executes\(em\&or what another
-program was doing at the moment it crashed.
-
-GDB can do four main kinds of things (plus other things in support of
-these) to help you catch bugs in the act:
-
-.TP
-\ \ \ \(bu
-Start your program, specifying anything that might affect its behavior.
-
-.TP
-\ \ \ \(bu
-Make your program stop on specified conditions.
-
-.TP
-\ \ \ \(bu
-Examine what has happened, when your program has stopped.
-
-.TP
-\ \ \ \(bu
-Change things in your program, so you can experiment with correcting the
-effects of one bug and go on to learn about another.
-.PP
-
-You can use GDB to debug programs written in C, C++, and Modula-2.
-Fortran support will be added when a GNU Fortran compiler is ready.
-
-GDB is invoked with the shell command \c
-.B gdb\c
-\&. Once started, it reads
-commands from the terminal until you tell it to exit with the GDB
-command \c
-.B quit\c
-\&. You can get online help from \c
-.B gdb\c
-\& itself
-by using the command \c
-.B help\c
-\&.
-
-You can run \c
-.B gdb\c
-\& with no arguments or options; but the most
-usual way to start GDB is with one argument or two, specifying an
-executable program as the argument:
-.sp
-.br
-gdb\ program
-.br
-.sp
-
-You can also start with both an executable program and a core file specified:
-.sp
-.br
-gdb\ program\ core
-.br
-.sp
-
-You can, instead, specify a process ID as a second argument, if you want
-to debug a running process:
-.sp
-.br
-gdb\ program\ 1234
-.br
-.sp
-
-would attach GDB to process \c
-.B 1234\c
-\& (unless you also have a file
-named `\|\c
-.B 1234\c
-\&\|'; GDB does check for a core file first).
-
-Here are some of the most frequently needed GDB commands:
-.TP
-.B break \fR[\|\fIfile\fB:\fR\|]\fIfunction
-\&
-Set a breakpoint at \c
-.I function\c
-\& (in \c
-.I file\c
-\&).
-.TP
-.B run \fR[\|\fIarglist\fR\|]
-Start your program (with \c
-.I arglist\c
-\&, if specified).
-.TP
-.B bt
-Backtrace: display the program stack.
-.TP
-.BI print " expr"\c
-\&
-Display the value of an expression.
-.TP
-.B c
-Continue running your program (after stopping, e.g. at a breakpoint).
-.TP
-.B next
-Execute next program line (after stopping); step \c
-.I over\c
-\& any
-function calls in the line.
-.TP
-.B edit \fR[\|\fIfile\fB:\fR\|]\fIfunction
-look at the program line where it is presently stopped.
-.TP
-.B list \fR[\|\fIfile\fB:\fR\|]\fIfunction
-type the text of the program in the vicinity of where it is presently stopped.
-.TP
-.B step
-Execute next program line (after stopping); step \c
-.I into\c
-\& any
-function calls in the line.
-.TP
-.B help \fR[\|\fIname\fR\|]
-Show information about GDB command \c
-.I name\c
-\&, or general information
-about using GDB.
-.TP
-.B quit
-Exit from GDB.
-.PP
-For full details on GDB, see \c
-.I
-Using GDB: A Guide to the GNU Source-Level Debugger\c
-\&, by Richard M. Stallman and Roland H. Pesch. The same text is available online
-as the \c
-.B gdb\c
-\& entry in the \c
-.B info\c
-\& program.
-.SH OPTIONS
-Any arguments other than options specify an executable
-file and core file (or process ID); that is, the first argument
-encountered with no
-associated option flag is equivalent to a `\|\c
-.B \-se\c
-\&\|' option, and the
-second, if any, is equivalent to a `\|\c
-.B \-c\c
-\&\|' option if it's the name of a file. Many options have
-both long and short forms; both are shown here. The long forms are also
-recognized if you truncate them, so long as enough of the option is
-present to be unambiguous. (If you prefer, you can flag option
-arguments with `\|\c
-.B +\c
-\&\|' rather than `\|\c
-.B \-\c
-\&\|', though we illustrate the
-more usual convention.)
-
-All the options and command line arguments you give are processed
-in sequential order. The order makes a difference when the
-`\|\c
-.B \-x\c
-\&\|' option is used.
-
-.TP
-.B \-help
-.TP
-.B \-h
-List all options, with brief explanations.
-
-.TP
-.BI "\-symbols=" "file"\c
-.TP
-.BI "\-s " "file"\c
-\&
-Read symbol table from file \c
-.I file\c
-\&.
-
-.TP
-.B \-write
-Enable writing into executable and core files.
-
-.TP
-.BI "\-exec=" "file"\c
-.TP
-.BI "\-e " "file"\c
-\&
-Use file \c
-.I file\c
-\& as the executable file to execute when
-appropriate, and for examining pure data in conjunction with a core
-dump.
-
-.TP
-.BI "\-se=" "file"\c
-\&
-Read symbol table from file \c
-.I file\c
-\& and use it as the executable
-file.
-
-.TP
-.BI "\-core=" "file"\c
-.TP
-.BI "\-c " "file"\c
-\&
-Use file \c
-.I file\c
-\& as a core dump to examine.
-
-.TP
-.BI "\-command=" "file"\c
-.TP
-.BI "\-x " "file"\c
-\&
-Execute GDB commands from file \c
-.I file\c
-\&.
-
-.TP
-.BI "\-ex " "command"\c
-\&
-Execute given GDB \c
-.I command\c
-\&.
-
-.TP
-.BI "\-directory=" "directory"\c
-.TP
-.BI "\-d " "directory"\c
-\&
-Add \c
-.I directory\c
-\& to the path to search for source files.
-.PP
-
-.TP
-.B \-nh
-Do not execute commands from ~/.gdbinit.
-
-.TP
-.B \-nx
-.TP
-.B \-n
-Do not execute commands from any `\|\c
-.B .gdbinit\c
-\&\|' initialization files.
-
-
-.TP
-.B \-quiet
-.TP
-.B \-q
-``Quiet''. Do not print the introductory and copyright messages. These
-messages are also suppressed in batch mode.
-
-.TP
-.B \-batch
-Run in batch mode. Exit with status \c
-.B 0\c
-\& after processing all the command
-files specified with `\|\c
-.B \-x\c
-\&\|' (and `\|\c
-.B .gdbinit\c
-\&\|', if not inhibited).
-Exit with nonzero status if an error occurs in executing the GDB
-commands in the command files.
-
-Batch mode may be useful for running GDB as a filter, for example to
-download and run a program on another computer; in order to make this
-more useful, the message
-.sp
-.br
-Program\ exited\ normally.
-.br
-.sp
-
-(which is ordinarily issued whenever a program running under GDB control
-terminates) is not issued when running in batch mode.
-
-.TP
-.BI "\-cd=" "directory"\c
-\&
-Run GDB using \c
-.I directory\c
-\& as its working directory,
-instead of the current directory.
-
-.TP
-.B \-fullname
-.TP
-.B \-f
-Emacs sets this option when it runs GDB as a subprocess. It tells GDB
-to output the full file name and line number in a standard,
-recognizable fashion each time a stack frame is displayed (which
-includes each time the program stops). This recognizable format looks
-like two `\|\c
-.B \032\c
-\&\|' characters, followed by the file name, line number
-and character position separated by colons, and a newline. The
-Emacs-to-GDB interface program uses the two `\|\c
-.B \032\c
-\&\|' characters as
-a signal to display the source code for the frame.
-
-.TP
-.BI "\-b " "bps"\c
-\&
-Set the line speed (baud rate or bits per second) of any serial
-interface used by GDB for remote debugging.
-
-.TP
-.BI "\-tty=" "device"\c
-\&
-Run using \c
-.I device\c
-\& for your program's standard input and output.
-.PP
-
-.SH "SEE ALSO"
-The full documentation for
-.B gdb
-is maintained as a Texinfo manual. If the
-.B info
-and
-.B gdb
-programs and GDB's Texinfo documentation are properly installed at
-your site, the command
-.IP
-.B info gdb
-.PP
-should give you access to the complete manual.
-
-.I
-Using GDB: A Guide to the GNU Source-Level Debugger\c
-, Richard M. Stallman and Roland H. Pesch, July 1991.
-.SH COPYING
-Copyright (c) 1991, 2010 Free Software Foundation, Inc.
-.PP
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-.PP
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-.PP
-Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be included in
-translations approved by the Free Software Foundation instead of in
-the original English.
diff --git a/gdb/gdbserver/Makefile.in b/gdb/gdbserver/Makefile.in
index 08db2cc..ef839d3 100644
--- a/gdb/gdbserver/Makefile.in
+++ b/gdb/gdbserver/Makefile.in
@@ -252,8 +252,6 @@ install-only:
fi; \
$(SHELL) $(srcdir)/../../mkinstalldirs $(DESTDIR)$(bindir); \
$(INSTALL_PROGRAM) gdbserver$(EXEEXT) $(DESTDIR)$(bindir)/$$n$(EXEEXT); \
- $(SHELL) $(srcdir)/../../mkinstalldirs $(DESTDIR)$(man1dir); \
- $(INSTALL_DATA) $(srcdir)/gdbserver.1 $(DESTDIR)$(man1dir)/$$n.1
@$(MAKE) $(FLAGS_TO_PASS) DO=$@ "DODIRS=$(SUBDIRS)" subdir_do

uninstall: force
diff --git a/gdb/gdbserver/gdbserver.1 b/gdb/gdbserver/gdbserver.1
deleted file mode 100644
index 59ed0bb..0000000
--- a/gdb/gdbserver/gdbserver.1
+++ /dev/null
@@ -1,116 +0,0 @@
-.\" Copyright (C) 1993-2013 Free Software Foundation, Inc.
-.\" See section COPYING for conditions for redistribution
-.TH gdbserver 1 "2 November 1993" "Cygnus Support" "GNU Development Tools"
-.SH NAME
-gdbserver \- Remote Server for the GNU Debugger
-.SH SYNOPSIS
-.na
-.TP
-.B gdbserver
-.RB tty
-.RB prog
-.RB "[\|" args... "\|]"
-.PP
-.B gdbserver
-.RB tty
-.B --attach
-.RB PID
-.ad b
-.SH DESCRIPTION
-GDBSERVER is a program that allows you to run GDB on a different machine
-than the one which is running the program being debugged.
-
-Usage (server (target) side):
-
-First, you need to have a copy of the program you want to debug put onto
-the target system. The program can be stripped to save space if needed, as
-GDBserver doesn't care about symbols. All symbol handling is taken care of by
-the GDB running on the host system.
-
-To use the server, you log on to the target system, and run the `gdbserver'
-program. You must tell it (a) how to communicate with GDB, (b) the name of
-your program, and (c) its arguments. The general syntax is:
-
- target> gdbserver COMM PROGRAM [ARGS ...]
-
-For example, using a serial port, you might say:
-
- target> gdbserver /dev/com1 emacs foo.txt
-
-This tells gdbserver to debug emacs with an argument of foo.txt, and to
-communicate with GDB via /dev/com1. Gdbserver now waits patiently for the
-host GDB to communicate with it.
-
-To use a TCP connection, you could say:
-
- target> gdbserver host:2345 emacs foo.txt
-
-This says pretty much the same thing as the last example, except that we are
-going to communicate with the host GDB 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
-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
-GDBs `target remote' command, which will be described shortly. Note that if
-you chose a port number that conflicts with another service, gdbserver will
-print an error message and exit.
-
-On some targets, gdbserver can also attach to running programs.
-This is accomplished via the --attach argument. The syntax is:
-
- target> gdbserver COMM --attach PID
-
-PID is the process ID of a currently running process. It isn't
-necessary to point gdbserver at a binary for the running process.
-
-Usage (host side):
-
-You need an unstripped copy of the target program on your host system, since
-GDB needs to examine it's symbol tables and such. Start up GDB 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
-descriptor. For example:
-
- (gdb) target remote /dev/ttyb
-
-communicates with the server via serial line /dev/ttyb, and:
-
- (gdb) target remote the-target:2345
-
-communicates via a TCP connection to port 2345 on host `the-target', where
-you previously started up gdbserver with the same port number. Note that for
-TCP connections, you must start up gdbserver prior to using the `target remote'
-command, otherwise you may get an error that looks something like
-`Connection refused'.
-.SH OPTIONS
-You have to supply the name of the program to debug
-and the tty to communicate on; the remote GDB will do everything else.
-Any remaining arguments will be passed to the program verbatim.
-.SH "SEE ALSO"
-.RB "`\|" gdb "\|'"
-entry in
-.B info\c
-\&;
-.I
-Using GDB: A Guide to the GNU Source-Level Debugger\c
-, Richard M. Stallman and Roland H. Pesch, July 1991.
-.SH COPYING
-Copyright (c) 1993 Free Software Foundation, Inc.
-.PP
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-.PP
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-.PP
-Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be included in
-translations approved by the Free Software Foundation instead of in
-the original English.