Initial creation of sourceware repository

author: Stan Shebs <shebs@codesourcery.com> 1999-04-16 01:35:26 +0000
committer: Stan Shebs <shebs@codesourcery.com> 1999-04-16 01:35:26 +0000
commit: c906108c21474dfb4ed285bcc0ac6fe02cd400cc (patch)
tree: a0015aa5cedc19ccbab307251353a41722a3ae13 /gdb/doc
parent: cd946cff9ede3f30935803403f06f6ed30cad136 (diff)
download: ppe42-binutils-c906108c21474dfb4ed285bcc0ac6fe02cd400cc.tar.gz
ppe42-binutils-c906108c21474dfb4ed285bcc0ac6fe02cd400cc.zip
18 files changed, 24972 insertions, 0 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
new file mode 100644
index 0000000000..1e03a80884
--- /dev/null
+++ b/gdb/doc/ChangeLog
@@ -0,0 +1,1473 @@
+Thu Feb 11 18:00:59 1999  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdb.texinfo: Update the credits.
+
+Mon Feb  8 17:33:57 1999  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdb.texinfo: Fix mistakes noticed in printout of last
+	draft, add Alpha to discussion of heuristic fence post.
+
+Fri Feb  5 17:20:00 1999  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdb.texinfo, remote.texi: Many changes; update to Seventh
+ 	Edition, merge some HP changes into mainline, describe some
+ 	previously undocumented features, describe more of the target
+ 	commands available, eliminate obsolete section on renamed
+ 	commands.
+	* all-cfg.texi, HPPA-cfg.texi: Remove some obsolete conditionals.
+
+Wed Jan 20 17:47:45 1999  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdb.texinfo: Make many HPPA conditionals unconditional,
+	including catchpoint description, since now on for all configs.
+	* all-cfg.texi: @clear HPPA, since is mainly for very HP-specific
+	specializations.
+
+Thu Jan 14 17:10:12 1999  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* Makefile.in (GDBvn.texi): Fix match expression to work with
+	current format of VERSION in gdb/Makefile.in.
+	* gdb.texinfo: Fix node ref to match new readline.
+
+Wed Jan 13 10:38:40 1999  Edith Epstein  <eepstein@sophia.cygnus.com>
+
+	* gdb.texinfo: Changes made as part of a project to merge in 
+	  changes made by HP. Documentation makes extensive use of 
+	  @ifclear HPPA and @ifset HPPA. The HP manual omits doumentation
+	  on remote debugging. There are differences in documentation
+ 	  (HP vs.  non-HP) on C++ support (aCC vs. gnu gcc++). Also,
+	  the HP manual discusses catchpoints, hardware watchpoints, and
+	  some HPUX specific limitations for shared library support.
+	  
+	  There are also a number of @node changes.
+
+1999-01-12  Jason Molenda  (jsm@bugshack.cygnus.com)
+
+	* gdbint.texinfo (Formatting): Disambiguate a sentence.
+	(C Usage): Same.
+
+Wed Jan  6 11:55:34 1999  David Taylor  <taylor@texas.cygnus.com>
+
+	The following changes were made by Edith Epstein
+ 	<eepstein@cygnus.com> as part of a project to merge in changes
+ 	made by HP.
+	
+	* HPPA-cfg.texi: new file.
+
+	* all-cfg.texi: set HPPA for HP PA-RISC targets.
+
+	* refcard.tex: change documentation about catch.
+	  removed info catch.
+
+Mon Jan  4 18:29:18 1999  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdbint.texinfo: Expand on GDB's coding standards,
+	specify the use of arg names with prototypes.
+
+1998-12-14  J.T. Conklin  <jtc@redbacknetworks.com>
+
+	* gdb.texinfo: Fix tipo.
+
+Sun Dec 13 10:27:59 1998  Andrew Cagney  <cagney@b1.cygnus.com>
+
+	* gdbint.texinfo: Document TARGET_BYTE_ORDER_DEFAULT and
+ 	TARGET_BYTE_ORDER_SELECTABLE_P.
+
+Thu Dec 10 16:07:09 1998  Andrew Cagney  <cagney@b1.cygnus.com>
+
+	* gdbint.texinfo (FRAME_FIND_SAVED_REGS): Document.
+
+1998-12-09  Jim Blandy  <jimb@zwingli.cygnus.com>
+
+	* agentexpr.texi: New file.
+
+Wed Dec  9 21:13:57 1998  Andrew Cagney  <cagney@chook>
+
+	* gdbint.texinfo (REGISTER_NAME): Replace REGISTER_NAMES.
+
+1998-12-03  J.T. Conklin  <jtc@redbacknetworks.com>
+
+	* remote.texi: Changed wording that implied that the GDB remote
+	protocol caches register values instead of GDB itself.
+
+Tue Dec  1 17:45:43 1998  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdbint.texinfo: Add some info about symbol readers.
+	(CHILL_PRODUCER, etc): Comment out descriptions, not useful.
+	(IN_SOLIB_CALL_TRAMPOLINE): Rename info from IN_SOLIB_TRAMPOLINE.
+	(IN_SOLIB_RETURN_TRAMPOLINE): Describe.
+	(KERNEL_DEBUGGING, MIPSEL): No info about these, remove.
+
+Mon Nov 30 11:32:21 1998  Andrew Cagney  <cagney@chook>
+
+	* gdbint.texinfo (FRAME_CHAIN_VALID_ALTERNATE): 
+
+Sat Nov 28 13:45:53 1998  Andrew Cagney  <cagney@b1.cygnus.com>
+
+	* gdbint.texinfo (INNER_THAN): Update, now takes parameters.
+
+Fri Nov 27 12:39:45 1998  Andrew Cagney  <cagney@chook>
+
+	* gdbint.texinfo (NO_SINGLE_STEP): Replace with
+ 	SOFTWARE_SINGLE_STEP_P and SOFTWARE_SINGLE_STEP.
+
+Wed Oct 14 10:02:40 1998  Andrew Cagney  <cagney@b1.cygnus.com>
+
+	* gdbint.texinfo: Fix minor typos.
+
+Wed Sep 30 18:03:19 1998  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdbint.texinfo: Complete overhaul.  Group descriptions more
+	logically, add more info on generic algorithms, remove much
+	obsolete and/or wrong material.
+
+Fri Jul 24 17:51:38 1998  Ian Lance Taylor  <ian@cygnus.com>
+
+	* stabs.texinfo (Method Type Descriptor): Expand and correct.
+
+Mon May  4 10:37:12 1998  Brian Youmans (3diff@gnu.org)
+
+	* refcard.tex:  Copyright, address updates.
+
+Tue Apr 21 18:09:56 1998  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdb.texinfo (EDITION, DATE): Update and change to use ordinals
+	for the edition instead of confusing GDB-version-like numbers.
+
+Mon Apr 13 14:05:00 1998  Fred Fish  <fnf@cygnus.com>
+
+	* gdb.texinfo (hbreak, watch): Fix typo, "date" -> "data".
+
+Thu Apr  2 16:52:44 1998  Jason Molenda  (crash@bugshack.cygnus.com)
+
+        * LRS: Reformat a bit to keep text under 80 columns.
+
+Thu Apr  2 16:10:36 1998  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdb.texinfo: Add some credits, mention bug monitor.
+	* remote.texi: Mention mips monitor targets.
+	* gdbint.texinfo: Describe SP_REGNUM, STEP_SKIPS_DELAY.
+	
+Mon Feb  2 17:13:03 1998  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdbint.texinfo: Remove obsolete mentions of pinsn.c and opcode.h
+ 	files, finish sorting of host vs target vs native macros, describe
+ 	some more of them.
+
+Tue Jan 13 16:44:50 1998  Fred Fish  <fnf@cygnus.com>
+
+	* gdbint.texinfo (Host Conditionals): Document change from
+	using NO_MMALLOC to it's inverse, USE_MMALLOC.
+
+Mon Nov 24 13:55:21 1997  Andrew Cagney  <cagney@b1.cygnus.com>
+
+	* gdbint.texinfo (Host Conditionals): Document
+ 	PRINTF_HAS_LONG_DOUBLE, SCANF_HAS_LONG_DOUBLE, HAVE_LONG_DOUBLE.
+
+Fri Jul  4 14:52:31 1997  Ian Lance Taylor  <ian@cygnus.com>
+
+	* gdbint.texinfo (Host Conditionals): Add CRLF_SOURCE_LINES.
+	Document LSEEK_NOT_LINEAR.
+
+Tue Mar 25 14:44:09 1997  Ian Lance Taylor  <ian@cygnus.com>
+
+	* stabs.texinfo (Stab Section Basics): Make it clear that only
+	some versions of the GNU linker remove the leading N_UNDF symbol.
+
+Thu Feb 27 17:45:19 1997  Ian Lance Taylor  <ian@cygnus.com>
+
+	* stabs.texinfo (String Field): Document type number pairs here,
+	instead of in the Sun specific section.
+	(Include Files): The GNU linker supports the N_BINCL
+	optimization.  Clarify the N_BINCL value, and what it is used
+	for.
+	(Procedures): Document N_FUN with an empty string to mark the end
+	of a function.
+	(Typedefs): Mention that Sun compilers may use N_GSYM for a type.
+	(Sun Differences): Remove this node, as the information is now
+	elsewhere in the main document.
+	(Stab Section Basics): Mention that the GNU linker may optimize
+	stabs and remove the leading N_UNDF symbol.
+
+Mon Dec  9 12:23:32 1996  Roland Pesch  <roland@wrs.com>
+
+	* gdb.texinfo, refcard.tex: Restore author credit
+
+Wed Oct  2 22:01:36 1996  Fred Fish  <fnf@fishfood.ninemoons.com>
+
+	* gdbint.texinfo (SIGTRAMP_START, SIGTRAMP_END): Update
+	documentation to account for START and END macros taking
+	one arg.
+
+Thu Aug 22 17:59:03 1996  Fred Fish  <fnf@cygnus.com>
+
+	From: Eberhard Mattes <mattes@azu.informatik.uni-stuttgart.de>
+	* gdb.texinfo (Frames): Fix typo.
+
+Tue Jul 23 10:06:20 1996  Fred Fish  <fnf@cygnus.com>
+
+	* gdbint.texinfo (NO_SINGLE_STEP): Document that single_step takes
+	a target_signal as arg type, not a pid.
+
+Fri Jul 12 11:10:05 1996  Stu Grossman  (grossman@critters.cygnus.com)
+
+	* gdb.texinfo:  Document `set assembly-language'.
+
+Thu Jul 11 13:50:28 1996  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* remote.texi: Update list of stubs in the GDB distribution.
+
+Fri Jul  5 15:38:54 1996  Fred Fish  <fnf@cygnus.com>
+
+	* gdbint.texinfo (NO_MMCHECK): Renamed from NO_MMALLOC_CHECK.
+  	Also document that some systems can use mmalloc but must define
+ 	this if their C runtime allocates memory that is later freed.
+	(MMCHECK_FORCE): Document new macro.
+	
+Fri Jun 28 22:17:10 1996  Dawn Perchik  <dawn@cygnus.com>
+
+	* remote.texi: Add documentation for target Sparclet.
+
+Mon Jun 24 18:12:22 1996  Jason Molenda  (crash@godzilla.cygnus.co.jp)
+
+	* Makefile.in (srcdir, VPATH, prefix, infodir, INSTALL, 
+	INSTALL_PROGRAM, INSTALL_DATA): Use autoconf set values.
+	* configure.in: Rewritten for autoconf.
+	* configure: New.
+
+Mon Jun 17 10:43:41 1996  Fred Fish  <fnf@cygnus.com>
+
+	* Makefile.in (DVIPS): New define, set to dvips.
+	(dvi): Add stabs.dvi.
+	(ps): New target.
+	(all-doc): Depend on info, dvi, and ps targets.
+	(STAGESTUFF): Add *.ps and *.dvi files.
+	(clean-info, clean-dvi): Remove.
+	(mostlyclean): Does not depend upon clean-info or clean-dvi,
+	rules completely rewritten.
+	(maintainer-clean): Remove clean-info and clean-dvi
+	dependencies and put their actions in the rules.
+	(gdb.ps): New target
+	(gdb.dvi, gdbgui.dvi, gdbint.dvi, stabs.dvi): Remove 
+	intermediate TeX files, whether they have 2 or 3 character
+	extensions.
+	(gdbint.ps): Add target and rules.
+	(gdb-internals): Delete unused target.
+	(Makefile): Depends upon config.status also.
+
+Sat Mar 30 15:46:58 1996  Fred Fish  <fnf@cygnus.com>
+
+	* gdbint.texinfo (CC_HAS_LONG_LONG): Clarify when/how this is
+	set.
+
+Sat Mar 16 15:10:20 1996  Fred Fish  <fnf@cygnus.com>
+
+	From Peter Schauer <Peter.Schauer@Regent.E-Technik.TU-Muenchen.DE>
+	* gdb.texinfo (Expressions): Fix erroneous array constant example.
+
+Sat Mar 16 13:28:45 1996  Fred Fish  <fnf@cygnus.com>
+
+	* gdb.texinfo: Add missing "@bullet" to some "@itemize" commands.
+
+Sat Feb 10 03:28:36 1996  Peter Schauer  (pes@regent.e-technik.tu-muenchen.de)
+
+	* gdb.texinfo (Print settings):  Document
+	`set/show print static-members' commands.
+
+Wed Jan 10 14:16:37 1996  Fred Fish  <fnf@cygnus.com>
+
+	* gdbint.texinfo (Native): Document name change, coredep.c to
+	core-aout.c.
+
+Wed Dec 13 12:35:28 1995  Ian Lance Taylor  <ian@cygnus.com>
+
+	* stabs.texinfo (Include Files): Document the values the SunOS4
+	linker creates for N_BINCL/N_EINCL/N_EXCL stabs.
+
+Fri Dec  8 21:08:44 1995  Fred Fish  <fnf@cygnus.com>
+
+	* gdbint.texinfo (Releases): Change gdb.tar.Z to gdb.tar.gz.
+	Fix typo.
+
+Fri Dec  1 11:07:50 1995  Fred Fish  <fnf@cygnus.com>
+
+	* gdbint.texinfo (Releases): Make "gdb.tar.gz" rather than
+	"gdb.tar.Z".
+
+Wed Sep 20 13:14:10 1995  Ian Lance Taylor  <ian@cygnus.com>
+
+	* Makefile.in (maintainer-clean): New target, synonym for
+	realclean.
+
+Thu Aug  3 10:45:37 1995  Fred Fish  <fnf@cygnus.com>
+
+	* Update all FSF addresses except those in COPYING* files.
+
+Wed Jul 19 18:43:03 1995  Stan Shebs  <shebs@andros.cygnus.com>
+
+	From Richard Earnshaw (rearnsha@armltd.co.uk):
+	* gdb.texinfo (convenience variables): Document $_exitcode.
+	(quit): Document optional expression to use as exit code.
+
+Thu Jun 22 21:27:33 1995  Victoria Mixon  <victoria@cygnus.com>
+
+	* gdb.texinfo, remote.texi: Brought up to date with various
+	GDB changes.
+
+Tue Jun 20 14:35:38 1995  Stan Shebs  <shebs@andros.cygnus.com>
+
+	* gdb.texinfo: Update dates and versions, fix comments about
+	hardware watchpoints in future releases and about the
+	sharedlibrary command.
+
+Mon May  8 09:30:36 1995  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Remove node `XCOFF differences'.  Describe value of
+	C_FUN stab.  Other cleanups.
+
+Wed Apr 19 07:02:19 1995  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* remote.texi (Bootstrapping): Clarify that flush_i_cache is only
+	for the sparc stub.
+
+Tue Apr 11 11:41:49 1995  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* annotate.texi: Clarify which addresses have differing formats
+	depending on the language and which do not.
+
+Tue Mar 28 16:56:22 1995  J.T. Conklin  <jtc@rtl.cygnus.com>
+
+	* remote.texi (NetWare): Changed example to use BOARD= instead of
+	  NODE= argument to reflect correspoding change to gdbserve.nlm.
+
+Fri Mar 17 06:47:02 1995  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Negative Type Numbers): Mention the fact that
+	GDB, as well as AIX dbx, supports the size type attribute.
+
+Thu Mar 16 12:11:32 1995  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Negative Type Numbers): Document types -31 to -34.
+
+Mon Mar 13 16:49:13 1995  Per Bothner  <bothner@kalessin.cygnus.com>
+
+	* gdb.texinfo (Define):  Document $arg0... arguments to commands,
+	and new 'if' and 'while' commands.
+
+Fri Feb 17 15:24:35 1995  Per Bothner  <bothner@kalessin.cygnus.com>
+
+	* gdb.texinfo (Artificial arrays):  Note use of coerce-to-array-type.
+
+Wed Feb 15 11:59:18 1995  J.T. Conklin  <jtc@rtl.cygnus.com>
+
+	* all-cfg.texi: New flag, GDBSERVE, for NetWare's gdbserve.nlm.
+	* remote.texi (NetWare): New node, how to use gdbserve.nlm on
+	  NetWare targets.  Mostly stolen from the Server node.
+
+Fri Feb 10 20:20:08 1995  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Setting): Talk about the language of a source file
+	versus the working language.  The old documentation did not match
+	what GDB did.
+
+Wed Feb  1 20:26:36 1995  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Source Files): Document N_SO used to mark the end
+	of a source file.
+
+Mon Jan 23 14:23:37 1995  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Processes): New node.
+
+Tue Jan 17 14:09:03 1995  Ian Lance Taylor  <ian@sanguine.cygnus.com>
+
+	* remote.texi: Update documentation of set/show mipsfpu.
+
+
+Sun Sep  4 16:47:21 1994  Stan Shebs  (shebs@andros.cygnus.com)
+
+	* gdbint.texinfo: Removed mentions of some incorrectly placed and
+	obsolete conditionals, described some others.
+
+Mon Aug  1 15:42:39 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdbint.texinfo: Remove references to BROKEN_LARGE_ALLOCA and
+	SET_STACK_LIMIT_HUGE; they were removed from GDB 14 May 1994.
+
+Mon Aug  1 15:12:02 1994  Stan Shebs  (shebs@andros.cygnus.com)
+
+	* gdbint.texinfo: Put regex conditionals in their own table.
+
+Tue Jul 26 18:32:52 1994  Stan Shebs  (shebs@andros.cygnus.com)
+
+	* gdbint.texinfo: Removed mentions of many obsolete conditionals,
+	described or fixed the descriptions of many others.
+
+Sun Jul 17 14:14:03 1994  Stan Shebs  (shebs@andros.cygnus.com)
+
+	* gdb.texinfo: Add some more credits.
+	* gdbint.texinfo: Capitalize GDB consistently, describe some
+	macros and remove some.
+
+Thu Jul 14 18:43:17 1994  Stan Shebs  (shebs@andros.cygnus.com)
+
+	* gdbint.texinfo: Removed mentions of many incorrectly placed and
+	obsolete conditionals, described some others.
+
+Tue Jul 12 12:23:15 1994  Peter Schauer  (pes@regent.e-technik.tu-muenchen.de)
+
+	* gdb.texinfo (help targets):  Changed to `help target', which
+	is the correct gdb command.
+
+Wed Jun 22 18:00:51 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* annotate.texi (TODO): New node, for keeping track of annotations
+	suggested but not yet implemented.
+
+Wed Jun  1 16:10:45 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Statics): Value of xcoff C_BSTAT points to
+	another symbol, it is not the address itself.
+
+Thu May  5 20:23:36 1994  Stan Shebs  (shebs@andros.cygnus.com)
+
+	* stabs.texinfo (Stab Section Basics): Add comment about alignment
+	of stabs-in-coff sections.
+
+Wed May  4 06:26:11 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* annotate.texi: Change edition to 0.5 and date to May 1994.
+	Add index.
+	(Frames): New node, for frame annotation.
+	(Displays): New node, for display annotation.
+
+	* remote.texi (MIPS Remote): Say that set timeout doesn't apply
+	when waiting for your program to stop.
+
+Fri Apr 29 18:24:46 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* annotate.texi (Breakpoint Info): Document annotation of header
+	fields and record annotation.
+
+Thu Apr 28 07:44:28 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* annotate.texi: New file, to document annotations.
+
+Thu Apr 21 14:20:51 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* Makefile.in (clean): Don't remove GDBvn.texi (apparently on Jan
+	16 I meant to make this change but did not).  Do remove gdb-cfg.texi.
+
+Wed Apr 20 11:22:48 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Stab Section Basics): Say what is in .stab
+	section, and say n_strx field is compilation unit relative.
+	* stabs.texinfo: Don't use @code for a.out when it is the name of
+	an object file format.
+
+Wed Apr 13 20:29:54 1994  Jim Kingdon  (kingdon@deneb.cygnus.com)
+
+	* gdb.texinfo: Refer to file names, not path names, per rms
+	convention.
+	(Arguments): Fix typo.
+
+Thu Mar 24 08:09:12 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Global Variables): Talk about stabs in files
+	where variables are referenced, but not defined.
+
+Wed Mar 23 07:16:36 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Move stuff on @ and # type descriptors from node
+	Cplusplus to new nodes Member Type Descriptor and Method Type
+	Descriptor.  Re-write stuff for #.
+
+Wed Mar 16 08:20:19 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Print Settings): Don't document "set print
+	fast-symbolic-addr off".  The bug which it worked around was fixed
+	on 25 Feb 94 in coffread.c, so I'm nuking the command.
+
+	* stabs.texinfo (Alternate Entry Points): New node, rewritten from
+	N_ENTRY node.
+
+	* stabs.texinfo (Type Descriptors): Add 'Y' type descriptor.
+
+Tue Mar 15 08:43:02 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdbint.texinfo (Host Conditionals, Target Conditionals): Remove
+	references to ieee-float.c.
+
+Fri Mar 11 08:09:40 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Set Breaks): Update documentation for tbreak to
+	match what the code actually does.
+
+Wed Mar  9 19:43:05 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Symbol Descriptors): Add OS9000 symbol descriptor s.
+
+Tue Mar  1 17:04:43 1994  Jim Kingdon  (kingdon@deneb.cygnus.com)
+
+	* stabs.texinfo (Type Descriptors): Add OS9000 type descriptors c,
+	i, and b.
+
+Wed Feb 23 10:44:18 1994  Jim Kingdon  (kingdon@rtl.cygnus.com)
+
+	* stabs.texinfo: Document N_RBRAC as function relative for COFF as
+	well as for ELF and SOM.  Unify the descriptions of ELF and SOM
+	as "stabs in sections" rather than just saying "ELF and SOM".
+	Also make that stuff apply to COFF.
+
+Fri Feb 18 08:25:58 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Formatting Documentation): Change GhostScript to
+	Ghostscript.
+
+Fri Feb  4 06:31:31 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Continuing and Stepping): When talking about "step"
+	versus functions without line numbers, also mention stepping into
+	them as well as "step" when you are in them.  Tell the user how to
+	deal with the situation.  Add comment about "debugging information".
+
+Thu Feb  3 11:39:59 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Enumerations): Document restriction on where
+	enumeration types can appear and still win with GDB.
+
+Wed Feb  2 11:29:17 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Negative Type Numbers): Document format for type
+	-16.
+
+Thu Jan 27 16:53:56 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Selection, Frame Info): Update information about
+	arbitrary frame specficiations.
+
+Wed Jan 26 15:31:57 1994  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo, remote.texi: general editing pass prior to Net release
+
+Tue Jan 25 12:12:04 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (String Field): Discuss continuing stabs with ?.
+
+Wed Jan 19 06:39:24 1994  David J. Mackenzie  (djm@thepub.cygnus.com)
+
+	* stabs.texinfo (Non-Stab Symbol Types): Mention N_SET* | N_EXT.
+
+Sun Jan 16 12:43:32 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Re-do stuff about C_BSTAT and move from XCOFF
+	Differences node to Statics node.
+	(Statics): Discuss XCOFF use of V symbol descriptor.
+
+	* Makefile.in: Remove refcard.dvi and GDBvn.texi in realclean,
+	not clean.
+
+Wed Jan 12 21:29:54 1994  John Gilmore  (gnu@cygnus.com)
+
+	* gdb.texinfo (Print Settings): Document `set print
+	fast-symbolic-addr' and improve the doc for some other
+	`set print's.
+
+Mon Jan  3 17:23:07 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (String Field): Talk about defining several type
+	numbers at once.
+	Fix lint regarding changing node ELF Transformations to
+	ELF and SOM Transformations.
+
+Fri Dec 31 00:42:43 1993  John Gilmore  (gnu@cygnus.com)
+
+	* stabs.texinfo:  Insert Peter Kessler's name as inventor (I think).
+
+Tue Dec 28 09:30:40 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Cross-References): `::' is for nested types only
+	within <>.
+	(Structures): Document static members.
+
+Mon Dec 27 13:55:04 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Document S type attribute.
+
+Sun Dec 26 20:46:36 1993  Jeffrey A. Law  (law@snake.cs.utah.edu)
+
+	* stabs.texinfo: Add notes about stabs-in-som where appropriate.
+
+Fri Dec  3 19:13:19 1993  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Fix a few typos.
+
+Sun Nov 28 18:06:25 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo, remote.texi: formatting improvements
+
+	* gdb.texinfo (New Features): mention threads.
+	(Summary, C): fix xrefs in newly contributed text.
+	(Threads): index entries, clarifications, example
+	(passim): minor typos fixed, phrasing improvements
+
+	* remote.texi (Bootstrapping): rephrase text on ^C and add index
+	entries; (Server): explain use of gdbserver w/real-time systems,
+	add example of conflicting TCP port; (MIPS Remote) break up
+	running text into table, highlighting commands, and add example.
+	
+Wed Nov 24 14:15:56 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* refcard.tex: avoid bad linebreaks even when REFEDITS=psrc.sed
+
+Fri Nov 12 16:10:58 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Nested Symbols): New node.
+	(String Field, Symbol Descriptors, Cross-References): Refer to it.
+
+Thu Nov 11 13:26:45 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Stabs in ELF): Clarify how Bbss.bss work with respect
+	to picking which Bbss.bss symbol to use, and (because there seems to
+	be no good way of doing it) re-write some of the text to make it
+	sound like Bbss.bss isn't such a great idea after all (as currently
+	designed).
+
+	* gdb.texinfo (C): In addition to saying people have to use g++ for
+	good results, say they have to use stabs.  Specifically say cfront
+	doesn't work well.
+	(Summary): Merge in information on Modula-2, Pascal, and Chill from
+	the gdb README.  Add xrefs to places where the support for the various
+	languages is described in detail.
+
+Mon Nov  8 11:47:34 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Clean up stuff about visibility and virtual
+	characters.
+
+	* stabs.texinfo (N_M2C): Cite Sun doc.
+
+Fri Nov  5 16:27:27 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo: updates re threads.
+	* remote.texinfo: avoid index entries starting with digits.
+
+Tue Nov  2 09:08:37 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Enumerations): Talk about large, negative and
+	octal values.  Clean up cross reference to type attributes.
+	(String Field): Say that GDB 4.11 supports size attribute.
+
+Sun Oct 31 13:31:10 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* remote.texi (VxWorks Remote): Clarify that rebuilding VxWorks kernel
+	is a mandatory step.  Make the stuff about that more concise.
+
+Wed Oct 27 00:25:46 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Class Names): New node.
+
+	* gdb.texinfo (Command Files): Explain order of init file reading.
+
+	* remote.texi (Bootstrapping): Talk about getting the serial driver
+	to deal with ^C sent by gdb to stop the remote system.
+
+Mon Oct 25 03:25:41 1993  Tom Lord  (lord@cygnus.com)
+
+	* libgdb.texinfo (I/O): incorporated better phrasing from rich.
+
+	* libgdb.texinfo (Defining Commands): made the DOC arg
+	to gdb_define_app_command a char * instead of char **
+	per a suggestion from kingdon.
+
+	* libgdb.texinfo: total rewrite from a different starting
+	premise.
+
+Wed Oct 20 18:07:44 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Local Variable Parameters): Re-write paragraph on
+	floats passed as doubles (to improve clarity).
+
+Tue Oct 19 14:21:18 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo (Source Path): index entries for $cwd, $pdir
+
+	* a4rc.sed: update to work with Andreas Vogel papersize params
+
+	* refcard.tex: use Andreas Vogel simplifications of papersize
+	params; remove useless version info; update copyright date.
+
+Tue Oct 19 10:46:22 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Symbols): Add class NAME to doc for ptype.
+
+Tue Oct 12 09:11:45 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Files): Say what address the load command loads it at.
+
+	* stabs.texinfo (Common Blocks): Minor cleanups.
+
+	* stabs.texinfo: Update ld stabs in elf relocation to reflect the fact
+	that Sun has backed away from the linker kludge and thus the relevant
+	issue is changes to the SunPRO tools, not the Solaris linker.
+
+	* stabs.texinfo (Traditional Integer Types): Clean up description
+	of octal bounds a little bit.  Document extra leading zeroes.
+
+Thu Oct  7 16:15:37 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Signaling): Update for symbolic symbol names
+	and add a section explaining the difference between the GDB
+	signal command and the shell kill utility.
+
+Wed Oct  6 13:23:01 1993  Tom Lord  (lord@rtl.cygnus.com)
+
+	* libgdb.texinfo: added `@' to braces that were unescaped.
+
+Mon Oct  4 10:42:18 1993  Tom Lord  (lord@rtl.cygnus.com)
+
+	* libgdb.texinfo: new file.  Spec for the gdb library.
+
+Sun Oct  3 15:26:56 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Include Files): Fix typo (start -> end).
+
+Thu Sep 30 18:24:56 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo, remote.texi: assorted small improvements, mostly
+	from Melissa at FSF's editing pass.
+
+Thu Sep 30 11:54:38 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo: Remove stuff about ar and 14 character filenames.
+	I believe this was fixed by the 13 Sep 89 change to print_frame_info.
+	Also, modern versions of ar like BSD 4.4 or SVR4 don't have this bug.
+
+Wed Sep 22 21:22:11 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* remote.texi (Bootstrapping): Discuss 386 call gates.
+
+Sat Sep 18 17:10:44 1993  Jim Kingdon  (kingdon@poseidon.cygnus.com)
+
+	* stabs.texinfo (Based Variables): New node.
+
+Thu Sep 16 17:48:55 1993  Jim Kingdon  (kingdon@cirdan.cygnus.com)
+
+	* stabs.texinfo (Negative Type Numbers): Re-write discussions of
+	names, sizes, and formats to suggest how not to lose.
+
+Sat Sep 11 09:35:11 1993  Jim Kingdon  (kingdon@poseidon.cygnus.com)
+
+	* stabs.texinfo (Methods): Fix typo.
+
+Fri Sep 10 06:34:20 1993  David J. Mackenzie  (djm@thepub.cygnus.com)
+
+	* gdb.texinfo: Fix a few typos.
+
+Wed Sep  8 09:11:52 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo: Clarify how well it works with Fortran.
+
+	* stabs.texinfo (Stabs In ELF, Statics, ELF Transformations):
+	More on relocating stabs in ELF files.
+
+Tue Sep  7 13:45:02 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Stabs In ELF): Talk about N_FUN value.
+
+Mon Sep  6 19:23:18 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Local Variable Parameters): Talk about nameless
+	parameters on VAX.
+
+Fri Sep  3 17:06:08 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo: @up/@down -> @raisesections/@lowersections
+
+Fri Sep  3 12:04:15 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Make info author notice match the TeX author notice.
+
+Tue Aug 31 13:21:06 1993  David J. Mackenzie  (djm@thepub.cygnus.com)
+
+	* stabs.texinfo: Initial-caps all words in node names and
+	non-trivial words in section names.
+
+Mon Aug 30 11:13:16 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Many minor cleanups.
+
+	* stabs.texinfo: Remove @deffn except from Expanded Reference node.
+
+Sat Aug 28 12:08:09 1993  David J. MacKenzie  (djm@edison.eng.umd.edu)
+
+	* stabs.texinfo: Remove full description of big example.
+	It's not really helpful; just use pieces of it where appropriate.
+	Add more Texinfo formatting directives (@samp, etc.).
+	Use @deffn to define stab types.
+	Eliminate some wordiness.  Break up some nodes.
+	Add an (alphabetized) index of symbol types.
+	Use consistent capitalization style in node and section names.
+
+Thu Aug 26 06:36:31 1993  Fred Fish  (fnf@deneb.cygnus.com)
+
+	* gdb.texinfo:  Change typo "Two two" to "The two".
+
+Sun Aug 22 12:15:18 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (XCOFF-differences): Remove references to
+	non-existent types N_DECL and N_RPSYM.
+
+	* stabs.texinfo (String Field): Say that type attributes bug is
+	fixed in GDB 4.10, since it is.
+
+	* stabs.texinfo: Clean up djm cleanups, and more cleanups of my own.
+
+Sat Aug 21 04:32:28 1993  David MacKenzie  (djm@cygnus.com)
+
+	* stabs.texinfo: Formatting cleanups.
+
+Fri Aug 20 20:49:53 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: When explaining the n_type of a stab, standardize
+	how we do it ('#' as a comment indicator, "36 is N_FUN" as text,
+	no tabs, use @r).
+	(Global Variables): Clean up.
+
+Tue Aug 17 15:57:27 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Stack Variables): Re-write.
+
+Mon Aug 16 21:20:08 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Stabs-in-elf): Talk about getting the start
+	addresses of a source file.  Also revise formatting.
+	Change "object module" or "object file" to "source file".
+	Various: Miscellaneous cleanups.
+
+Thu Aug 12 15:11:51 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Point to mangling info in gcc's gpcompare.texi.
+
+Tue Aug 10 16:57:49 1993  Stan Shebs  (shebs@rtl.cygnus.com)
+
+	* gdbint.texinfo: Removed many nonsensical machine-collected
+	host and target conditionals, described some of the remainder.
+
+Tue Aug 10 13:28:30 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdbint.texinfo (Getting Started): Use @itemize, not @table.
+
+	* gdbint.texinfo (Top): Add name to @top line, and re-write the
+	paragraph which follows.
+
+	* gdbint.texinfo (Host): Use @code not @samp for Makefile
+	variables.  Looks better and avoids overful hbox.
+
+Fri Jul 30 18:26:21 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Procedures): Improve stuff on nested functions.
+
+Thu Jul 29 15:10:58 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* remote.texi: (MIPS Remote) clearer doc for set/show timeout,
+	retransmit-timeout
+
+Thu Jul 29 13:16:09 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdbint.texinfo: Update statement about `some ancient Unix
+	systems, like Ultrix 4.0' to Ultrix 4.2.
+
+Wed Jul 28 15:26:53 1993  Roland H. Pesch  (pesch@el_bosque.cygnus.com)
+
+	* h8-cfg.texi, all-cfg.texi: new flag GDBSERVER
+
+	* Makefile.in: depend on remote.texi rather than gdbinv-s.texi
+
+	* remote.texi: (Server) New node on gdbserver.  (Remote Serial,
+	ST2000 Remote, MIPS Remote): mention `host:port' syntax for TCP.
+
+	* remote.texi: new name for former gdbinv-s.texi
+
+	* gdb.texinfo: use remote.texi rather than gdbinv-s.texi
+
+Wed Jul 28 08:26:24 1993  Ian Lance Taylor  (ian@cygnus.com)
+
+	* gdbinv-s.texi: Documented timeout and retransmit-timeout
+	variables for MIPS remote debugging protocol.
+
+Mon Jul 26 13:00:09 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Negative Type Numbers): FORTRAN LOGICAL fix.
+
+Tue Jul 20 16:30:41 1993  Jim Kingdon  (kingdon@deneb.cygnus.com)
+
+	* Makefile.in (refcard.dvi): Use srcdir where necessary.
+
+Mon Jul 19 12:02:50 1993  Roland H. Pesch  (pesch@cygnus.com)
+
+	* gdb.texinfo: repair conditional bugs in text markup
+
+Fri Jul 16 18:57:50 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo, all-cfg.texi, h8-cfg.texi: introduce MOD2 switch
+	to select Modula-2 material.
+
+Thu Jul 15 13:15:01 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Cleanups regarding statics.
+
+	* gdbinv-s.texi (Bootstrapping): Document exceptionHandler.
+	(Debug Session): Mention exceptionHandler.  Add xref to Bootstrapping.
+
+Mon Jul 12 13:37:02 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: N_MAIN is sometimes used for C.
+
+Fri Jul  9 09:47:02 1993  Peter Schauer  (pes@regent.e-technik.tu-muenchen.de)
+
+	* gdbint.texinfo (Host, Target Conditionals): Remove TM_FILE_OVERRIDE.
+
+Tue Jul  6 12:41:28 1993  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo (Target Conditionals): Remove NO_TYPEDEFS,
+	removed from the code by Kingdon. 
+
+Tue Jul  6 12:24:34 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* gdb.texinfo (Break Commands): Remove stuff about flushing terminal
+	input when evaluating breakpoint conditions; the bug has been fixed.
+
+	* gdb.texinfo (Continuing and Stepping): Argument to "continue"
+	sets the ignore count to N-1, not to N.
+
+Thu Jul  1 14:57:42 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* refcard.tex (\hoffset): correct longstanding error to match
+	  intended offset; avoids cutting off edge on some printers
+
+Wed Jun 30 18:23:06 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Parameters): Say that order of stabs is significant.
+
+Fri Jun 25 21:34:52 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Common Blocks): Say what Sun FORTRAN does.
+
+Fri Jun 25 16:15:10 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* Makefile.in: (REFEDITS) new var to control whether PS or CM
+	fonts and whether US or A4 paper for GDB refcard; (refcard.dvi)
+	collect sed edits if any, apply to refcard before formatting;
+	(refcard.ps) stop implying PS fonts if PS output requested;
+	(lrefcard.ps) delete extra target for variant PS fonts
+
+	* refcard.tex: parametrize papersize dependent info, collect
+	  in easily replaced spot
+
+	* a4rc.sed: new file, edits to refcard for A4 paper
+
+Fri Jun 25 14:21:46 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Negative Type Numbers): Type -16 is 4 bytes.
+
+Wed Jun 23 15:02:50 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Negative Type Numbers): Minor character cleanups.
+
+Tue Jun 22 16:31:52 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Express disapproval of 'D' symbol descriptor
+	politely rather than rudely.
+
+Fri Jun 18 19:42:09 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Document common blocks.
+
+Fri Jun 18 12:12:57 1993  Fred Fish  (fnf@cygnus.com)
+
+	* stabs.texinfo:  Add some basic info about stabs-in-elf.
+
+Fri Jun 18 13:57:09 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Top): Minor cleanup.
+
+Mon Jun 14 16:16:51 1993  david d `zoo' zuhn  (zoo at rtl.cygnus.com)
+
+	* Makefile.in (install-info): remove parentdir support
+
+Tue Jun 15 18:11:39 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo (Copying): delete this node and references to it;
+	RMS says this manual need not carry GPL. (passim): Improvements
+	from last round at FSF, largely due to Ian Taylor review, and
+	minor formatting improvements.
+
+	* gdbinv-s.texi (passim): Improvements from last round at FSF,
+	largely due to Ian Taylor review. (Debug Session): minor edits to
+	new text.
+
+Sun Jun 13 12:52:39 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* Makefile.in (realclean): Remove info and dvi files too.
+
+Sat Jun 12 16:09:22 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* {all,h8}-config.texi: Rename to *-cfg.texi for 14 char filenames.
+	* Makefile.in: Change accordingly.  gdb-config.texi -> gdb-cfg.texi.
+	* gdb.texinfo: Change accordingly.
+
+	* stabs.texinfo: Clean up N_{L,R}BRAC.  Discuss what addresses of
+	N_{L,R}BRAC,N_SLINE are relative to.
+
+Fri Jun 11 15:15:55 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* Makefile.in (GDBvn.texi): Update atomically.
+
+Wed Jun  9 10:58:16 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* gdbinv-s.texi (Debug Session): Document exceptionHook.
+
+Tue Jun  8 13:42:04 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* gdb.texinfo (Print Settings): Move all stuff relating to symbolic
+	addresses together.  Also motivate the set print symbol-filename
+	command and suggest other solutions.
+
+Tue Jun  1 22:46:43 1993  Fred Fish  (fnf@cygnus.com)
+
+	* gdb.texinfo (set print elements):  Note that the number of
+	elements is set to unlimited by "set print elements 0".
+
+Mon May 31 08:06:55 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* stabs.texinfo (Builtin Type Descriptors): Try to clarify what
+	NF_LDOUBLE means.
+	(Stab Types): Include Solaris stab types.
+	(Procedures): Document Solaris extensions.
+
+Thu May 27 06:20:42 1993  Peter Schauer  (pes@regent.e-technik.tu-muenchen.de)
+
+	* gdb.texinfo:  Add `set print symbol-filename' doc.
+
+Wed May 26 00:26:42 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Arrays): Talk about type definition vs. type
+	information.
+
+	* stabs.texinfo (Builtin Type Descriptors): Talk about omitting
+	the trailing semicolon.
+
+Tue May 25 14:49:42 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Line Numbers, Source Files): Re-write these two nodes
+	and merge in other parts of the document addressing these subjects.
+	gdbint.texinfo (XCOFF): Remove info which is now in stabs.texinfo.
+
+	* stabs.texinfo (Subranges, Arrays): Try to explain about the semicolon
+	at the end of a range type.
+
+	* stabs.texinfo (Subranges): "A offset" and "T offset" are not
+	AIX extensions.
+
+Mon May 24 09:00:33 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Stabs Format):  Misc fixes.
+
+Sat May 22 10:40:56 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Constants):  Allow an `e' constant to be non-enum.
+	(Traditional builtin types): Document convex convention for long long.
+	(Negative builtin types): Discuss type names, and misc fixes.
+
+Fri May 21 11:20:31 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Builtin Type Descriptors): Document the floating
+	point types used with @samp{R} type descriptor.
+	(Symbol Descriptors): Describe how to handle conflict between
+	different meanings of @samp{P} symbol descriptor.
+
+Thu May 20 13:35:10 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Remove node Quick Reference and put its children
+	directly under the main menu.
+
+	* stabs.texinfo: Many more changes to bring it into line with
+	AIX documentation and reality.  I think it now has all the
+	information from the AIX documentation, except that I burned
+	out when I got to variant records (Pascal and Modula-2) and
+	all the COBOL types.  Oh well, we can add them later when we're
+	worrying more about those languages.
+
+	* stabs.texinfo (Automatic variables): Talk about what it means
+	to omit the symbol descriptor.
+
+Tue May 18 17:59:18 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo (Parameters): Add "(sometimes)" when describing
+	gcc2 behavior with promoted args.
+
+Fri May 14 21:35:29 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo: include readline appendices in info version of manual
+
+Fri May  7 11:56:18 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdbinv-s.texi (Remote Serial): describe new ^C behavior in
+	target remote.
+
+	* gdb.texinfo (Machine Code): more index entries for disassemble
+
+Fri May  7 10:12:30 1993  Fred Fish  (fnf@cygnus.com)
+
+	* Clarify the intended use of the gdb-testers and gdb-patches
+	mailing lists, and shrink gzip comment.
+
+Thu May  6 16:39:50 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo (Shell Commands): do not mention SHELL env var in
+	DOSHOST configuration of manual.
+
+	* gdb.texinfo (MIPS Stack): new node.
+
+	* all-config.texi (MIPS) new switch.
+
+	* gdbinv-s.texi (Nindy Options) Remove two instances of future
+	tense; (MIPS Remote) new node.
+
+	* gdb.texinfo (passim) rephrases to work around makeinfo @value
+	bug; (Environment) less passive, other small cleanups in text about
+	.cshrc/.bashrc; (Invoking GDB) new MIPS Remote menu entry;
+	(Remote) new MIPS Remote menu entry.
+
+Thu Apr 29 09:36:25 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* stabs.texinfo: Many changes to include information from the
+	AIX documentation.
+
+	* gdb.texinfo (Environment): Mention pitfall with .cshrc.
+
+Tue Apr 27 14:02:57 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* gdbint.texinfo (new node Debugging GDB, elsewhere):
+	Move a bunch of information from ../README.
+	(Getting Started): New node.
+
+Fri Apr 23 17:21:13 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdbinv-s.texi, gdb.texinfo: include Hitachi SH target
+
+	* gdb.texinfo: advance manual revision dates to present
+
+	* gdbinv-s.texi, gdb.texinfo, all-config.texi, h8-config.texi:
+	stop using silly Roman numerals in @set variable names
+
+Fri Apr 23 07:30:01 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* stabs.texinfo (Parameters): Keep trying to get this right.
+
+Wed Apr 21 15:18:47 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* stabs.texinfo (Parameters): More on "local parameters".
+
+Mon Apr 19 08:00:51 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* stabs.texinfo (Parameters): Re-do "local parameters" section.
+
+Sun Apr 18 09:47:45 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* stabs.texinfo (Symbol descriptors): Re-do using @table and @xref.
+	(Parameters): Rewrite.
+	(xcoff-differences, Sun-differences): Minor changes.
+
+Thu Apr 15 02:35:24 1993  John Gilmore  (gnu@cacophony.cygnus.com)
+
+	* stabs.texinfo:  Minor cleanup.
+
+Wed Apr 14 17:31:00 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* gdbint.texinfo: Minor xcoff stuff.
+
+Wed Apr  7 14:11:07 1993  Fred Fish  (fnf@cygnus.com)
+
+	* gdbint.texinfo:  Update for new config directory structure.
+	Add info about internal type data structures.
+
+Mon Apr  5 09:06:30 1993  Ian Lance Taylor  (ian@cygnus.com)
+
+	* Makefile.in (SFILES_INCLUDED): gdb-config.texi is no longer in
+	$(srcdir).
+	(gdb-config.texi): Depend on file in $(srcdir).
+
+Fri Apr  2 16:55:13 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* stabs.texinfo: Fixes about N_SO.
+
+Fri Mar 26 18:00:35 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo: include list of nonstandard init file names
+
+	* *-config.texi: new switch GENERIC for text that applies *only*
+	to (usual) multiple-target version of manual
+
+	* gdb.texinfo, gdbinv-s.texi: Update conditional markup to correct
+	h8 config
+
+	* gdb.texinfo: depend on latest fixed makeinfo, use conditionals
+	in menus (rather than conditionally selected multiple alternative
+	menus).
+
+	* Makefile.in: define and use DOC_CONFIG var to select
+	configuration for GDB user manual.
+
+	* gdb-config.texi: delete from repository, generate from Makefile.
+
+	* all-config.texi: normal `generic' configuration file, formerly
+	stored as gdb-config.texi
+
+Wed Mar 24 14:03:19 1993  david d `zoo' zuhn  (zoo at poseidon.cygnus.com)
+
+	* Makefile.in: add dvi target to build all .dvi files
+
+Tue Mar 23 16:03:24 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo, gdvinv-s.texinfo: formatting improvements.
+
+Fri Mar 19 21:46:50 1993  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Doc NO_MMALLOC and NO_MMALLOC_CHECK as
+	host conditionals.
+	* stabs.texinfo:  More array fixes inspired by Jim's.
+
+Fri Mar 19 10:23:34 1993  Jim Kingdon  (kingdon@cygnus.com)
+
+	* stabs.texinfo: Fixes re arrays and continuations.
+
+	* gdbint.texinfo: Add XCOFF node.
+
+Mon Mar  8 15:52:18 1993  John Gilmore  (gnu@cygnus.com)
+
+	* gdb.texinfo:  Add `set print max-symbolic-offset' doc.
+
+Sun Feb 21 17:09:38 1993  Per Bothner  (bothner@rtl.cygnus.com)
+
+	* stabs.texinfo:  Fix for array types to mention lower bounds.
+
+Thu Feb 18 01:19:49 1993  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Update PTRACE_ARG3_TYPE doc, pull PT_*.
+
+Wed Feb 17 08:15:24 1993  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Remove SET_STACK_LIMIT_HUGE from target defines.
+
+Thu Feb 11 10:38:40 1993  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Fix thinko (NM_FILE => NAT_FILE).  Found
+	by Michael Ben-Gershon <mybg@CS.HUJI.AC.IL>.
+
+Wed Feb 10 23:59:19 1993  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Eliminate IBM6000_HOST, document IBM6000_TARGET.
+
+Tue Feb  9 18:26:21 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo, gdbinv-s.texi: misc updates
+
+Sat Feb  6 10:25:47 1993  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Brief documentation for longjmp support,
+	from an email msg by Stu.
+
+Fri Feb  5 14:10:15 1993  John Gilmore  (gnu@cygnus.com)
+
+	* stabs.texinfo:  Fix description of floating point "range"
+	types (which really define basic types).  Reported by Jim Meehan,
+	<meehan@src.dec.com>.
+
+	* gdbint.texinfo:  Remove COFF_NO_LONG_FILE_NAMES define, now gone.
+
+Thu Feb  4 13:56:46 1993  Ian Lance Taylor  (ian@cygnus.com)
+
+	* gdbint.texinfo: Slightly expand section on supporting a new
+	object file format.
+
+Thu Feb  4 01:49:04 1993  John Gilmore  (gnu@cygnus.com)
+
+	* Makefile.in (refcard.ps, lrefcard.ps):  Remove psref.tex
+	intermediate file.
+
+Tue Feb  2 12:18:06 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo, gdbinv-s.texi: miscellaneous stylistic cleanups
+
+Mon Feb  1 15:35:47 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdbinv-s.texi: z8000 simulator target name is just "sim"
+
+	* gdbinv-s.texi:  Mention that Z8000 simulator can simulate Z8001
+	as well as Z8002.
+
+Sat Nov 28 06:51:35 1992  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Add sections on clean design and on how to send
+	in changes.
+
+Mon Nov  9 23:57:02 1992  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Add how to declare the result of make_cleanup.
+
+Mon Oct 26 11:09:47 1992  John Gilmore  (gnu@cygnus.com)
+
+	* gdb.texinfo:  Fix typo, reported by Karl Berry.
+
+Fri Oct 23 00:41:21 1992  John Gilmore  (gnu@cygnus.com)
+
+	* gdb.texinfo:  Add opcodes dir to GDB distribution description.
+
+Sat Oct 10 18:04:58 1992  david d `zoo' zuhn  (zoo at cirdan.cygnus.com)
+
+	* gdbint.texinfo: fixed a stray email address (needs @@),
+	added @table @code to node "Native Conditionals"
+
+Tue Sep 22 00:34:15 1992  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Describe coding style of GDB.
+
+Mon Sep 21 19:32:16 1992  John Gilmore  (gnu@cygnus.com)
+
+	* stabs.texinfo:  Minor wording changes.
+
+Tue Sep 15 02:57:09 1992  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Improve release doc slightly.
+
+Fri Sep 11 01:34:25 1992  John Gilmore  (gnu@sphagnum.cygnus.com)
+
+	* gdbint.texinfo:  Improve doc of GDB config macros.
+
+Wed Sep  9 16:52:06 1992  John Gilmore  (gnu@cygnus.com)
+
+	* stabs.texinfo:  Remove Bothner's changes for C++ nested types.
+	These will be reinserted when examined.
+
+Mon Aug 24 01:17:55 1992  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Make a start at documenting all the #if macros
+	in GDB.  At least list them all, and start separating them into
+	host-specific and target-specific.
+
+Tue Aug 18 15:59:13 1992  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdbinv-s.m4.in: refrain from using @cartouche for just a few
+	examples (not consistent w others).  
+	gdb.texinfo: issue disclaimer paragraph on cmdline options only
+	for generic vn of doc
+
+Tue Aug 18 14:53:27 1992  Ian Lance Taylor  (ian@cygnus.com)
+
+	* Makefile.in: always create installation directories.
+
+Tue Aug 18 14:11:50 1992  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo: in h8 config, do not describe searching commands.
+
+Mon Aug 17 18:07:59 1992  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo, none.m4, h8.m4, gdbinv-s.m4.in: improve H8/300
+	  conditionals; introduce a few generic switches that may be
+	  useful for other cross-dev or dos-hosted configs.
+
+	* gdb.texinfo: fix typo in "info reg" description
+
+Sun Aug 16 01:16:18 1992  John Gilmore  (gnu@cygnus.com)
+
+	* stabs.texinfo:  Minor updates from running TeX over it.
+	* Makefile.in (stabs.dvi, stabs.ps):  Add.
+
+Sat Aug 15 20:52:24 1992  Per Bothner  (bothner@rtl.cygnus.com)
+
+	* stabs.texinfo:  Stabs documentation, written by Julia Menapace.
+	First pass at converting it to texinfo.
+
+Sat Aug 15 03:14:59 1992  John Gilmore  (gnu@cygnus.com)
+
+	* gdb.texinfo, refcard.tex:  Document mult args on `info reg'.
+	* Makefile.in (refcard.ps, lrefcard.ps):  Add missing $(srdir).
+
+Fri Aug 14 21:08:47 1992  John Gilmore  (gnu@cygnus.com)
+
+	* gdbint.texinfo:  Add section on partial symbol tables.
+
+Sat Jun 20 16:31:10 1992  John Gilmore  (gnu at cygnus.com)
+
+	* gdb.texinfo:  document `set remotedebug' and `set
+	rstack_high_address'.
+
+Thu May 14 17:09:48 1992  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo: slight expansion of new text on reading info files
+	* gdbinv-s.m4.in: correct and expand info on cross-debugging
+	H8/300 from DOS.
+
+Tue May 12 12:22:47 1992  John Gilmore  (gnu at cygnus.com)
+
+	* gdb.texinfo:  `info user' => `show user'.  Noticed by David Taylor.
+
+Mon May 11 19:06:27 1992  John Gilmore  (gnu at cygnus.com)
+
+	* gdb.texinfo:  Say how to read the `info' files.
+
+Tue May  5 12:11:38 1992  K. Richard Pixley  (rich@cygnus.com)
+
+	* Makefile.in: gm4 -> m4.
+
+Fri Apr 10 17:50:43 1992  John Gilmore  (gnu at rtl.cygnus.com)
+
+	* gdb.texinfo:  Update for GDB-4.5.  Move `Formatting
+	Documentation' ahead of `Installing GDB' to match README.
+	Update shared library doc, -readnow and -mapped, and directory
+	structure (add glob and mmalloc).  Update configure doc.	
+
+Tue Mar 24 23:28:38 1992  K. Richard Pixley  (rich@cygnus.com)
+
+	* Makefile.in: remove $(srcdir) from gdb.info rule.
+
+Sat Mar  7 18:44:50 1992  K. Richard Pixley  (rich@rtl.cygnus.com)
+
+	* Makefile.in: commented out gdb-all.texinfo rule.  This is
+	  temporary.
+
+Wed Feb 26 18:04:40 1992  K. Richard Pixley  (rich@cygnus.com)
+
+	* Makefile.in, configure.in: removed traces of namesubdir,
+	  -subdirs, $(subdir), $(unsubdir), some rcs triggers.  Forced
+	  copyrights to '92, changed some from Cygnus to FSF.
+
+Fri Dec 13 09:47:31 1991  John Gilmore  (gnu at cygnus.com)
+
+	* gdb.texinfo:  Improve how we ask for bug reports.
+
+Tue Dec 10 04:07:21 1991  K. Richard Pixley  (rich at rtl.cygnus.com)
+
+	* Makefile.in: infodir belongs in datadir.
+
+Fri Dec  6 23:57:34 1991  K. Richard Pixley  (rich at rtl.cygnus.com)
+
+	* Makefile.in: remove spaces following hyphens, bsd make can't
+	  cope.  install using INSTALL_DATA.  added clean-info.  added
+	  standards.text support. 
+
+Thu Dec  5 22:46:12 1991  K. Richard Pixley  (rich at rtl.cygnus.com)
+
+	* Makefile.in: idestdir and ddestdir go away.  Added copyrights
+	  and shift gpl to v2.  Added ChangeLog if it didn't exist. docdir
+	  and mandir now keyed off datadir by default.
+
+
+Local Variables:
+mode: indented-text
+left-margin: 8
+fill-column: 74
+version-control: never
+End:
diff --git a/gdb/doc/HPPA-cfg.texi b/gdb/doc/HPPA-cfg.texi
new file mode 100644
index 0000000000..88a138cab8
--- /dev/null
+++ b/gdb/doc/HPPA-cfg.texi
@@ -0,0 +1,114 @@
+@c GDB MANUAL configuration file.  
+@c Copyright (c) 1993 Free Software Foundation, Inc.
+@c
+@c NOTE: While the GDB manual is configurable (by changing these
+@c switches), its configuration is ***NOT*** automatically tied in to
+@c source configuration---because the authors expect that, save in
+@c unusual cases, the most inclusive form of the manual is appropriate
+@c no matter how the program itself is configured.
+@c
+@c The only automatically-varying variable is the GDB version number,
+@c which the Makefile rewrites based on the VERSION variable from
+@c `../Makefile.in'.  
+@c 
+@c GDB version number is recorded in the variable GDBVN
+@include GDBvn.texi
+@c
+@c ----------------------------------------------------------------------
+@c PLATFORM FLAGS:
+@clear GENERIC
+@c
+@c HP PA-RISC target:
+@set HPPA
+@c
+@c Hitachi H8/300 target:
+@clear H8
+@c Hitachi H8/300 target ONLY:
+@clear H8EXCLUSIVE
+@c
+@c remote MIPS target:
+@clear MIPS
+@c
+@c SPARC target:
+@clear SPARC
+@c
+@c AMD 29000 target:
+@clear AMD29K
+@c
+@c Intel 960 target:
+@clear I960
+@c
+@c Tandem ST2000 (phone switch) target:
+@clear ST2000
+@c
+@c Zilog 8000 target:
+@clear Z8K
+@c
+@c Wind River Systems VxWorks environment:
+@clear VXWORKS
+@c
+@c ----------------------------------------------------------------------
+@c DOC FEATURE FLAGS:
+@c 
+@c Bare-board target?
+@clear BARETARGET
+@c
+@c Restrict languages discussed to C?
+@c This is backward.  As time permits, change this to language-specific
+@c switches for what to include.
+@clear CONLY
+@c Discuss Fortran?
+@clear FORTRAN
+@c
+@c Discuss Modula 2?
+@clear MOD2
+@c
+@c Specifically for host machine running DOS?
+@clear DOSHOST
+@c
+@c Talk about CPU simulator targets?
+@clear SIMS
+@c
+@c Remote serial line settings of interest?
+@set SERIAL
+@c
+@c Discuss features requiring Posix or similar OS environment?
+@set POSIX
+@c
+@c Discuss remote serial debugging stub?
+@clear REMOTESTUB
+@c
+@c Discuss gdbserver?
+@set GDBSERVER
+@c
+@c Discuss gdbserve.nlm?
+@set GDBSERVE
+@c
+@c Refrain from discussing how to configure sw and format doc?
+@clear PRECONFIGURED
+@c
+@c Refrain from referring to unfree publications?
+@set FSFDOC
+@c
+@c ----------------------------------------------------------------------
+@c STRINGS:
+@c
+@c Name of GDB program.  Used also for (gdb) prompt string.
+@set GDBP gdb
+@c 
+@c Name of GDB product.  Used in running text.
+@set GDBN GDB
+@c
+@c Name of target.
+@set TARGET HP 9000 Systems
+@c 
+@c Name of host.  Should not be used in generic configs, but generic
+@c value may catch some flubs.
+@set HOST machine specific
+@c
+@c Name of GCC product
+@set NGCC GCC
+@c 
+@c Name of GCC program
+@set GCC gcc
+
diff --git a/gdb/doc/LRS b/gdb/doc/LRS
new file mode 100644
index 0000000000..7e25d432a3
--- /dev/null
+++ b/gdb/doc/LRS
@@ -0,0 +1,197 @@
+What's LRS?
+===========
+
+LRS, or Live Range Splitting is an optimization technique which allows
+a user variable to reside in different locations during different parts
+of a function.
+
+For example, a variable might reside in the stack for part of a function
+and in a register during a loop and in a different register during
+another loop.
+
+Clearly, if a variable may reside in different locations, then the
+compiler must describe to the debugger where the variable resides for
+any given part of the function.
+
+This document describes the debug format for encoding these extensions
+in stabs.
+
+Since these extensions are gcc specific, these additional symbols and
+stabs can be disabled by the gcc command option -gstabs.
+
+
+GNU extensions for LRS under stabs:
+===================================
+
+
+range symbols:
+-------------
+
+    A range symbol will be used to mark the beginning or end of a
+    live range (the range which describes where a symbol is active,
+    or live).  These symbols will later be referenced in the stabs for
+    debug purposes.  For simplicity, we'll use the terms "range_start"
+    and "range_end" to identify the range symbols which mark the beginning
+    and end of a live range respectively.
+
+    Any text symbol which would normally appear in the symbol table
+    (eg. a function name) can be used as range symbol.  If an address
+    is needed to delimit a live range and does not match any of the
+    values of symbols which would normally appear in the symbol table,
+    a new symbol will be added to the table whose value is that address.
+
+    The three new symbol types described below have been added for this 
+    purpose.
+
+    For efficiency, the compiler should use existing symbols as range
+    symbols whenever possible; this reduces the number of additional
+    symbols which need to be added to the symbol table.
+
+    
+New debug symbol type for defining ranges:
+------------------------------------------
+
+    range_off - contains PC function offset for start/end of a live range.
+		Its location is relative to the function start and therefore 
+		eliminates the need for additional relocation.
+
+    This symbol has a values in the text section, and does not have a name.
+
+	    NOTE: the following may not be needed but are included here just 
+		in case.
+	    range - contains PC value of beginning or end of a live range
+		(relocs required).
+
+	    NOTE: the following will be required if we desire LRS debugging
+		to work with old style a.out stabs.
+	    range_abs - contains absolute PC value of start/end of a live 
+		range.  The range_abs debug symbol is provided for 
+		completeness, in case there is a need to describe addresses 
+		in ROM, etc.
+
+
+Live range:
+-----------
+
+    The compiler and debugger view a variable with multiple homes as
+    a primary symbol and aliases for that symbol.  The primary symbol
+    describes the default home of the variable while aliases describe
+    alternate homes for the variable.
+
+    A live range defines the interval of instructions beginning with
+    range_start and ending at range_end-1, and is used to specify a
+    range of instructions where an alias is active or "live".  So,
+    the actual end of the range will be one less than the value of the
+    range_end symbol.
+
+    Ranges do not have to be nested. Eg. Two ranges may intersect while 
+        each range contains subranges which are not in the other range.
+
+    There does not have to be a 1-1 mapping from range_start to
+        range_end symbols.  Eg. Two range_starts can share the same 
+        range_end, while one symbol's range_start can be another symbol's
+        range_end.
+
+    When a variable's storage class changes (eg. from stack to register,
+	or from one register to another), a new symbol entry will be
+	added to the symbol table with stabs describing the new type,
+	and appropriate live ranges refering to the variable's initial
+	symbol index.
+
+    For variables which are defined in the source but optimized away,
+        a symbol should be emitted with the live range l(0,0).
+
+    Live ranges for aliases of a particular variable should always
+	be disjoint.  Overlapping ranges for aliases of the same variable
+	will be treated as an error by the debugger, and the overlapping
+	range will be ignored.
+
+    If no live range information is given, the live range will be assumed to 
+	span the symbol's entire lexical scope.
+
+
+New stabs string identifiers:
+-----------------------------
+
+  "id" in "#id" in the following section refers to a numeric value.
+
+  New stab syntax for live range:  l(<ref_from>,<ref_to>) 
+
+    <ref_from> - "#id" where #id identifies the text symbol (range symbol) to
+		use as the start of live range (range_start).  The value for 
+		the referenced text symbol is the starting address of the 
+		live range.
+
+    <ref_to> - "#id" where #id identifies the text symbol (range symbol) to
+		use as the end of live range (range_end).  The value for 
+		the referenced text symbol is ONE BYTE PAST the ending 
+		address of the live range.
+
+
+  New stab syntax for identifying symbols.
+
+    <def> - "#id="
+
+	    Uses:
+	      <def><name>:<typedef1>...
+		  When used in front of a symbol name, "#id=" defines a
+		  unique reference number for this symbol.  The reference
+		  number can be used later when defining aliases for this
+		  symbol.
+	      <def>
+		  When used as the entire stab string, "#id=" identifies this 
+		  nameless symbol as being the symbol for which "#id" refers to.
+
+
+    <ref> - "#id" where "#id" refers to the symbol for which the string 
+		"#id=" identifies.
+	    Uses:
+	      <ref>:<typedef2>;<liverange>;<liverange>...
+		  Defines an alias for the symbol identified by the reference
+		  number ID.
+	      l(<ref1>,<ref2>)
+		  When used within a live range, "#id" refers to the text 
+		  symbol identified by "#id=" to use as the range symbol.
+
+    <liverange> - "l(<ref_from>,<ref_to>)" - specifies a live range for a 
+		symbol.  Multiple "l" specifiers can be combined to represent 
+		mutiple live ranges, separated by semicolons.
+
+
+
+
+Example:
+========
+
+Consider a program of the form:
+
+    void foo(){
+      int a = ...;
+      ...
+      while (b--)
+       c += a;
+      ..
+      d = a;
+      ..
+    }
+
+Assume that "a" lives in the stack at offset -8, except for inside the
+loop where "a" resides in register "r5".
+
+The way to describe this is to create a stab for the variable "a" which
+describes "a" as living in the stack and an alias for the variable "a"
+which describes it as living in register "r5" in the loop.
+
+Let's assume that "#1" and "#2" are symbols which bound the area where
+"a" lives in a register.
+
+The stabs to describe "a" and its alias would look like this:
+
+        .stabs "#3=a:1",128,0,8,-8
+        .stabs "#3:r1;l(#1,#2)",64,0,0,5
+
+
+This design implies that the debugger will keep a chain of aliases for
+any given variable with aliases and that chain will be searched first
+to find out if an alias is active.  If no alias is active, then the
+debugger will assume that the main variable is active.
diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
new file mode 100644
index 0000000000..4bcd62ec16
--- /dev/null
+++ b/gdb/doc/Makefile.in
@@ -0,0 +1,340 @@
+##Copyright (C) 1991, 1992, 1999 Free Software Foundation, Inc.
+
+# Makefile for GDB documentation.
+# This file is part of GDB.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+srcdir = @srcdir@
+VPATH = @srcdir@
+
+prefix = @prefix@
+
+infodir = @infodir@
+
+SHELL = @SHELL@
+
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_DATA = @INSTALL_DATA@
+
+# main GDB source directory
+gdbdir = $(srcdir)/..
+
+# where to find texinfo; GDB dist should include a recent one
+TEXIDIR=${gdbdir}/../texinfo
+
+# where to find makeinfo, preferably one designed for texinfo-2
+MAKEINFO=makeinfo
+
+# where to find texi2roff, ditto
+TEXI2ROFF=texi2roff
+
+# Where is the source dir for the READLINE library doc?  
+# Traditionally readline is in .. or .
+READLINE_DIR = ${gdbdir}/../readline/doc
+
+SET_TEXINPUTS = TEXINPUTS=${TEXIDIR}:.:$(srcdir):$(READLINE_DIR):$$TEXINPUTS
+
+# There may be alternate predefined collections of switches to configure
+# the GDB manual.  Normally this is not done in synch with the software
+# config system, since this choice tends to be independent; most people
+# want a doc config of `all' for a generic manual, regardless of sw config.
+DOC_CONFIG = all
+
+# This list of sed edits will edit the GDB reference card
+# for what fonts and what papersize to use.
+# By default (NO edits applied), the refcard uses:
+#    - Computer Modern (CM) fonts
+#    - US letter paper (8.5x11in)
+# List some of the following files for alternative fonts and paper:
+#  a4rc.sed     use A4 paper (297 x 210 mm)
+#  psrc.sed     use PostScript fonts (Karl Berry short TeX names)
+# lpsrc.sed     use PostScript fonts (full PostScript names in TeX)
+# e.g. for A4, Postscript:  REFEDITS = a4rc.sed psrc.sed
+#      for A4, CM fonts:    REFEDITS = a4rc.sed
+#      for US, PS fonts:    REFEDITS = psrc.sed
+#      for default:
+REFEDITS =
+
+# Don Knuth's TeX formatter
+TEX = tex
+
+# auxiliary program for sorting Texinfo indices
+TEXINDEX = texindex
+
+# Program to generate Postscript files from DVI files.
+DVIPS = dvips
+
+# Main GDB manual's source files
+SFILES_INCLUDED = gdb-cfg.texi $(srcdir)/remote.texi
+
+SFILES_LOCAL = $(srcdir)/gdb.texinfo GDBvn.texi $(SFILES_INCLUDED)
+
+SFILES_DOC = $(SFILES_LOCAL) \
+                $(READLINE_DIR)/rluser.texinfo $(READLINE_DIR)/inc-hist.texi
+
+#### Host, target, and site specific Makefile fragments come in here.
+###
+
+all install:
+
+info: gdb.info gdbint.info stabs.info
+dvi: gdb.dvi gdbint.dvi stabs.dvi refcard.dvi
+ps: gdb.ps gdbint.ps stabs.ps refcard.ps
+all-doc: info dvi ps
+
+install-info: info
+	for i in *.info* ; do \
+		$(INSTALL_DATA) $$i $(infodir)/$$i ; \
+	done
+
+STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi
+
+# Copy the object files from a particular stage into a subdirectory.
+stage1: force
+	-mkdir stage1
+	-mv $(STAGESTUFF) stage1
+
+stage2: force
+	-mkdir stage2
+	-mv $(STAGESTUFF) stage2
+
+stage3: force
+	-mkdir stage3
+	-mv $(STAGESTUFF) stage3
+
+against=stage2
+
+comparison: force
+	for i in $(STAGESTUFF) ; do cmp $$i $(against)/$$i ; done
+
+de-stage1: force
+	-(cd stage1 ; mv -f * ..)
+	-rmdir stage1
+
+de-stage2: force
+	-(cd stage2 ; mv -f * ..)
+	-rmdir stage2
+
+de-stage3: force
+	-(cd stage3 ; mv -f * ..)
+	-rmdir stage3
+
+# The "least clean" level of cleaning.  Get rid of files which are
+# automatically generated files that are just intermediate files,
+# 
+mostlyclean:
+	rm -f gdb.mm gdb.ms gdb.me links2roff
+	rm -f *.aux *.cp* *.fn* *.ky* *.log *.pg* *.toc *.tp* *.vr*
+	rm -f sedref.dvi sedref.tex tmp.sed
+
+clean: mostlyclean
+	rm -f rluser.texinfo inc-hist.texi gdb-cfg.texi
+
+distclean: clean
+	rm -f Makefile config.status
+
+# GDBvn.texi, the dvi files, the info files, and the postscript files, 
+# are all part of the distribution, so it should not be removed by
+# "clean" or "distclean".  Use maintainer-clean to remove them.
+
+maintainer-clean realclean: distclean
+	rm -f GDBvn.texi *.info* *.dvi *.ps
+
+# GDB QUICK REFERENCE (dvi output)
+refcard.dvi : refcard.tex $(REFEDITS)
+	if [ -z "$(REFEDITS)" ]; then \
+		cp $(srcdir)/refcard.tex sedref.tex ; \
+	else \
+		echo > tmp.sed ; \
+		for f in "$(REFEDITS)" ; do \
+			cat $(srcdir)/$$f >>tmp.sed ; done ; \
+		sed -f tmp.sed $(srcdir)/refcard.tex >sedref.tex ; \
+	fi
+	$(SET_TEXINPUTS) $(TEX) sedref.tex
+	mv sedref.dvi refcard.dvi
+	rm -f sedref.log sedref.tex tmp.sed
+
+refcard.ps : refcard.dvi
+	$(DVIPS) -t landscape -o $@ $?
+
+# File to record current GDB version number (copied from main dir Makefile.in)
+GDBvn.texi : ${gdbdir}/Makefile.in
+	echo "@set GDBVN `sed <$(srcdir)/../Makefile.in -n 's/^VERSION *= *//p'`" > ./GDBvn.new
+	mv GDBvn.new GDBvn.texi
+
+# Updated atomically
+.PRECIOUS: GDBvn.texi
+
+# Choose configuration for GDB manual (normally `all'; normally not tied into
+# `configure' script because most users prefer generic version of manual,
+# not one for their binary config---which may not be specifically
+# defined anyways).
+gdb-cfg.texi: ${srcdir}/${DOC_CONFIG}-cfg.texi
+	ln -s ${srcdir}/${DOC_CONFIG}-cfg.texi gdb-cfg.texi || \
+	ln ${srcdir}/${DOC_CONFIG}-cfg.texi gdb-cfg.texi || \
+	cp ${srcdir}/${DOC_CONFIG}-cfg.texi gdb-cfg.texi
+
+# GDB MANUAL: texinfo source, using @set/@clear/@value/@ifset/@ifclear
+# If your texinfo or makeinfo don't support these, get a new texinfo release
+#
+# The nonsense with GDBvn.texi gets this to run with both Sun and GNU make.
+#   Note that we can *generate* GDBvn.texi, but since we distribute one in the
+#   source directory for the benefit of people who *don't* use this makefile,
+#   VPATH will often tell make not to bother building it, because the one
+#   in the srcdir is up to date.  (if not, then make should build one here).
+
+# GDB MANUAL: TeX dvi file
+gdb.dvi: ${SFILES_DOC}
+	if [ ! -f ./GDBvn.texi ]; then \
+		ln -s $(srcdir)/GDBvn.texi . || \
+		ln $(srcdir)/GDBvn.texi . || \
+		cp $(srcdir)/GDBvn.texi . ; else true; fi
+	$(SET_TEXINPUTS) $(TEX) gdb.texinfo
+	$(SET_TEXINPUTS) $(TEX) gdb.texinfo
+	$(TEXINDEX) gdb.??
+	$(SET_TEXINPUTS) $(TEX) gdb.texinfo
+	rm -f gdb.aux gdb.cp* gdb.fn* gdb.ky* gdb.log gdb.pg* gdb.toc \
+		gdb.tp* gdb.vr*
+
+gdb.ps: gdb.dvi
+	$(DVIPS) -o $@ $?
+
+# GDB MANUAL: info file
+# We're using texinfo2, and older makeinfo's may not be able to
+# cope with all the markup.  
+gdb.info: ${SFILES_DOC}
+	$(MAKEINFO) -I ${READLINE_DIR} -I $(srcdir) -o ./gdb.info gdb.texinfo
+
+# GDB MANUAL: roff translations
+# Try to use a recent texi2roff.  v2 was put on prep in jan91.
+# If you want an index, see texi2roff doc for postprocessing 
+# and add -i to texi2roff invocations below.
+# Workarounds for texi2roff-2 (probably fixed in later texi2roff's, delete
+#    corresponding -e lines when later texi2roff's are current)
+# + @ifinfo's deleted explicitly due to texi2roff-2 bug w nested constructs.
+# + @c's deleted explicitly because texi2roff sees texinfo commands in them
+# + @   (that's at-BLANK) not recognized by texi2roff, turned into blank
+# + @alphaenumerate is ridiculously new, turned into @enumerate
+
+# texi2roff doesn't have a notion of include dirs, so we have to fake 
+# it out for gdb manual's include files---but only if not configured
+# in main sourcedir.
+links2roff: $(SFILES_INCLUDED)
+	if [ ! -f gdb.texinfo ]; then \
+		ln -s $(SFILES_INCLUDED) . || \
+		ln $(SFILES_INCLUDED)    . || \
+		cp $(SFILES_INCLUDED)    . ; \
+	fi
+	touch links2roff
+
+#  "Readline" appendices.  Get them also due to lack of includes, 
+# regardless of whether or not configuring in main sourcedir.
+# @ftable removed due to bug in texi2roff-2; if your texi2roff
+# is newer, try just ln or cp
+rluser.texinfo: ${READLINE_DIR}/rluser.texinfo
+		sed -e 's/^@ftable/@table/g' \
+		-e 's/^@end ftable/@end table/g' \
+		${READLINE_DIR}/rluser.texinfo > ./rluser.texinfo
+
+inc-hist.texi: ${READLINE_DIR}/inc-hist.texi
+	ln -s ${READLINE_DIR}/inc-hist.texi . || \
+	ln ${READLINE_DIR}/inc-hist.texi . || \
+	cp ${READLINE_DIR}/inc-hist.texi .
+
+# gdb manual suitable for [gtn]roff -me
+gdb.me: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texi
+	sed -e '/\\input texinfo/d' \
+		-e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \
+		-e '/^@ifinfo/,/^@end ifinfo/d' \
+		-e '/^@c /d' \
+		-e 's/{.*,,/{/' \
+		-e 's/@ / /g' \
+		-e 's/^@alphaenumerate/@enumerate/g' \
+		-e 's/^@end alphaenumerate/@end enumerate/g' \
+		$(srcdir)/gdb.texinfo | \
+	$(TEXI2ROFF) -me | \
+	sed -e 's/---/\\(em/g' \
+	>gdb.me 
+
+# gdb manual suitable for [gtn]roff -ms
+gdb.ms: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texi
+	sed -e '/\\input texinfo/d' \
+		-e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \
+		-e '/^@ifinfo/,/^@end ifinfo/d' \
+		-e '/^@c /d' \
+		-e 's/{.*,,/{/' \
+		-e 's/@ / /g' \
+		-e 's/^@alphaenumerate/@enumerate/g' \
+		-e 's/^@end alphaenumerate/@end enumerate/g' \
+		$(srcdir)/gdb.texinfo | \
+	$(TEXI2ROFF) -ms | \
+	sed -e 's/---/\\(em/g' \
+	>gdb.ms 
+
+# gdb manual suitable for [tn]roff -mm
+# '@noindent's removed due to texi2roff-2 mm bug; if yours is newer, 
+#   try leaving them in
+gdb.mm: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texi
+	sed -e '/\\input texinfo/d' \
+		-e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \
+		-e '/^@ifinfo/,/^@end ifinfo/d' \
+		-e '/^@c /d' \
+		-e 's/{.*,,/{/' \
+		-e '/@noindent/d' \
+		-e 's/@ / /g' \
+		-e 's/^@alphaenumerate/@enumerate/g' \
+		-e 's/^@end alphaenumerate/@end enumerate/g' \
+		$(srcdir)/gdb.texinfo | \
+	$(TEXI2ROFF) -mm | \
+	sed -e 's/---/\\(em/g' \
+	>gdb.mm 
+
+
+# GDB INTERNALS MANUAL: TeX dvi file
+gdbint.dvi : gdbint.texinfo
+	$(SET_TEXINPUTS) $(TEX) gdbint.texinfo
+	$(TEXINDEX) gdbint.??
+	$(SET_TEXINPUTS) $(TEX) gdbint.texinfo
+	rm -f gdbint.aux gdbint.cp* gdbint.fn* gdbint.ky* \
+		gdbint.log gdbint.pg* gdbint.toc gdbint.tp* gdbint.vr*
+
+gdbint.ps : gdbint.dvi
+	$(DVIPS) -o $@ $?
+
+# GDB INTERNALS MANUAL: info file
+
+gdbint.info: gdbint.texinfo
+	$(MAKEINFO) -o gdbint.info $(srcdir)/gdbint.texinfo
+
+stabs.info: stabs.texinfo
+	$(MAKEINFO) -o stabs.info $(srcdir)/stabs.texinfo
+
+# STABS DOCUMENTATION: TeX dvi file
+stabs.dvi : stabs.texinfo
+	$(SET_TEXINPUTS) $(TEX) stabs.texinfo
+	$(TEXINDEX) stabs.??
+	$(SET_TEXINPUTS) $(TEX) stabs.texinfo
+	rm -f stabs.aux stabs.cp* stabs.fn* stabs.ky* \
+		stabs.log stabs.pg* stabs.toc stabs.tp* stabs.vr*
+
+stabs.ps: stabs.dvi
+	$(DVIPS) -o $@ $?
+
+force:
+
+Makefile: Makefile.in $(host_makefile_frag) $(target_makefile_frag) config.status
+	$(SHELL) ./config.status
diff --git a/gdb/doc/a4rc.sed b/gdb/doc/a4rc.sed
new file mode 100644
index 0000000000..22922904ef
--- /dev/null
+++ b/gdb/doc/a4rc.sed
@@ -0,0 +1,11 @@
+/--- Papersize params:/,/--- end papersize params/c\
+%------- Papersize params:\
+%%  A4 paper (297x210mm)\
+%%\
+\\totalwidth=297mm   % total width of paper\
+\\totalheight=210mm  % total height of paper\
+\\hmargin=5mm        % horizontal margin width\
+\\vmargin=10mm       % vertical margin width\
+\\secskip=.6pc       % space between refcard secs\
+\\lskip=1pt          % extra skip between \\sec entries\
+%------- end papersize params
diff --git a/gdb/doc/agentexpr.texi b/gdb/doc/agentexpr.texi
new file mode 100644
index 0000000000..4b790f56af
--- /dev/null
+++ b/gdb/doc/agentexpr.texi
@@ -0,0 +1,839 @@
+\input texinfo
+@c %**start of header
+@setfilename agentexpr.info
+@settitle GDB Agent Expressions
+@setchapternewpage off
+@c %**end of header
+
+Revision: $Id$
+
+@node The GDB Agent Expression Mechanism
+@chapter The GDB Agent Expression Mechanism
+
+In some applications, it is not feasable for the debugger to interrupt
+the program's execution long enough for the developer to learn anything
+helpful about its behavior.  If the program's correctness depends on its
+real-time behavior, delays introduced by a debugger might cause the
+program to fail, even when the code itself is correct.  It is useful to
+be able to observe the program's behavior without interrupting it.
+
+Using GDB's @code{trace} and @code{collect} commands, the user can
+specify locations in the program, and arbitrary expressions to evaluate
+when those locations are reached.  Later, using the @code{tfind}
+command, she can examine the values those expressions had when the
+program hit the trace points.  The expressions may also denote objects
+in memory --- structures or arrays, for example --- whose values GDB
+should record; while visiting a particular tracepoint, the user may
+inspect those objects as if they were in memory at that moment.
+However, because GDB records these values without interacting with the
+user, it can do so quickly and unobtrusively, hopefully not disturbing
+the program's behavior.
+
+When GDB is debugging a remote target, the GDB @dfn{agent} code running
+on the target computes the values of the expressions itself.  To avoid
+having a full symbolic expression evaluator on the agent, GDB translates
+expressions in the source language into a simpler bytecode language, and
+then sends the bytecode to the agent; the agent then executes the
+bytecode, and records the values for GDB to retrieve later.
+
+The bytecode language is simple; there are forty-odd opcodes, the bulk
+of which are the usual vocabulary of C operands (addition, subtraction,
+shifts, and so on) and various sizes of literals and memory reference
+operations.  The bytecode interpreter operates strictly on machine-level
+values --- various sizes of integers and floating point numbers --- and
+requires no information about types or symbols; thus, the interpreter's
+internal data structures are simple, and each bytecode requires only a
+few native machine instructions to implement it.  The interpreter is
+small, and strict limits on the memory and time required to evaluate an
+expression are easy to determine, making it suitable for use by the
+debugging agent in real-time applications.
+
+@menu
+* General Bytecode Design::     Overview of the interpreter.
+* Bytecode Descriptions::       What each one does.
+* Using Agent Expressions::     How agent expressions fit into the big picture.
+* Varying Target Capabilities:: How to discover what the target can do.
+* Tracing on Symmetrix::        Special info for implementation on EMC's
+                                boxes.
+* Rationale::                   Why we did it this way.
+@end menu
+
+
+@c @node Rationale
+@c @section Rationale
+
+
+@node General Bytecode Design
+@section General Bytecode Design
+
+The agent represents bytecode expressions as an array of bytes.  Each
+instruction is one byte long (thus the term @dfn{bytecode}).  Some
+instructions are followed by operand bytes; for example, the @code{goto}
+instruction is followed by a destination for the jump.
+
+The bytecode interpreter is a stack-based machine; most instructions pop
+their operands off the stack, perform some operation, and push the
+result back on the stack for the next instruction to consume.  Each
+element of the stack may contain either a integer or a floating point
+value; these values are as many bits wide as the largest integer that
+can be directly manipulated in the source language.  Stack elements
+carry no record of their type; bytecode could push a value as an
+integer, then pop it as a floating point value.  However, GDB will not
+generate code which does this.  In C, one might define the type of a
+stack element as follows:
+@example
+union agent_val @{
+  LONGEST l;
+  DOUBLEST d;
+@};
+@end example
+@noindent
+where @code{LONGEST} and @code{DOUBLEST} are @code{typedef} names for
+the largest integer and floating point types on the machine.
+
+By the time the bytecode interpreter reaches the end of the expression,
+the value of the expression should be the only value left on the stack.
+For tracing applications, @code{trace} bytecodes in the expression will
+have recorded the necessary data, and the value on the stack may be
+discarded.  For other applications, like conditional breakpoints, the
+value may be useful.
+
+Separate from the stack, the interpreter has two registers:
+@table @code
+@item pc
+The address of the next bytecode to execute.
+
+@item start
+The address of the start of the bytecode expression, necessary for
+interpreting the @code{goto} and @code{if_goto} instructions.
+
+@end table
+@noindent
+Neither of these registers is directly visible to the bytecode language
+itself, but they are useful for defining the meanings of the bytecode
+operations.
+
+There are no instructions to perform side effects on the running
+program, or call the program's functions; we assume that these
+expressions are only used for unobtrusive debugging, not for patching
+the running code.  
+
+Most bytecode instructions do not distinguish between the various sizes
+of values, and operate on full-width values; the upper bits of the
+values are simply ignored, since they do not usually make a difference
+to the value computed.  The exceptions to this rule are:
+@table @asis
+
+@item memory reference instructions (@code{ref}@var{n})
+There are distinct instructions to fetch different word sizes from
+memory.  Once on the stack, however, the values are treated as full-size
+integers.  They may need to be sign-extended; the @code{ext} instruction
+exists for this purpose.
+
+@item the sign-extension instruction (@code{ext} @var{n})
+These clearly need to know which portion of their operand is to be
+extended to occupy the full length of the word.
+
+@end table
+
+If the interpreter is unable to evaluate an expression completely for
+some reason (a memory location is inaccessible, or a divisor is zero,
+for example), we say that interpretation ``terminates with an error''.
+This means that the problem is reported back to the interpreter's caller
+in some helpful way.  In general, code using agent expressions should
+assume that they may attempt to divide by zero, fetch arbitrary memory
+locations, and misbehave in other ways.
+
+Even complicated C expressions compile to a few bytecode instructions;
+for example, the expression @code{x + y * z} would typically produce
+code like the following, assuming that @code{x} and @code{y} live in
+registers, and @code{z} is a global variable holding a 32-bit
+@code{int}:
+@example
+reg 1
+reg 2
+const32 @i{address of z}
+ref32
+ext 32
+mul
+add
+end
+@end example
+
+In detail, these mean:
+@table @code
+
+@item reg 1
+Push the value of register 1 (presumably holding @code{x}) onto the
+stack.
+
+@item reg 2
+Push the value of register 2 (holding @code{y}).
+
+@item const32 @i{address of z}
+Push the address of @code{z} onto the stack.
+
+@item ref32
+Fetch a 32-bit word from the address at the top of the stack; replace
+the address on the stack with the value.  Thus, we replace the address
+of @code{z} with @code{z}'s value.
+
+@item ext 32
+Sign-extend the value on the top of the stack from 32 bits to full
+length.  This is necessary because @code{z} is a signed integer.
+
+@item mul
+Pop the top two numbers on the stack, multiply them, and push their
+product.  Now the top of the stack contains the value of the expression
+@code{y * z}.
+
+@item add
+Pop the top two numbers, add them, and push the sum.  Now the top of the
+stack contains the value of @code{x + y * z}.
+
+@item end
+Stop executing; the value left on the stack top is the value to be
+recorded.
+
+@end table
+
+
+@node Bytecode Descriptions
+@section Bytecode Descriptions
+
+Each bytecode description has the following form:
+
+@table @asis
+
+@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b}
+
+Pop the top two stack items, @var{a} and @var{b}, as integers; push
+their sum, as an integer.
+
+@end table
+
+In this example, @code{add} is the name of the bytecode, and
+@code{(0x02)} is the one-byte value used to encode the bytecode, in
+hexidecimal.  The phrase ``@var{a} @var{b} @result{} @var{a+b}'' shows
+the stack before and after the bytecode executes.  Beforehand, the stack
+must contain at least two values, @var{a} and @var{b}; since the top of
+the stack is to the right, @var{b} is on the top of the stack, and
+@var{a} is underneath it.  After execution, the bytecode will have
+popped @var{a} and @var{b} from the stack, and replaced them with a
+single value, @var{a+b}.  There may be other values on the stack below
+those shown, but the bytecode affects only those shown.
+
+Here is another example:
+
+@table @asis
+
+@item @code{const8} (0x22) @var{n}: @result{} @var{n}
+Push the 8-bit integer constant @var{n} on the stack, without sign
+extension.
+
+@end table
+
+In this example, the bytecode @code{const8} takes an operand @var{n}
+directly from the bytecode stream; the operand follows the @code{const8}
+bytecode itself.  We write any such operands immediately after the name
+of the bytecode, before the colon, and describe the exact encoding of
+the operand in the bytecode stream in the body of the bytecode
+description.
+
+For the @code{const8} bytecode, there are no stack items given before
+the @result{}; this simply means that the bytecode consumes no values
+from the stack.  If a bytecode consumes no values, or produces no
+values, the list on either side of the @result{} may be empty.
+
+If a value is written as @var{a}, @var{b}, or @var{n}, then the bytecode
+treats it as an integer.  If a value is written is @var{addr}, then the
+bytecode treats it as an address.
+
+We do not fully describe the floating point operations here; although
+this design can be extended in a clean way to handle floating point
+values, they are not of immediate interest to the customer, so we avoid
+describing them, to save time.
+
+
+@table @asis
+
+@item @code{float} (0x01): @result{}
+
+Prefix for floating-point bytecodes.  Not implemented yet.
+
+@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b}
+Pop two integers from the stack, and push their sum, as an integer.
+
+@item @code{sub} (0x03): @var{a} @var{b} @result{} @var{a-b}
+Pop two integers from the stack, subtract the top value from the
+next-to-top value, and push the difference.
+
+@item @code{mul} (0x04): @var{a} @var{b} @result{} @var{a*b}
+Pop two integers from the stack, multiply them, and push the product on
+the stack.  Note that, when one multiplies two @var{n}-bit numbers
+yielding another @var{n}-bit number, it is irrelevant whether the
+numbers are signed or not; the results are the same.
+
+@item @code{div_signed} (0x05): @var{a} @var{b} @result{} @var{a/b}
+Pop two signed integers from the stack; divide the next-to-top value by
+the top value, and push the quotient.  If the divisor is zero, terminate
+with an error.
+
+@item @code{div_unsigned} (0x06): @var{a} @var{b} @result{} @var{a/b}
+Pop two unsigned integers from the stack; divide the next-to-top value
+by the top value, and push the quotient.  If the divisor is zero,
+terminate with an error.
+
+@item @code{rem_signed} (0x07): @var{a} @var{b} @result{} @var{a modulo b}
+Pop two signed integers from the stack; divide the next-to-top value by
+the top value, and push the remainder.  If the divisor is zero,
+terminate with an error.
+
+@item @code{rem_unsigned} (0x08): @var{a} @var{b} @result{} @var{a modulo b}
+Pop two unsigned integers from the stack; divide the next-to-top value
+by the top value, and push the remainder.  If the divisor is zero,
+terminate with an error.
+
+@item @code{lsh} (0x09): @var{a} @var{b} @result{} @var{a<<b}
+Pop two integers from the stack; let @var{a} be the next-to-top value,
+and @var{b} be the top value.  Shift @var{a} left by @var{b} bits, and
+push the result.
+
+@item @code{rsh_signed} (0x0a): @var{a} @var{b} @result{} @var{@code{(signed)}a>>b}
+Pop two integers from the stack; let @var{a} be the next-to-top value,
+and @var{b} be the top value.  Shift @var{a} right by @var{b} bits,
+inserting copies of the top bit at the high end, and push the result.
+
+@item @code{rsh_unsigned} (0x0b): @var{a} @var{b} @result{} @var{a>>b}
+Pop two integers from the stack; let @var{a} be the next-to-top value,
+and @var{b} be the top value.  Shift @var{a} right by @var{b} bits,
+inserting zero bits at the high end, and push the result.
+
+@item @code{log_not} (0x0e): @var{a} @result{} @var{!a}
+Pop an integer from the stack; if it is zero, push the value one;
+otherwise, push the value zero.
+
+@item @code{bit_and} (0x0f): @var{a} @var{b} @result{} @var{a&b}
+Pop two integers from the stack, and push their bitwise @code{and}.
+
+@item @code{bit_or} (0x10): @var{a} @var{b} @result{} @var{a|b}
+Pop two integers from the stack, and push their bitwise @code{or}.
+
+@item @code{bit_xor} (0x11): @var{a} @var{b} @result{} @var{a^b}
+Pop two integers from the stack, and push their bitwise
+exclusive-@code{or}.
+
+@item @code{bit_not} (0x12): @var{a} @result{} @var{~a}
+Pop an integer from the stack, and push its bitwise complement.
+
+@item @code{equal} (0x13): @var{a} @var{b} @result{} @var{a=b}
+Pop two integers from the stack; if they are equal, push the value one;
+otherwise, push the value zero.
+
+@item @code{less_signed} (0x14): @var{a} @var{b} @result{} @var{a<b}
+Pop two signed integers from the stack; if the next-to-top value is less
+than the top value, push the value one; otherwise, push the value zero.
+
+@item @code{less_unsigned} (0x15): @var{a} @var{b} @result{} @var{a<b}
+Pop two unsigned integers from the stack; if the next-to-top value is less
+than the top value, push the value one; otherwise, push the value zero.
+
+@item @code{ext} (0x16) @var{n}: @var{a} @result{} @var{a}, sign-extended from @var{n} bits
+Pop an unsigned value from the stack; treating it as an @var{n}-bit
+twos-complement value, extend it to full length.  This means that all
+bits to the left of bit @var{n-1} (where the least significant bit is bit
+0) are set to the value of bit @var{n-1}.  Note that @var{n} may be
+larger than or equal to the width of the stack elements of the bytecode
+engine; in this case, the bytecode should have no effect.
+
+The number of source bits to preserve, @var{n}, is encoded as a single
+byte unsigned integer following the @code{ext} bytecode.
+
+@item @code{zero_ext} (0x2a) @var{n}: @var{a} @result{} @var{a}, zero-extended from @var{n} bits
+Pop an unsigned value from the stack; zero all but the bottom @var{n}
+bits.  This means that all bits to the left of bit @var{n-1} (where the
+least significant bit is bit 0) are set to the value of bit @var{n-1}.
+
+The number of source bits to preserve, @var{n}, is encoded as a single
+byte unsigned integer following the @code{zero_ext} bytecode.
+
+@item @code{ref8} (0x17): @var{addr} @result{} @var{a}
+@itemx @code{ref16} (0x18): @var{addr} @result{} @var{a}
+@itemx @code{ref32} (0x19): @var{addr} @result{} @var{a}
+@itemx @code{ref64} (0x1a): @var{addr} @result{} @var{a}
+Pop an address @var{addr} from the stack.  For bytecode
+@code{ref}@var{n}, fetch an @var{n}-bit value from @var{addr}, using the
+natural target endianness.  Push the fetched value as an unsigned
+integer.
+
+Note that @var{addr} may not be aligned in any particular way; the
+@code{ref@var{n}} bytecodes should operate correctly for any address.
+
+If attempting to access memory at @var{addr} would cause a processor
+exception of some sort, terminate with an error.
+
+@item @code{ref_float} (0x1b): @var{addr} @result{} @var{d}
+@itemx @code{ref_double} (0x1c): @var{addr} @result{} @var{d}
+@itemx @code{ref_long_double} (0x1d): @var{addr} @result{} @var{d}
+@itemx @code{l_to_d} (0x1e): @var{a} @result{} @var{d}
+@itemx @code{d_to_l} (0x1f): @var{d} @result{} @var{a}
+Not implemented yet.
+
+@item @code{dup} (0x28): @var{a} => @var{a} @var{a}
+Push another copy of the stack's top element.
+
+@item @code{swap} (0x2b): @var{a} @var{b} => @var{b} @var{a}
+Exchange the top two items on the stack.
+
+@item @code{pop} (0x29): @var{a} =>
+Discard the top value on the stack.
+
+@item @code{if_goto} (0x20) @var{offset}: @var{a} @result{}
+Pop an integer off the stack; if it is non-zero, branch to the given
+offset in the bytecode string.  Otherwise, continue to the next
+instruction in the bytecode stream.  In other words, if @var{a} is
+non-zero, set the @code{pc} register to @code{start} + @var{offset}.
+Thus, an offset of zero denotes the beginning of the expression.
+
+The @var{offset} is stored as a sixteen-bit unsigned value, stored
+immediately following the @code{if_goto} bytecode.  It is always stored
+most signficant byte first, regardless of the target's normal
+endianness.  The offset is not guaranteed to fall at any particular
+alignment within the bytecode stream; thus, on machines where fetching a
+16-bit on an unaligned address raises an exception, you should fetch the
+offset one byte at a time.
+
+@item @code{goto} (0x21) @var{offset}: @result{}
+Branch unconditionally to @var{offset}; in other words, set the
+@code{pc} register to @code{start} + @var{offset}.
+
+The offset is stored in the same way as for the @code{if_goto} bytecode.
+
+@item @code{const8} (0x22) @var{n}: @result{} @var{n}
+@itemx @code{const16} (0x23) @var{n}: @result{} @var{n}
+@itemx @code{const32} (0x24) @var{n}: @result{} @var{n}
+@itemx @code{const64} (0x25) @var{n}: @result{} @var{n}
+Push the integer constant @var{n} on the stack, without sign extension.
+To produce a small negative value, push a small twos-complement value,
+and then sign-extend it using the @code{ext} bytecode.
+
+The constant @var{n} is stored in the appropriate number of bytes
+following the @code{const}@var{b} bytecode.  The constant @var{n} is
+always stored most significant byte first, regardless of the target's
+normal endianness.  The constant is not guaranteed to fall at any
+particular alignment within the bytecode stream; thus, on machines where
+fetching a 16-bit on an unaligned address raises an exception, you
+should fetch @var{n} one byte at a time.
+
+@item @code{reg} (0x26) @var{n}: @result{} @var{a}
+Push the value of register number @var{n}, without sign extension.  The
+registers are numbered following GDB's conventions.
+
+The register number @var{n} is encoded as a 16-bit unsigned integer
+immediately following the @code{reg} bytecode.  It is always stored most
+signficant byte first, regardless of the target's normal endianness.
+The register number is not guaranteed to fall at any particular
+alignment within the bytecode stream; thus, on machines where fetching a
+16-bit on an unaligned address raises an exception, you should fetch the
+register number one byte at a time.
+
+@item @code{trace} (0x0c): @var{addr} @var{size} @result{}
+Record the contents of the @var{size} bytes at @var{addr} in a trace
+buffer, for later retrieval by GDB.
+
+@item @code{trace_quick} (0x0d) @var{size}: @var{addr} @result{} @var{addr}
+Record the contents of the @var{size} bytes at @var{addr} in a trace
+buffer, for later retrieval by GDB.  @var{size} is a single byte
+unsigned integer following the @code{trace} opcode.
+
+This bytecode is equivalent to the sequence @code{dup const8 @var{size}
+trace}, but we provide it anyway to save space in bytecode strings.
+
+@item @code{trace16} (0x30) @var{size}: @var{addr} @result{} @var{addr}
+Identical to trace_quick, except that @var{size} is a 16-bit big-endian
+unsigned integer, not a single byte.  This should probably have been
+named @code{trace_quick16}, for consistency.
+
+@item @code{end} (0x27): @result{}
+Stop executing bytecode; the result should be the top element of the
+stack.  If the purpose of the expression was to compute an lvalue or a
+range of memory, then the next-to-top of the stack is the lvalue's
+address, and the top of the stack is the lvalue's size, in bytes.
+
+@end table
+
+
+@node Using Agent Expressions
+@section Using Agent Expressions
+
+Here is a sketch of a full non-stop debugging cycle, showing how agent
+expressions fit into the process.
+
+@itemize @bullet
+
+@item
+The user selects trace points in the program's code at which GDB should
+collect data.
+
+@item
+The user specifies expressions to evaluate at each trace point.  These
+expressions may denote objects in memory, in which case those objects'
+contents are recorded as the program runs, or computed values, in which
+case the values themselves are recorded.
+
+@item
+GDB transmits the tracepoints and their associated expressions to the
+GDB agent, running on the debugging target.
+
+@item
+The agent arranges to be notified when a trace point is hit.  Note that,
+on some systems, the target operating system is completely responsible
+for collecting the data; see @ref{Tracing on Symmetrix}.
+
+@item
+When execution on the target reaches a trace point, the agent evaluates
+the expressions associated with that trace point, and records the
+resulting values and memory ranges.
+
+@item
+Later, when the user selects a given trace event and inspects the
+objects and expression values recorded, GDB talks to the agent to
+retrieve recorded data as necessary to meet the user's requests.  If the
+user asks to see an object whose contents have not been recorded, GDB
+reports an error.
+
+@end itemize
+
+
+@node Varying Target Capabilities
+@section Varying Target Capabilities
+
+Some targets don't support floating-point, and some would rather not
+have to deal with @code{long long} operations.  Also, different targets
+will have different stack sizes, and different bytecode buffer lengths.
+
+Thus, GDB needs a way to ask the target about itself.  We haven't worked
+out the details yet, but in general, GDB should be able to send the
+target a packet asking it to describe itself.  The reply should be a
+packet whose length is explicit, so we can add new information to the
+packet in future revisions of the agent, without confusing old versions
+of GDB, and it should contain a version number.  It should contain at
+least the following information:
+
+@itemize @bullet
+
+@item
+whether floating point is supported
+
+@item
+whether @code{long long} is supported
+
+@item
+maximum acceptable size of bytecode stack
+
+@item
+maximum acceptable length of bytecode expressions
+
+@item
+which registers are actually available for collection
+
+@item
+whether the target supports disabled tracepoints
+
+@end itemize
+
+
+
+@node Tracing on Symmetrix
+@section Tracing on Symmetrix
+
+This section documents the API used by the GDB agent to collect data on
+Symmetrix systems.
+
+Cygnus originally implemented these tracing features to help EMC
+Corporation debug their Symmetrix high-availability disk drives.  The
+Symmetrix application code already includes substantial tracing
+facilities; the GDB agent for the Symmetrix system uses those facilities
+for its own data collection, via the API described here.
+
+@deftypefn Function DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *@var{frame}, char *@var{address}, char **@var{buffer}, unsigned int *@var{size})
+Search the trace frame @var{frame} for memory saved from @var{address}.
+If the memory is available, provide the address of the buffer holding
+it; otherwise, provide the address of the next saved area.
+
+@itemize @bullet
+
+@item
+If the memory at @var{address} was saved in @var{frame}, set
+@code{*@var{buffer}} to point to the buffer in which that memory was
+saved, set @code{*@var{size}} to the number of bytes from @var{address}
+that are saved at @code{*@var{buffer}}, and return
+@code{OK_TARGET_RESPONSE}.  (Clearly, in this case, the function will
+always set @code{*@var{size}} to a value greater than zero.)
+
+@item
+If @var{frame} does not record any memory at @var{address}, set
+@code{*@var{size}} to the distance from @var{address} to the start of
+the saved region with the lowest address higher than @var{address}.  If
+there is no memory saved from any higher address, set @code{*@var{size}}
+to zero.  Return @code{NOT_FOUND_TARGET_RESPONSE}.
+@end itemize
+
+These two possibilities allow the caller to either retrieve the data, or
+walk the address space to the next saved area.
+@end deftypefn
+
+This function allows the GDB agent to map the regions of memory saved in
+a particular frame, and retrieve their contents efficiently.
+
+This function also provides a clean interface between the GDB agent and
+the Symmetrix tracing structures, making it easier to adapt the GDB
+agent to future versions of the Symmetrix system, and vice versa.  This
+function searches all data saved in @var{frame}, whether the data is
+there at the request of a bytecode expression, or because it falls in
+one of the format's memory ranges, or because it was saved from the top
+of the stack.  EMC can arbitrarily change and enhance the tracing
+mechanism, but as long as this function works properly, all collected
+memory is visible to GDB.
+
+The function itself is straightforward to implement.  A single pass over
+the trace frame's stack area, memory ranges, and expression blocks can
+yield the address of the buffer (if the requested address was saved),
+and also note the address of the next higher range of memory, to be
+returned when the search fails.
+
+As an example, suppose the trace frame @code{f} has saved sixteen bytes
+from address @code{0x8000} in a buffer at @code{0x1000}, and thirty-two
+bytes from address @code{0xc000} in a buffer at @code{0x1010}.  Here are
+some sample calls, and the effect each would have:
+
+@table @code
+
+@item adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size)
+This would set @code{buffer} to @code{0x1000}, set @code{size} to
+sixteen, and return @code{OK_TARGET_RESPONSE}, since @code{f} saves
+sixteen bytes from @code{0x8000} at @code{0x1000}.
+
+@item adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size)
+This would set @code{buffer} to @code{0x1004}, set @code{size} to
+twelve, and return @code{OK_TARGET_RESPONSE}, since @file{f} saves the
+twelve bytes from @code{0x8004} starting four bytes into the buffer at
+@code{0x1000}.  This shows that request addresses may fall in the middle
+of saved areas; the function should return the address and size of the
+remainder of the buffer.
+
+@item adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size)
+This would set @code{size} to @code{0x3f00} and return
+@code{NOT_FOUND_TARGET_RESPONSE}, since there is no memory saved in
+@code{f} from the address @code{0x8100}, and the next memory available
+is at @code{0x8100 + 0x3f00}, or @code{0xc000}.  This shows that request
+addresses may fall outside of all saved memory ranges; the function
+should indicate the next saved area, if any.
+
+@item adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size)
+This would set @code{size} to @code{0x1000} and return
+@code{NOT_FOUND_TARGET_RESPONSE}, since the next saved memory is at
+@code{0x7000 + 0x1000}, or @code{0x8000}.
+
+@item adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size)
+This would set @code{size} to zero, and return
+@code{NOT_FOUND_TARGET_RESPONSE}.  This shows how the function tells the
+caller that no further memory ranges have been saved.
+
+@end table
+
+As another example, here is a function which will print out the
+addresses of all memory saved in the trace frame @code{frame} on the
+Symmetrix INLINES console:
+@example
+void
+print_frame_addresses (FRAME_DEF *frame)
+@{
+  char *addr;
+  char *buffer;
+  unsigned long size;
+
+  addr = 0;
+  for (;;)
+    @{
+      /* Either find out how much memory we have here, or discover
+         where the next saved region is.  */
+      if (adbg_find_memory_in_frame (frame, addr, &buffer, &size)
+          == OK_TARGET_RESPONSE)
+        printp ("saved %x to %x\n", addr, addr + size);
+      if (size == 0)
+        break;
+      addr += size;
+    @}
+@}
+@end example
+
+Note that there is not necessarily any connection between the order in
+which the data is saved in the trace frame, and the order in which
+@code{adbg_find_memory_in_frame} will return those memory ranges.  The
+code above will always print the saved memory regions in order of
+increasing address, while the underlying frame structure might store the
+data in a random order.
+
+[[This section should cover the rest of the Symmetrix functions the stub
+relies upon, too.]]
+
+@node Rationale
+@section Rationale
+
+Some of the design decisions apparent above are arguable.
+
+@table @b
+
+@item What about stack overflow/underflow?
+GDB should be able to query the target to discover its stack size.
+Given that information, GDB can determine at translation time whether a
+given expression will overflow the stack.  But this spec isn't about
+what kinds of error-checking GDB ought to do.
+
+@item Why are you doing everything in LONGEST?
+
+Speed isn't important, but agent code size is; using LONGEST brings in a
+bunch of support code to do things like division, etc.  So this is a
+serious concern.
+
+First, note that you don't need different bytecodes for different
+operand sizes.  You can generate code without @emph{knowing} how big the
+stack elements actually are on the target.  If the target only supports
+32-bit ints, and you don't send any 64-bit bytecodes, everything just
+works.  The observation here is that the MIPS and the Alpha have only
+fixed-size registers, and you can still get C's semantics even though
+most instructions only operate on full-sized words.  You just need to
+make sure everything is properly sign-extended at the right times.  So
+there is no need for 32- and 64-bit variants of the bytecodes.  Just
+implement everything using the largest size you support.
+
+GDB should certainly check to see what sizes the target supports, so the
+user can get an error earlier, rather than later.  But this information
+is not necessary for correctness.
+
+
+@item Why don't you have @code{>} or @code{<=} operators?
+I want to keep the interpreter small, and we don't need them.  We can
+combine the @code{less_} opcodes with @code{log_not}, and swap the order
+of the operands, yielding all four asymmetrical comparison operators.
+For example, @code{(x <= y)} is @code{! (x > y)}, which is @code{! (y <
+x)}.
+
+@item Why do you have @code{log_not}?
+@itemx Why do you have @code{ext}?
+@itemx Why do you have @code{zero_ext}?
+These are all easily synthesized from other instructions, but I expect
+them to be used frequently, and they're simple, so I include them to
+keep bytecode strings short.
+
+@code{log_not} is equivalent to @code{const8 0 equal}; it's used in half
+the relational operators.
+
+@code{ext @var{n}} is equivalent to @code{const8 @var{s-n} lsh const8
+@var{s-n} rsh_signed}, where @var{s} is the size of the stack elements;
+it follows @code{ref@var{m}} and @var{reg} bytecodes when the value
+should be signed.  See the next bulleted item.
+
+@code{zero_ext @var{n}} is equivalent to @code{const@var{m} @var{mask}
+log_and}; it's used whenever we push the value of a register, because we
+can't assume the upper bits of the register aren't garbage.
+
+@item Why not have sign-extending variants of the @code{ref} operators?
+Because that would double the number of @code{ref} operators, and we
+need the @code{ext} bytecode anyway for accessing bitfields.
+
+@item Why not have constant-address variants of the @code{ref} operators?
+Because that would double the number of @code{ref} operators again, and
+@code{const32 @var{address} ref32} is only one byte longer.
+
+@item Why do the @code{ref@var{n}} operators have to support unaligned fetches?
+GDB will generate bytecode that fetches multi-byte values at unaligned
+addresses whenever the executable's debugging information tells it to.
+Furthermore, GDB does not know the value the pointer will have when GDB
+generates the bytecode, so it cannot determine whether a particular
+fetch will be aligned or not.
+
+In particular, structure bitfields may be several bytes long, but follow
+no alignment rules; members of packed structures are not necessarily
+aligned either.
+
+In general, there are many cases where unaligned references occur in
+correct C code, either at the programmer's explicit request, or at the
+compiler's discretion.  Thus, it is simpler to make the GDB agent
+bytecodes work correctly in all circumstances than to make GDB guess in
+each case whether the compiler did the usual thing.
+
+@item Why are there no side-effecting operators?
+Because our current client doesn't want them?  That's a cheap answer.  I
+think the real answer is that I'm afraid of implementing function
+calls.  We should re-visit this issue after the present contract is
+delivered.
+
+@item Why aren't the @code{goto} ops PC-relative?
+The interpreter has the base address around anyway for PC bounds
+checking, and it seemed simpler.
+
+@item Why is there only one offset size for the @code{goto} ops?
+Offsets are currently sixteen bits.  I'm not happy with this situation
+either:
+
+Suppose we have multiple branch ops with different offset sizes.  As I
+generate code left-to-right, all my jumps are forward jumps (there are
+no loops in expressions), so I never know the target when I emit the
+jump opcode.  Thus, I have to either always assume the largest offset
+size, or do jump relaxation on the code after I generate it, which seems
+like a big waste of time.
+
+I can imagine a reasonable expression being longer than 256 bytes.  I
+can't imagine one being longer than 64k.  Thus, we need 16-bit offsets.
+This kind of reasoning is so bogus, but relaxation is pathetic.
+
+The other approach would be to generate code right-to-left.  Then I'd
+always know my offset size.  That might be fun.
+
+@item Where is the function call bytecode?
+
+When we add side-effects, we should add this.
+
+@item Why does the @code{reg} bytecode take a 16-bit register number?
+
+Intel's IA64-architecture, Merced, has 128 general-purpose registers,
+and 128 floating-point registers, and I'm sure it has some random
+control registers.
+
+@item Why do we need @code{trace} and @code{trace_quick}?
+Because GDB needs to record all the memory contents and registers an
+expression touches.  If the user wants to evaluate an expression
+@code{x->y->z}, the agent must record the values of @code{x} and
+@code{x->y} as well as the value of @code{x->y->z}.
+
+@item Don't the @code{trace} bytecodes make the interpreter less general?
+They do mean that the interpreter contains special-purpose code, but
+that doesn't mean the interpreter can only be used for that purpose.  If
+an expression doesn't use the @code{trace} bytecodes, they don't get in
+its way.
+
+@item Why doesn't @code{trace_quick} consume its arguments the way everything else does?
+In general, you do want your operators to consume their arguments; it's
+consistent, and generally reduces the amount of stack rearrangement
+necessary.  However, @code{trace_quick} is a kludge to save space; it
+only exists so we needn't write @code{dup const8 @var{SIZE} trace}
+before every memory reference.  Therefore, it's okay for it not to
+consume its arguments; it's meant for a specific context in which we
+know exactly what it should do with the stack.  If we're going to have a
+kludge, it should be an effective kludge.
+
+@item Why does @code{trace16} exist?
+That opcode was added by the customer that contracted Cygnus for the
+data tracing work.  I personally think it is unnecessary; objects that
+large will be quite rare, so it is okay to use @code{dup const16
+@var{size} trace} in those cases.
+
+Whatever we decide to do with @code{trace16}, we should at least leave
+opcode 0x30 reserved, to remain compatible with the customer who added
+it.
+
+@end table
+
+@bye
diff --git a/gdb/doc/all-cfg.texi b/gdb/doc/all-cfg.texi
new file mode 100644
index 0000000000..74d8090b51
--- /dev/null
+++ b/gdb/doc/all-cfg.texi
@@ -0,0 +1,112 @@
+@c GDB MANUAL configuration file.  
+@c Copyright (c) 1993 Free Software Foundation, Inc.
+@c
+@c NOTE: While the GDB manual is configurable (by changing these
+@c switches), its configuration is ***NOT*** automatically tied in to
+@c source configuration---because the authors expect that, save in
+@c unusual cases, the most inclusive form of the manual is appropriate
+@c no matter how the program itself is configured.
+@c
+@c The only automatically-varying variable is the GDB version number,
+@c which the Makefile rewrites based on the VERSION variable from
+@c `../Makefile.in'.  
+@c 
+@c GDB version number is recorded in the variable GDBVN
+@include GDBvn.texi
+@c
+@c ----------------------------------------------------------------------
+@c PLATFORM FLAGS:
+@set GENERIC
+@c
+@c HP PA-RISC target ONLY:
+@clear HPPA
+@c
+@c Hitachi H8/300 target:
+@set H8
+@c Hitachi H8/300 target ONLY:
+@clear H8EXCLUSIVE
+@c
+@c remote MIPS target:
+@set MIPS
+@c
+@c SPARC target:
+@set SPARC
+@set SPARCLET
+@c
+@c AMD 29000 target:
+@set AMD29K
+@c
+@c Intel 960 target:
+@set I960
+@c
+@c Tandem ST2000 (phone switch) target:
+@set ST2000
+@c
+@c Zilog 8000 target:
+@set Z8K
+@c
+@c Wind River Systems VxWorks environment:
+@set VXWORKS
+@c
+@c ----------------------------------------------------------------------
+@c DOC FEATURE FLAGS:
+@c 
+@c Bare-board target?
+@clear BARETARGET
+@c
+@c Restrict languages discussed to C?
+@c This is backward.  As time permits, change this to language-specific
+@c switches for what to include.
+@clear CONLY
+@c Discuss Fortran?
+@set FORTRAN
+@c
+@c Discuss Modula 2?
+@set MOD2
+@c
+@c Specifically for host machine running DOS?
+@clear DOSHOST
+@c
+@c Talk about CPU simulator targets?
+@set SIMS
+@c
+@c Remote serial line settings of interest?
+@set SERIAL
+@c
+@c Discuss features requiring Posix or similar OS environment?
+@set POSIX
+@c
+@c Discuss remote serial debugging stub?
+@set REMOTESTUB
+@c
+@c Discuss gdbserver?
+@set GDBSERVER
+@c
+@c Discuss gdbserve.nlm?
+@set GDBSERVE
+@c
+@c Refrain from discussing how to configure sw and format doc?
+@clear PRECONFIGURED
+@c
+@c Refrain from referring to unfree publications?
+@set FSFDOC
+@c
+@c ----------------------------------------------------------------------
+@c STRINGS:
+@c
+@c Name of GDB program.  Used also for (gdb) prompt string.
+@set GDBP gdb
+@c 
+@c Name of GDB product.  Used in running text.
+@set GDBN GDB
+@c
+@c Name of host.  Should not be used in generic configs, but generic
+@c value may catch some flubs.
+@set HOST machine specific
+@c
+@c Name of GCC product
+@set NGCC GCC
+@c 
+@c Name of GCC program
+@set GCC gcc
+
diff --git a/gdb/doc/annotate.texi b/gdb/doc/annotate.texi
new file mode 100644
index 0000000000..9d5850dbf2
--- /dev/null
+++ b/gdb/doc/annotate.texi
@@ -0,0 +1,717 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename annotate.info
+@settitle GDB Annotations
+@setchapternewpage off
+@c %**end of header
+
+@set EDITION 0.5
+@set DATE May 1994
+
+@ifinfo
+This file documents GDB annotations.
+
+This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
+Annotations}.  Copyright 1994 Free Software Foundation
+
+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.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+
+@titlepage
+@title GDB Annotations
+@subtitle Edition @value{EDITION}
+@subtitle @value{DATE}
+@author Cygnus Support
+@page
+@vskip 0pt plus 1filll
+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.
+
+Copyright @copyright{} 1994 Free Software Foundation
+@end titlepage
+
+@ifinfo
+@node Top
+@top GDB Annotations
+
+This file describes annotations in GDB, the GNU symbolic debugger.
+Annotations are designed to interface GDB to graphical user interfaces
+or other similar programs which want to interact with GDB at a
+relatively high level.
+
+This is Edition @value{EDITION}, @value{DATE}.
+
+@menu
+* General::             What annotations are; the general syntax.
+* Server::              Issuing a command without affecting user state.
+* Values::              Values are marked as such.
+* Frames::              Stack frames are annotated.
+* Displays::            GDB can be told to display something periodically.
+* Prompting::           Annotations marking GDB's need for input.
+* Errors::              Annotations for error messages.
+* Breakpoint Info::     Information on breakpoints.
+* Invalidation::        Some annotations describe things now invalid.
+* Running::             Whether the program is running, how it stopped, etc.
+* Source::              Annotations describing source code.
+* TODO::                Annotations which might be added in the future.
+* Index::               Index
+@end menu
+@end ifinfo
+
+@node General
+@chapter What is an Annotation?
+
+To produce annotations, start GDB with the @code{--annotate=2} option.
+
+Annotations start with a newline character, two @samp{control-z}
+characters, and the name of the annotation.  If there is no additional
+information associated with this annotation, the name of the annotation
+is followed immediately by a newline.  If there is additional
+information, the name of the annotation is followed by a space, the
+additional information, and a newline.  The additional information
+cannot contain newline characters.
+
+Any output not beginning with a newline and two @samp{control-z}
+characters denotes literal output from GDB.  Currently there is no need
+for GDB to output a newline followed by two @samp{control-z} characters,
+but if there was such a need, the annotations could be extended with an
+@samp{escape} annotation which means those three characters as output.
+
+A simple example of starting up GDB with annotations is:
+
+@example
+$ gdb --annotate=2
+GDB is free software and you are welcome to distribute copies of it
+ under certain conditions; type "show copying" to see the conditions.
+There is absolutely no warranty for GDB; type "show warranty" for details.
+GDB 4.12.3 (sparc-sun-sunos4.1.3), 
+Copyright 1994 Free Software Foundation, Inc.
+
+^Z^Zpre-prompt
+(gdb) 
+^Z^Zprompt
+quit
+
+^Z^Zpost-prompt
+$ 
+@end example
+
+Here @samp{quit} is input to GDB; the rest is output from GDB.  The three
+lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
+character) are annotations; the rest is output from GDB.
+
+@node Server
+@chapter The Server Prefix
+
+To issue a command to GDB without affecting certain aspects of the state
+which is seen by users, prefix it with @samp{server }.  This means that
+this command will not affect the command history, nor will it affect
+GDB's notion of which command to repeat if @key{RET} is pressed on a
+line by itself.
+
+The server prefix does not affect the recording of values into the value
+history; to print a value without recording it into the value history,
+use the @code{output} command instead of the @code{print} command.
+
+@node Values
+@chapter Values
+
+When a value is printed in various contexts, GDB uses annotations to
+delimit the value from the surrounding text.
+
+@findex value-history-begin
+@findex value-history-value
+@findex value-history-end
+If a value is printed using @code{print} and added to the value history,
+the annotation looks like
+
+@example
+^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
+@var{history-string}
+^Z^Zvalue-history-value
+@var{the-value}
+^Z^Zvalue-history-end
+@end example
+
+where @var{history-number} is the number it is getting in the value
+history, @var{history-string} is a string, such as @samp{$5 = }, which
+introduces the value to the user, @var{the-value} is the output
+corresponding to the value itself, and @var{value-flags} is @samp{*} for
+a value which can be dereferenced and @samp{-} for a value which cannot.
+
+@findex value-begin
+@findex value-end
+If the value is not added to the value history (it is an invalid float
+or it is printed with the @code{output} command), the annotation is similar:
+
+@example
+^Z^Zvalue-begin @var{value-flags}
+@var{the-value}
+^Z^Zvalue-end
+@end example
+
+@findex arg-begin
+@findex arg-name-end
+@findex arg-value
+@findex arg-end
+When GDB prints an argument to a function (for example, in the output
+from the @code{backtrace} command), it annotates it as follows:
+
+@example
+^Z^Zarg-begin
+@var{argument-name}
+^Z^Zarg-name-end
+@var{separator-string}
+^Z^Zarg-value @var{value-flags}
+@var{the-value}
+^Z^Zarg-end
+@end example
+
+where @var{argument-name} is the name of the argument,
+@var{separator-string} is text which separates the name from the value
+for the user's benefit (such as @samp{=}), and @var{value-flags} and
+@var{the-value} have the same meanings as in a
+@code{value-history-begin} annotation.
+
+@findex field-begin
+@findex field-name-end
+@findex field-value
+@findex field-end
+When printing a structure, GDB annotates it as follows:
+
+@example
+^Z^Zfield-begin @var{value-flags}
+@var{field-name}
+^Z^Zfield-name-end
+@var{separator-string}
+^Z^Zfield-value
+@var{the-value}
+^Z^Zfield-end
+@end example
+
+where @var{field-name} is the name of the field, @var{separator-string}
+is text which separates the name from the value for the user's benefit
+(such as @samp{=}), and @var{value-flags} and @var{the-value} have the
+same meanings as in a @code{value-history-begin} annotation.
+
+When printing an array, GDB annotates it as follows:
+
+@example
+^Z^Zarray-section-begin @var{array-index} @var{value-flags}
+@end example
+
+where @var{array-index} is the index of the first element being
+annotated and @var{value-flags} has the same meaning as in a
+@code{value-history-begin} annotation.  This is followed by any number
+of elements, where is element can be either a single element:
+
+@findex elt
+@example
+@samp{,} @var{whitespace}         ; @r{omitted for the first element}
+@var{the-value}
+^Z^Zelt
+@end example
+
+or a repeated element
+
+@findex elt-rep
+@findex elt-rep-end
+@example
+@samp{,} @var{whitespace}         ; @r{omitted for the first element}
+@var{the-value}
+^Z^Zelt-rep @var{number-of-repititions}
+@var{repetition-string}
+^Z^Zelt-rep-end
+@end example
+
+In both cases, @var{the-value} is the output for the value of the
+element and @var{whitespace} can contain spaces, tabs, and newlines.  In
+the repeated case, @var{number-of-repititons} is the number of
+consecutive array elements which contain that value, and
+@var{repetition-string} is a string which is designed to convey to the
+user that repitition is being depicted.
+
+@findex array-section-end
+Once all the array elements have been output, the array annotation is
+ended with
+
+@example
+^Z^Zarray-section-end
+@end example
+
+@node Frames
+@chapter Frames
+
+Whenever GDB prints a frame, it annotates it.  For example, this applies
+to frames printed when GDB stops, output from commands such as
+@code{backtrace} or @code{up}, etc.
+
+@findex frame-begin
+The frame annotation begins with
+
+@example
+^Z^Zframe-begin @var{level} @var{address}
+@var{level-string}
+@end example
+
+where @var{level} is the number of the frame (0 is the innermost frame,
+and other frames have positive numbers), @var{address} is the address of
+the code executing in that frame, and @var{level-string} is a string
+designed to convey the level to the user.  @var{address} is in the form
+@samp{0x} followed by one or more lowercase hex digits (note that this
+does not depend on the language).  The frame ends with
+
+@findex frame-end
+@example
+^Z^Zframe-end
+@end example
+
+Between these annotations is the main body of the frame, which can
+consist of
+
+@itemize @bullet
+@item
+@findex function-call
+@example
+^Z^Zfunction-call
+@var{function-call-string}
+@end example
+
+where @var{function-call-string} is text designed to convey to the user
+that this frame is associated with a function call made by GDB to a
+function in the program being debugged.
+
+@item
+@findex signal-handler-caller
+@example
+^Z^Zsignal-handler-caller
+@var{signal-handler-caller-string}
+@end example
+
+where @var{signal-handler-caller-string} is text designed to convey to
+the user that this frame is associated with whatever mechanism is used
+by this operating system to call a signal handler (it is the frame which
+calls the signal handler, not the frame for the signal handler itself).
+
+@item
+A normal frame.
+
+@findex frame-address
+@findex frame-address-end
+This can optionally (depending on whether this is thought of as
+interesting information for the user to see) begin with
+
+@example
+^Z^Zframe-address
+@var{address}
+^Z^Zframe-address-end
+@var{separator-string}
+@end example
+
+where @var{address} is the address executing in the frame (the same
+address as in the @code{frame-begin} annotation, but printed in a form
+which is intended for user consumption---in particular, the syntax varies
+depending on the language), and @var{separator-string} is a string
+intended to separate this address from what follows for the user's
+benefit.
+
+@findex frame-function-name
+@findex frame-args
+Then comes
+
+@example
+^Z^Zframe-function-name
+@var{function-name}
+^Z^Zframe-args
+@var{arguments}
+@end example
+
+where @var{function-name} is the name of the function executing in the
+frame, or @samp{??} if not known, and @var{arguments} are the arguments
+to the frame, with parentheses around them (each argument is annotated
+individually as well @pxref{Values}).
+
+@findex frame-source-begin
+@findex frame-source-file
+@findex frame-source-file-end
+@findex frame-source-line
+@findex frame-source-end
+If source information is available, a reference to it is then printed:
+
+@example
+^Z^Zframe-source-begin
+@var{source-intro-string}
+^Z^Zframe-source-file
+@var{filename}
+^Z^Zframe-source-file-end
+:
+^Z^Zframe-source-line
+@var{line-number}
+^Z^Zframe-source-end
+@end example
+
+where @var{source-intro-string} separates for the user's benefit the
+reference from the text which precedes it, @var{filename} is the name of
+the source file, and @var{line-number} is the line number within that
+file (the first line is line 1).
+
+@findex frame-where
+If GDB prints some information about where the frame is from (which
+library, which load segment, etc.; currently only done on the RS/6000),
+it is annotated with
+
+@example
+^Z^Zframe-where
+@var{information}
+@end example
+
+Then, if source is to actually be displayed for this frame (for example,
+this is not true for output from the @code{backtrace} command), then a
+@code{source} annotation (@pxref{Source}) is displayed.  Unlike most
+annotations, this is output instead of the normal text which would be
+output, not in addition.
+@end itemize
+
+@node Displays
+@chapter Displays
+
+@findex display-begin
+@findex display-number-end
+@findex display-format
+@findex display-expression
+@findex display-expression-end
+@findex display-value
+@findex display-end
+When GDB is told to display something using the @code{display} command,
+the results of the display are annotated:
+
+@example
+^Z^Zdisplay-begin
+@var{number}
+^Z^Zdisplay-number-end
+@var{number-separator}
+^Z^Zdisplay-format
+@var{format}
+^Z^Zdisplay-expression
+@var{expression}
+^Z^Zdisplay-expression-end
+@var{expression-separator}
+^Z^Zdisplay-value
+@var{value}
+^Z^Zdisplay-end
+@end example
+
+where @var{number} is the number of the display, @var{number-separator}
+is intended to separate the number from what follows for the user,
+@var{format} includes information such as the size, format, or other
+information about how the value is being displayed, @var{expression} is
+the expression being displayed, @var{expression-separator} is intended
+to separate the expression from the text that follows for the user,
+and @var{value} is the actual value being displayed.
+
+@node Prompting
+@chapter Annotation for GDB Input
+
+When GDB prompts for input, it annotates this fact so it is possible
+to know when to send output, when the output from a given command is
+over, etc.
+
+Different kinds of input each have a different @dfn{input type}.  Each
+input type has three annotations: a @code{pre-} annotation, which
+denotes the beginning of any prompt which is being output, a plain
+annotation, which denotes the end of the prompt, and then a @code{post-}
+annotation which denotes the end of any echo which may (or may not) be
+associated with the input.  For example, the @code{prompt} input type
+features the following annotations:
+
+@example
+^Z^Zpre-prompt
+^Z^Zprompt
+^Z^Zpost-prompt
+@end example
+
+The input types are
+
+@table @code
+@findex pre-prompt
+@findex prompt
+@findex post-prompt
+@item prompt
+When GDB is prompting for a command (the main GDB prompt).
+
+@findex pre-commands
+@findex commands
+@findex post-commands
+@item commands
+When GDB prompts for a set of commands, like in the @code{commands}
+command.  The annotations are repeated for each command which is input.
+
+@findex pre-overload-choice
+@findex overload-choice
+@findex post-overload-choice
+@item overload-choice
+When GDB wants the user to select between various overloaded functions.
+
+@findex pre-query
+@findex query
+@findex post-query
+@item query
+When GDB wants the user to confirm a potentially dangerous operation.
+
+@findex pre-prompt-for-continue
+@findex prompt-for-continue
+@findex post-prompt-for-continue
+@item prompt-for-continue
+When GDB is asking the user to press return to continue.  Note: Don't
+expect this to work well; instead use @code{set height 0} to disable
+prompting.  This is because the counting of lines is buggy in the
+presence of annotations.
+@end table
+
+@node Errors
+@chapter Errors
+
+@findex quit
+@example
+^Z^Zquit
+@end example
+
+This annotation occurs right before GDB responds to an interrupt.
+
+@findex error
+@example
+^Z^Zerror
+@end example
+
+This annotation occurs right before GDB responds to an error.
+
+Quit and error annotations indicate that any annotations which GDB was
+in the middle of may end abruptly.  For example, if a
+@code{value-history-begin} annotation is followed by a @code{error}, one
+cannot expect to receive the matching @code{value-history-end}.  One
+cannot expect not to receive it either, however; an error annotation
+does not necessarily mean that GDB is immediately returning all the way
+to the top level.
+
+@findex error-begin
+A quit or error annotation may be preceded by
+
+@example
+^Z^Zerror-begin
+@end example
+
+Any output between that and the quit or error annotation is the error
+message.
+
+Warning messages are not yet annotated.
+@c If we want to change that, need to fix warning(), type_error(),
+@c range_error(), and possibly other places.
+
+@node Breakpoint Info
+@chapter Information on Breakpoints
+
+The output from the @code{info breakpoints} command is annotated as follows:
+
+@findex breakpoints-headers
+@findex breakpoints-table
+@example
+^Z^Zbreakpoints-headers
+@var{header-entry}
+^Z^Zbreakpoints-table
+@end example
+
+where @var{header-entry} has the same syntax as an entry (see below) but
+instead of containing data, it contains strings which are intended to
+convey the meaning of each field to the user.  This is followed by any
+number of entries.  If a field does not apply for this entry, it is
+omitted.  Fields may contain trailing whitespace.  Each entry consists
+of:
+
+@findex record
+@findex field
+@example
+^Z^Zrecord
+^Z^Zfield 0
+@var{number}
+^Z^Zfield 1
+@var{type}
+^Z^Zfield 2
+@var{disposition}
+^Z^Zfield 3
+@var{enable}
+^Z^Zfield 4
+@var{address}
+^Z^Zfield 5
+@var{what}
+^Z^Zfield 6
+@var{frame}
+^Z^Zfield 7
+@var{condition}
+^Z^Zfield 8
+@var{ignore-count}
+^Z^Zfield 9
+@var{commands}
+@end example
+
+Note that @var{address} is intended for user consumption---the syntax
+varies depending on the language.
+
+The output ends with
+
+@findex breakpoints-table-end
+@example
+^Z^Zbreakpoints-table-end
+@end example
+
+@node Invalidation
+@chapter Invalidation Notices
+
+The following annotations say that certain pieces of state may have
+changed.
+
+@table @code
+@findex frames-invalid
+@item ^Z^Zframes-invalid
+
+The frames (for example, output from the @code{backtrace} command) may
+have changed.
+
+@findex breakpoints-invalid
+@item ^Z^Zbreakpoints-invalid
+
+The breakpoints may have changed.  For example, the user just added or
+deleted a breakpoint.
+@end table
+
+@node Running
+@chapter Running the Program
+
+@findex starting
+@findex stopping
+When the program starts executing due to a GDB command such as
+@code{step} or @code{continue}, 
+
+@example
+^Z^Zstarting
+@end example
+
+is output.  When the program stops, 
+
+@example
+^Z^Zstopped
+@end example
+
+is output.  Before the @code{stopped} annotation, a variety of
+annotations describe how the program stopped.
+
+@table @code
+@findex exited
+@item ^Z^Zexited @var{exit-status}
+The program exited, and @var{exit-status} is the exit status (zero for
+successful exit, otherwise nonzero).
+
+@findex signalled
+@findex signal-name
+@findex signal-name-end
+@findex signal-string
+@findex signal-string-end
+@item ^Z^Zsignalled
+The program exited with a signal.  After the @code{^Z^Zsignalled}, the
+annotation continues:
+
+@example
+@var{intro-text}
+^Z^Zsignal-name
+@var{name}
+^Z^Zsignal-name-end
+@var{middle-text}
+^Z^Zsignal-string
+@var{string}
+^Z^Zsignal-string-end
+@var{end-text}
+@end example
+
+where @var{name} is the name of the signal, such as @code{SIGILL} or
+@code{SIGSEGV}, and @var{string} is the explanation of the signal, such
+as @code{Illegal Instruction} or @code{Segmentation fault}.
+@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
+user's benefit and have no particular format.
+
+@findex signal
+@item ^Z^Zsignal
+The syntax of this annotation is just like @code{signalled}, but GDB is
+just saying that the program received the signal, not that it was
+terminated with it.
+
+@findex breakpoint
+@item ^Z^Zbreakpoint @var{number}
+The program hit breakpoint number @var{number}.
+
+@findex watchpoint
+@item ^Z^Zwatchpoint @var{number}
+The program hit watchpoint number @var{number}.
+@end table
+
+@node Source
+@chapter Displaying Source
+
+@findex source
+The following annotation is used instead of displaying source code:
+
+@example
+^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
+@end example
+
+where @var{filename} is an absolute file name indicating which source
+file, @var{line} is the line number within that file (where 1 is the
+first line in the file), @var{character} is the character position
+within the file (where 0 is the first character in the file) (for most
+debug formats this will necessarily point to the beginning of a line),
+@var{middle} is @samp{middle} if @var{addr} is in the middle of the
+line, or @samp{beg} if @var{addr} is at the beginning of the line, and
+@var{addr} is the address in the target program associated with the
+source which is being displayed.  @var{addr} is in the form @samp{0x}
+followed by one or more lowercase hex digits (note that this does not
+depend on the language).
+
+@node TODO
+@chapter Annotations We Might Want in the Future
+
+@format
+    - target-invalid
+      the target might have changed (registers, heap contents, or
+      execution status).  For performance, we might eventually want
+      to hit `registers-invalid' and `all-registers-invalid' with
+      greater precision
+
+    - systematic annotation for set/show parameters (including
+      invalidation notices).
+
+    - similarly, `info' returns a list of candidates for invalidation
+      notices.
+@end format
+
+@node Index
+@unnumbered Index
+
+@printindex fn
+
+@bye
diff --git a/gdb/doc/configure b/gdb/doc/configure
new file mode 100755
index 0000000000..8c5591ce05
--- /dev/null
+++ b/gdb/doc/configure
@@ -0,0 +1,862 @@
+#! /bin/sh
+
+# Guess values for system-dependent variables and create Makefiles.
+# Generated automatically using autoconf version 2.12.2 
+# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc.
+#
+# This configure script is free software; the Free Software Foundation
+# gives unlimited permission to copy, distribute and modify it.
+
+# Defaults:
+ac_help=
+ac_default_prefix=/usr/local
+# Any additions from configure.in:
+
+# Initialize some variables set by options.
+# The variables have the same names as the options, with
+# dashes changed to underlines.
+build=NONE
+cache_file=./config.cache
+exec_prefix=NONE
+host=NONE
+no_create=
+nonopt=NONE
+no_recursion=
+prefix=NONE
+program_prefix=NONE
+program_suffix=NONE
+program_transform_name=s,x,x,
+silent=
+site=
+srcdir=
+target=NONE
+verbose=
+x_includes=NONE
+x_libraries=NONE
+bindir='${exec_prefix}/bin'
+sbindir='${exec_prefix}/sbin'
+libexecdir='${exec_prefix}/libexec'
+datadir='${prefix}/share'
+sysconfdir='${prefix}/etc'
+sharedstatedir='${prefix}/com'
+localstatedir='${prefix}/var'
+libdir='${exec_prefix}/lib'
+includedir='${prefix}/include'
+oldincludedir='/usr/include'
+infodir='${prefix}/info'
+mandir='${prefix}/man'
+
+# Initialize some other variables.
+subdirs=
+MFLAGS= MAKEFLAGS=
+SHELL=${CONFIG_SHELL-/bin/sh}
+# Maximum number of lines to put in a shell here document.
+ac_max_here_lines=12
+
+ac_prev=
+for ac_option
+do
+
+  # If the previous option needs an argument, assign it.
+  if test -n "$ac_prev"; then
+    eval "$ac_prev=\$ac_option"
+    ac_prev=
+    continue
+  fi
+
+  case "$ac_option" in
+  -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
+  *) ac_optarg= ;;
+  esac
+
+  # Accept the important Cygnus configure options, so we can diagnose typos.
+
+  case "$ac_option" in
+
+  -bindir | --bindir | --bindi | --bind | --bin | --bi)
+    ac_prev=bindir ;;
+  -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*)
+    bindir="$ac_optarg" ;;
+
+  -build | --build | --buil | --bui | --bu)
+    ac_prev=build ;;
+  -build=* | --build=* | --buil=* | --bui=* | --bu=*)
+    build="$ac_optarg" ;;
+
+  -cache-file | --cache-file | --cache-fil | --cache-fi \
+  | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c)
+    ac_prev=cache_file ;;
+  -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \
+  | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*)
+    cache_file="$ac_optarg" ;;
+
+  -datadir | --datadir | --datadi | --datad | --data | --dat | --da)
+    ac_prev=datadir ;;
+  -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \
+  | --da=*)
+    datadir="$ac_optarg" ;;
+
+  -disable-* | --disable-*)
+    ac_feature=`echo $ac_option|sed -e 's/-*disable-//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then
+      { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
+    fi
+    ac_feature=`echo $ac_feature| sed 's/-/_/g'`
+    eval "enable_${ac_feature}=no" ;;
+
+  -enable-* | --enable-*)
+    ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then
+      { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
+    fi
+    ac_feature=`echo $ac_feature| sed 's/-/_/g'`
+    case "$ac_option" in
+      *=*) ;;
+      *) ac_optarg=yes ;;
+    esac
+    eval "enable_${ac_feature}='$ac_optarg'" ;;
+
+  -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \
+  | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \
+  | --exec | --exe | --ex)
+    ac_prev=exec_prefix ;;
+  -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \
+  | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \
+  | --exec=* | --exe=* | --ex=*)
+    exec_prefix="$ac_optarg" ;;
+
+  -gas | --gas | --ga | --g)
+    # Obsolete; use --with-gas.
+    with_gas=yes ;;
+
+  -help | --help | --hel | --he)
+    # Omit some internal or obsolete options to make the list less imposing.
+    # This message is too long to be a string in the A/UX 3.1 sh.
+    cat << EOF
+Usage: configure [options] [host]
+Options: [defaults in brackets after descriptions]
+Configuration:
+  --cache-file=FILE       cache test results in FILE
+  --help                  print this message
+  --no-create             do not create output files
+  --quiet, --silent       do not print \`checking...' messages
+  --version               print the version of autoconf that created configure
+Directory and file names:
+  --prefix=PREFIX         install architecture-independent files in PREFIX
+                          [$ac_default_prefix]
+  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
+                          [same as prefix]
+  --bindir=DIR            user executables in DIR [EPREFIX/bin]
+  --sbindir=DIR           system admin executables in DIR [EPREFIX/sbin]
+  --libexecdir=DIR        program executables in DIR [EPREFIX/libexec]
+  --datadir=DIR           read-only architecture-independent data in DIR
+                          [PREFIX/share]
+  --sysconfdir=DIR        read-only single-machine data in DIR [PREFIX/etc]
+  --sharedstatedir=DIR    modifiable architecture-independent data in DIR
+                          [PREFIX/com]
+  --localstatedir=DIR     modifiable single-machine data in DIR [PREFIX/var]
+  --libdir=DIR            object code libraries in DIR [EPREFIX/lib]
+  --includedir=DIR        C header files in DIR [PREFIX/include]
+  --oldincludedir=DIR     C header files for non-gcc in DIR [/usr/include]
+  --infodir=DIR           info documentation in DIR [PREFIX/info]
+  --mandir=DIR            man documentation in DIR [PREFIX/man]
+  --srcdir=DIR            find the sources in DIR [configure dir or ..]
+  --program-prefix=PREFIX prepend PREFIX to installed program names
+  --program-suffix=SUFFIX append SUFFIX to installed program names
+  --program-transform-name=PROGRAM
+                          run sed PROGRAM on installed program names
+EOF
+    cat << EOF
+Host type:
+  --build=BUILD           configure for building on BUILD [BUILD=HOST]
+  --host=HOST             configure for HOST [guessed]
+  --target=TARGET         configure for TARGET [TARGET=HOST]
+Features and packages:
+  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
+  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
+  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
+  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
+  --x-includes=DIR        X include files are in DIR
+  --x-libraries=DIR       X library files are in DIR
+EOF
+    if test -n "$ac_help"; then
+      echo "--enable and --with options recognized:$ac_help"
+    fi
+    exit 0 ;;
+
+  -host | --host | --hos | --ho)
+    ac_prev=host ;;
+  -host=* | --host=* | --hos=* | --ho=*)
+    host="$ac_optarg" ;;
+
+  -includedir | --includedir | --includedi | --included | --include \
+  | --includ | --inclu | --incl | --inc)
+    ac_prev=includedir ;;
+  -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \
+  | --includ=* | --inclu=* | --incl=* | --inc=*)
+    includedir="$ac_optarg" ;;
+
+  -infodir | --infodir | --infodi | --infod | --info | --inf)
+    ac_prev=infodir ;;
+  -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*)
+    infodir="$ac_optarg" ;;
+
+  -libdir | --libdir | --libdi | --libd)
+    ac_prev=libdir ;;
+  -libdir=* | --libdir=* | --libdi=* | --libd=*)
+    libdir="$ac_optarg" ;;
+
+  -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \
+  | --libexe | --libex | --libe)
+    ac_prev=libexecdir ;;
+  -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \
+  | --libexe=* | --libex=* | --libe=*)
+    libexecdir="$ac_optarg" ;;
+
+  -localstatedir | --localstatedir | --localstatedi | --localstated \
+  | --localstate | --localstat | --localsta | --localst \
+  | --locals | --local | --loca | --loc | --lo)
+    ac_prev=localstatedir ;;
+  -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \
+  | --localstate=* | --localstat=* | --localsta=* | --localst=* \
+  | --locals=* | --local=* | --loca=* | --loc=* | --lo=*)
+    localstatedir="$ac_optarg" ;;
+
+  -mandir | --mandir | --mandi | --mand | --man | --ma | --m)
+    ac_prev=mandir ;;
+  -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*)
+    mandir="$ac_optarg" ;;
+
+  -nfp | --nfp | --nf)
+    # Obsolete; use --without-fp.
+    with_fp=no ;;
+
+  -no-create | --no-create | --no-creat | --no-crea | --no-cre \
+  | --no-cr | --no-c)
+    no_create=yes ;;
+
+  -no-recursion | --no-recursion | --no-recursio | --no-recursi \
+  | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r)
+    no_recursion=yes ;;
+
+  -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \
+  | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \
+  | --oldin | --oldi | --old | --ol | --o)
+    ac_prev=oldincludedir ;;
+  -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \
+  | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \
+  | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*)
+    oldincludedir="$ac_optarg" ;;
+
+  -prefix | --prefix | --prefi | --pref | --pre | --pr | --p)
+    ac_prev=prefix ;;
+  -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*)
+    prefix="$ac_optarg" ;;
+
+  -program-prefix | --program-prefix | --program-prefi | --program-pref \
+  | --program-pre | --program-pr | --program-p)
+    ac_prev=program_prefix ;;
+  -program-prefix=* | --program-prefix=* | --program-prefi=* \
+  | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*)
+    program_prefix="$ac_optarg" ;;
+
+  -program-suffix | --program-suffix | --program-suffi | --program-suff \
+  | --program-suf | --program-su | --program-s)
+    ac_prev=program_suffix ;;
+  -program-suffix=* | --program-suffix=* | --program-suffi=* \
+  | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*)
+    program_suffix="$ac_optarg" ;;
+
+  -program-transform-name | --program-transform-name \
+  | --program-transform-nam | --program-transform-na \
+  | --program-transform-n | --program-transform- \
+  | --program-transform | --program-transfor \
+  | --program-transfo | --program-transf \
+  | --program-trans | --program-tran \
+  | --progr-tra | --program-tr | --program-t)
+    ac_prev=program_transform_name ;;
+  -program-transform-name=* | --program-transform-name=* \
+  | --program-transform-nam=* | --program-transform-na=* \
+  | --program-transform-n=* | --program-transform-=* \
+  | --program-transform=* | --program-transfor=* \
+  | --program-transfo=* | --program-transf=* \
+  | --program-trans=* | --program-tran=* \
+  | --progr-tra=* | --program-tr=* | --program-t=*)
+    program_transform_name="$ac_optarg" ;;
+
+  -q | -quiet | --quiet | --quie | --qui | --qu | --q \
+  | -silent | --silent | --silen | --sile | --sil)
+    silent=yes ;;
+
+  -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
+    ac_prev=sbindir ;;
+  -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
+  | --sbi=* | --sb=*)
+    sbindir="$ac_optarg" ;;
+
+  -sharedstatedir | --sharedstatedir | --sharedstatedi \
+  | --sharedstated | --sharedstate | --sharedstat | --sharedsta \
+  | --sharedst | --shareds | --shared | --share | --shar \
+  | --sha | --sh)
+    ac_prev=sharedstatedir ;;
+  -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \
+  | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \
+  | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \
+  | --sha=* | --sh=*)
+    sharedstatedir="$ac_optarg" ;;
+
+  -site | --site | --sit)
+    ac_prev=site ;;
+  -site=* | --site=* | --sit=*)
+    site="$ac_optarg" ;;
+
+  -srcdir | --srcdir | --srcdi | --srcd | --src | --sr)
+    ac_prev=srcdir ;;
+  -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*)
+    srcdir="$ac_optarg" ;;
+
+  -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \
+  | --syscon | --sysco | --sysc | --sys | --sy)
+    ac_prev=sysconfdir ;;
+  -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \
+  | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*)
+    sysconfdir="$ac_optarg" ;;
+
+  -target | --target | --targe | --targ | --tar | --ta | --t)
+    ac_prev=target ;;
+  -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*)
+    target="$ac_optarg" ;;
+
+  -v | -verbose | --verbose | --verbos | --verbo | --verb)
+    verbose=yes ;;
+
+  -version | --version | --versio | --versi | --vers)
+    echo "configure generated by autoconf version 2.12.2"
+    exit 0 ;;
+
+  -with-* | --with-*)
+    ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then
+      { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
+    fi
+    ac_package=`echo $ac_package| sed 's/-/_/g'`
+    case "$ac_option" in
+      *=*) ;;
+      *) ac_optarg=yes ;;
+    esac
+    eval "with_${ac_package}='$ac_optarg'" ;;
+
+  -without-* | --without-*)
+    ac_package=`echo $ac_option|sed -e 's/-*without-//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then
+      { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
+    fi
+    ac_package=`echo $ac_package| sed 's/-/_/g'`
+    eval "with_${ac_package}=no" ;;
+
+  --x)
+    # Obsolete; use --with-x.
+    with_x=yes ;;
+
+  -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \
+  | --x-incl | --x-inc | --x-in | --x-i)
+    ac_prev=x_includes ;;
+  -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \
+  | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*)
+    x_includes="$ac_optarg" ;;
+
+  -x-libraries | --x-libraries | --x-librarie | --x-librari \
+  | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l)
+    ac_prev=x_libraries ;;
+  -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \
+  | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*)
+    x_libraries="$ac_optarg" ;;
+
+  -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; }
+    ;;
+
+  *)
+    if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then
+      echo "configure: warning: $ac_option: invalid host type" 1>&2
+    fi
+    if test "x$nonopt" != xNONE; then
+      { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; }
+    fi
+    nonopt="$ac_option"
+    ;;
+
+  esac
+done
+
+if test -n "$ac_prev"; then
+  { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; }
+fi
+
+trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
+
+# File descriptor usage:
+# 0 standard input
+# 1 file creation
+# 2 errors and warnings
+# 3 some systems may open it to /dev/tty
+# 4 used on the Kubota Titan
+# 6 checking for... messages and results
+# 5 compiler messages saved in config.log
+if test "$silent" = yes; then
+  exec 6>/dev/null
+else
+  exec 6>&1
+fi
+exec 5>./config.log
+
+echo "\
+This file contains any messages produced by compilers while
+running configure, to aid debugging if configure makes a mistake.
+" 1>&5
+
+# Strip out --no-create and --no-recursion so they do not pile up.
+# Also quote any args containing shell metacharacters.
+ac_configure_args=
+for ac_arg
+do
+  case "$ac_arg" in
+  -no-create | --no-create | --no-creat | --no-crea | --no-cre \
+  | --no-cr | --no-c) ;;
+  -no-recursion | --no-recursion | --no-recursio | --no-recursi \
+  | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;;
+  *" "*|*"	"*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*)
+  ac_configure_args="$ac_configure_args '$ac_arg'" ;;
+  *) ac_configure_args="$ac_configure_args $ac_arg" ;;
+  esac
+done
+
+# NLS nuisances.
+# Only set these to C if already set.  These must not be set unconditionally
+# because not all systems understand e.g. LANG=C (notably SCO).
+# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'!
+# Non-C LC_CTYPE values break the ctype check.
+if test "${LANG+set}"   = set; then LANG=C;   export LANG;   fi
+if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi
+if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi
+if test "${LC_CTYPE+set}"    = set; then LC_CTYPE=C;    export LC_CTYPE;    fi
+
+# confdefs.h avoids OS command line length limits that DEFS can exceed.
+rm -rf conftest* confdefs.h
+# AIX cpp loses on an empty file, so make sure it contains at least a newline.
+echo > confdefs.h
+
+# A filename unique to this package, relative to the directory that
+# configure is in, which we can look for to find out if srcdir is correct.
+ac_unique_file=refcard.tex
+
+# Find the source files, if location was not specified.
+if test -z "$srcdir"; then
+  ac_srcdir_defaulted=yes
+  # Try the directory containing this script, then its parent.
+  ac_prog=$0
+  ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'`
+  test "x$ac_confdir" = "x$ac_prog" && ac_confdir=.
+  srcdir=$ac_confdir
+  if test ! -r $srcdir/$ac_unique_file; then
+    srcdir=..
+  fi
+else
+  ac_srcdir_defaulted=no
+fi
+if test ! -r $srcdir/$ac_unique_file; then
+  if test "$ac_srcdir_defaulted" = yes; then
+    { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; }
+  else
+    { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; }
+  fi
+fi
+srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'`
+
+# Prefer explicitly selected file to automatically selected ones.
+if test -z "$CONFIG_SITE"; then
+  if test "x$prefix" != xNONE; then
+    CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site"
+  else
+    CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site"
+  fi
+fi
+for ac_site_file in $CONFIG_SITE; do
+  if test -r "$ac_site_file"; then
+    echo "loading site script $ac_site_file"
+    . "$ac_site_file"
+  fi
+done
+
+if test -r "$cache_file"; then
+  echo "loading cache $cache_file"
+  . $cache_file
+else
+  echo "creating cache $cache_file"
+  > $cache_file
+fi
+
+ac_ext=c
+# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options.
+ac_cpp='$CPP $CPPFLAGS'
+ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5'
+ac_link='${CC-cc} -o conftest${ac_exeext} $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5'
+cross_compiling=$ac_cv_prog_cc_cross
+
+ac_exeext=
+ac_objext=o
+if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then
+  # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu.
+  if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then
+    ac_n= ac_c='
+' ac_t='	'
+  else
+    ac_n=-n ac_c= ac_t=
+  fi
+else
+  ac_n= ac_c='\c' ac_t=
+fi
+
+
+ac_aux_dir=
+for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do
+  if test -f $ac_dir/install-sh; then
+    ac_aux_dir=$ac_dir
+    ac_install_sh="$ac_aux_dir/install-sh -c"
+    break
+  elif test -f $ac_dir/install.sh; then
+    ac_aux_dir=$ac_dir
+    ac_install_sh="$ac_aux_dir/install.sh -c"
+    break
+  fi
+done
+if test -z "$ac_aux_dir"; then
+  { echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; }
+fi
+ac_config_guess=$ac_aux_dir/config.guess
+ac_config_sub=$ac_aux_dir/config.sub
+ac_configure=$ac_aux_dir/configure # This should be Cygnus configure.
+
+# Find a good install program.  We prefer a C program (faster),
+# so one script is as good as another.  But avoid the broken or
+# incompatible versions:
+# SysV /etc/install, /usr/sbin/install
+# SunOS /usr/etc/install
+# IRIX /sbin/install
+# AIX /bin/install
+# AIX 4 /usr/bin/installbsd, which doesn't work without a -g flag
+# AFS /usr/afsws/bin/install, which mishandles nonexistent args
+# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff"
+# ./install, which can be erroneously created by make from ./install.sh.
+echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6
+echo "configure:556: checking for a BSD compatible install" >&5
+if test -z "$INSTALL"; then
+if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then
+  echo $ac_n "(cached) $ac_c" 1>&6
+else
+    IFS="${IFS= 	}"; ac_save_IFS="$IFS"; IFS=":"
+  for ac_dir in $PATH; do
+    # Account for people who put trailing slashes in PATH elements.
+    case "$ac_dir/" in
+    /|./|.//|/etc/*|/usr/sbin/*|/usr/etc/*|/sbin/*|/usr/afsws/bin/*|/usr/ucb/*) ;;
+    *)
+      # OSF1 and SCO ODT 3.0 have their own names for install.
+      # Don't use installbsd from OSF since it installs stuff as root
+      # by default.
+      for ac_prog in ginstall scoinst install; do
+        if test -f $ac_dir/$ac_prog; then
+	  if test $ac_prog = install &&
+            grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then
+	    # AIX install.  It has an incompatible calling convention.
+	    :
+	  else
+	    ac_cv_path_install="$ac_dir/$ac_prog -c"
+	    break 2
+	  fi
+	fi
+      done
+      ;;
+    esac
+  done
+  IFS="$ac_save_IFS"
+
+fi
+  if test "${ac_cv_path_install+set}" = set; then
+    INSTALL="$ac_cv_path_install"
+  else
+    # As a last resort, use the slow shell script.  We don't cache a
+    # path for INSTALL within a source directory, because that will
+    # break other packages using the cache if that directory is
+    # removed, or if the path is relative.
+    INSTALL="$ac_install_sh"
+  fi
+fi
+echo "$ac_t""$INSTALL" 1>&6
+
+# Use test -z because SunOS4 sh mishandles braces in ${var-val}.
+# It thinks the first close brace ends the variable substitution.
+test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}'
+
+test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644'
+
+trap '' 1 2 15
+cat > confcache <<\EOF
+# This file is a shell script that caches the results of configure
+# tests run on this system so they can be shared between configure
+# scripts and configure runs.  It is not useful on other systems.
+# If it contains results you don't want to keep, you may remove or edit it.
+#
+# By default, configure uses ./config.cache as the cache file,
+# creating it if it does not exist already.  You can give configure
+# the --cache-file=FILE option to use a different cache file; that is
+# what configure does when it calls configure scripts in
+# subdirectories, so they share the cache.
+# Giving --cache-file=/dev/null disables caching, for debugging configure.
+# config.status only pays attention to the cache file if you give it the
+# --recheck option to rerun configure.
+#
+EOF
+# The following way of writing the cache mishandles newlines in values,
+# but we know of no workaround that is simple, portable, and efficient.
+# So, don't put newlines in cache variables' values.
+# Ultrix sh set writes to stderr and can't be redirected directly,
+# and sets the high bit in the cache file unless we assign to the vars.
+(set) 2>&1 |
+  case `(ac_space=' '; set) 2>&1 | grep ac_space` in
+  *ac_space=\ *)
+    # `set' does not quote correctly, so add quotes (double-quote substitution
+    # turns \\\\ into \\, and sed turns \\ into \).
+    sed -n \
+      -e "s/'/'\\\\''/g" \
+      -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p"
+    ;;
+  *)
+    # `set' quotes correctly as required by POSIX, so do not add quotes.
+    sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p'
+    ;;
+  esac >> confcache
+if cmp -s $cache_file confcache; then
+  :
+else
+  if test -w $cache_file; then
+    echo "updating cache $cache_file"
+    cat confcache > $cache_file
+  else
+    echo "not updating unwritable cache $cache_file"
+  fi
+fi
+rm -f confcache
+
+trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
+
+test "x$prefix" = xNONE && prefix=$ac_default_prefix
+# Let make expand exec_prefix.
+test "x$exec_prefix" = xNONE && exec_prefix='${prefix}'
+
+# Any assignment to VPATH causes Sun make to only execute
+# the first set of double-colon rules, so remove it if not needed.
+# If there is a colon in the path, we need to keep it.
+if test "x$srcdir" = x.; then
+  ac_vpsub='/^[ 	]*VPATH[ 	]*=[^:]*$/d'
+fi
+
+trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15
+
+# Transform confdefs.h into DEFS.
+# Protect against shell expansion while executing Makefile rules.
+# Protect against Makefile macro expansion.
+cat > conftest.defs <<\EOF
+s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g
+s%[ 	`~#$^&*(){}\\|;'"<>?]%\\&%g
+s%\[%\\&%g
+s%\]%\\&%g
+s%\$%$$%g
+EOF
+DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '`
+rm -f conftest.defs
+
+
+# Without the "./", some shells look in PATH for config.status.
+: ${CONFIG_STATUS=./config.status}
+
+echo creating $CONFIG_STATUS
+rm -f $CONFIG_STATUS
+cat > $CONFIG_STATUS <<EOF
+#! /bin/sh
+# Generated automatically by configure.
+# Run this file to recreate the current configuration.
+# This directory was configured as follows,
+# on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
+#
+# $0 $ac_configure_args
+#
+# Compiler output produced by configure, useful for debugging
+# configure, is in ./config.log if it exists.
+
+ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]"
+for ac_option
+do
+  case "\$ac_option" in
+  -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r)
+    echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion"
+    exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;;
+  -version | --version | --versio | --versi | --vers | --ver | --ve | --v)
+    echo "$CONFIG_STATUS generated by autoconf version 2.12.2"
+    exit 0 ;;
+  -help | --help | --hel | --he | --h)
+    echo "\$ac_cs_usage"; exit 0 ;;
+  *) echo "\$ac_cs_usage"; exit 1 ;;
+  esac
+done
+
+ac_given_srcdir=$srcdir
+ac_given_INSTALL="$INSTALL"
+
+trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15
+EOF
+cat >> $CONFIG_STATUS <<EOF
+
+# Protect against being on the right side of a sed subst in config.status.
+sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g;
+ s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF
+$ac_vpsub
+$extrasub
+s%@SHELL@%$SHELL%g
+s%@CFLAGS@%$CFLAGS%g
+s%@CPPFLAGS@%$CPPFLAGS%g
+s%@CXXFLAGS@%$CXXFLAGS%g
+s%@DEFS@%$DEFS%g
+s%@LDFLAGS@%$LDFLAGS%g
+s%@LIBS@%$LIBS%g
+s%@exec_prefix@%$exec_prefix%g
+s%@prefix@%$prefix%g
+s%@program_transform_name@%$program_transform_name%g
+s%@bindir@%$bindir%g
+s%@sbindir@%$sbindir%g
+s%@libexecdir@%$libexecdir%g
+s%@datadir@%$datadir%g
+s%@sysconfdir@%$sysconfdir%g
+s%@sharedstatedir@%$sharedstatedir%g
+s%@localstatedir@%$localstatedir%g
+s%@libdir@%$libdir%g
+s%@includedir@%$includedir%g
+s%@oldincludedir@%$oldincludedir%g
+s%@infodir@%$infodir%g
+s%@mandir@%$mandir%g
+s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g
+s%@INSTALL_DATA@%$INSTALL_DATA%g
+
+CEOF
+EOF
+
+cat >> $CONFIG_STATUS <<\EOF
+
+# Split the substitutions into bite-sized pieces for seds with
+# small command number limits, like on Digital OSF/1 and HP-UX.
+ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script.
+ac_file=1 # Number of current file.
+ac_beg=1 # First line for current file.
+ac_end=$ac_max_sed_cmds # Line after last line for current file.
+ac_more_lines=:
+ac_sed_cmds=""
+while $ac_more_lines; do
+  if test $ac_beg -gt 1; then
+    sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file
+  else
+    sed "${ac_end}q" conftest.subs > conftest.s$ac_file
+  fi
+  if test ! -s conftest.s$ac_file; then
+    ac_more_lines=false
+    rm -f conftest.s$ac_file
+  else
+    if test -z "$ac_sed_cmds"; then
+      ac_sed_cmds="sed -f conftest.s$ac_file"
+    else
+      ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file"
+    fi
+    ac_file=`expr $ac_file + 1`
+    ac_beg=$ac_end
+    ac_end=`expr $ac_end + $ac_max_sed_cmds`
+  fi
+done
+if test -z "$ac_sed_cmds"; then
+  ac_sed_cmds=cat
+fi
+EOF
+
+cat >> $CONFIG_STATUS <<EOF
+
+CONFIG_FILES=\${CONFIG_FILES-"Makefile"}
+EOF
+cat >> $CONFIG_STATUS <<\EOF
+for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then
+  # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in".
+  case "$ac_file" in
+  *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'`
+       ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;;
+  *) ac_file_in="${ac_file}.in" ;;
+  esac
+
+  # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories.
+
+  # Remove last slash and all that follows it.  Not all systems have dirname.
+  ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'`
+  if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then
+    # The file is in a subdirectory.
+    test ! -d "$ac_dir" && mkdir "$ac_dir"
+    ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`"
+    # A "../" for each directory in $ac_dir_suffix.
+    ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'`
+  else
+    ac_dir_suffix= ac_dots=
+  fi
+
+  case "$ac_given_srcdir" in
+  .)  srcdir=.
+      if test -z "$ac_dots"; then top_srcdir=.
+      else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;;
+  /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;;
+  *) # Relative path.
+    srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix"
+    top_srcdir="$ac_dots$ac_given_srcdir" ;;
+  esac
+
+  case "$ac_given_INSTALL" in
+  [/$]*) INSTALL="$ac_given_INSTALL" ;;
+  *) INSTALL="$ac_dots$ac_given_INSTALL" ;;
+  esac
+
+  echo creating "$ac_file"
+  rm -f "$ac_file"
+  configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure."
+  case "$ac_file" in
+  *Makefile*) ac_comsub="1i\\
+# $configure_input" ;;
+  *) ac_comsub= ;;
+  esac
+
+  ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"`
+  sed -e "$ac_comsub
+s%@configure_input@%$configure_input%g
+s%@srcdir@%$srcdir%g
+s%@top_srcdir@%$top_srcdir%g
+s%@INSTALL@%$INSTALL%g
+" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file
+fi; done
+rm -f conftest.s*
+
+EOF
+cat >> $CONFIG_STATUS <<EOF
+
+EOF
+cat >> $CONFIG_STATUS <<\EOF
+
+exit 0
+EOF
+chmod +x $CONFIG_STATUS
+rm -fr confdefs* $ac_clean_files
+test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1
+
diff --git a/gdb/doc/configure.in b/gdb/doc/configure.in
new file mode 100644
index 0000000000..460efc2b46
--- /dev/null
+++ b/gdb/doc/configure.in
@@ -0,0 +1,4 @@
+AC_PREREQ(2.12.1)
+AC_INIT(refcard.tex)
+AC_PROG_INSTALL
+AC_OUTPUT(Makefile)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
new file mode 100644
index 0000000000..fc920bb0c5
--- /dev/null
+++ b/gdb/doc/gdb.texinfo
@@ -0,0 +1,10316 @@
+\input texinfo      @c -*-texinfo-*-
+@c Copyright 1988-1999
+@c Free Software Foundation, Inc.
+@c
+@c %**start of header 
+@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
+@c of @set vars.  However, you can override filename with makeinfo -o.
+@setfilename gdb.info
+@c
+@include gdb-cfg.texi
+@c
+@ifset GENERIC
+@settitle Debugging with @value{GDBN}
+@end ifset
+@ifclear GENERIC
+@settitle Debugging with @value{GDBN} (@value{TARGET})
+@end ifclear
+@setchapternewpage odd
+@c %**end of header
+
+@iftex
+@c @smallbook
+@c @cropmarks
+@end iftex
+
+@finalout
+@syncodeindex ky cp
+
+@c readline appendices use @vindex
+@syncodeindex vr cp
+
+@c !!set GDB manual's edition---not the same as GDB version!
+@set EDITION Seventh
+
+@c !!set GDB manual's revision date
+@set DATE February 1999
+
+@c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly.
+
+@ifinfo
+@c This is a dir.info fragment to support semi-automated addition of
+@c manuals to an info tree.  zoo@cygnus.com is developing this facility.
+@format
+START-INFO-DIR-ENTRY
+* Gdb: (gdb).                     The @sc{gnu} debugger.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+@c
+@c
+@ifinfo
+This file documents the @sc{gnu} debugger @value{GDBN}.
+
+
+This is the @value{EDITION} Edition, @value{DATE}, 
+of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
+for @value{GDBN} Version @value{GDBVN}.
+
+Copyright (C) 1988-1999 Free Software Foundation, Inc.
+
+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.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+
+@titlepage
+@title Debugging with @value{GDBN}
+@subtitle The @sc{gnu} Source-Level Debugger
+@ifclear GENERIC
+@subtitle (@value{TARGET})
+@end ifclear
+@sp 1
+@ifclear HPPA
+@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
+@subtitle @value{DATE}
+@author Richard M. Stallman and Roland H. Pesch
+@end ifclear
+@ifset HPPA
+@subtitle Edition @value{EDITION}, for @value{HPVER} (based on @value{GDBN} @value{GDBVN})
+@subtitle @value{DATE}
+@author Richard M. Stallman and Roland H. Pesch (modified by HP)
+@end ifset
+@page
+@ifclear HPPA
+@tex
+{\parskip=0pt
+\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@prep.ai.mit.edu.)\par
+\hfill {\it Debugging with @value{GDBN}}\par
+\hfill \TeX{}info \texinfoversion\par
+}
+@end tex
+@end ifclear
+@ifset HPPA
+@tex
+{\parskip=0pt
+\hfill {\it Debugging with @value{GDBN}}\par
+\hfill \TeX{}info \texinfoversion\par
+}
+@end tex
+@end ifset
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1988-1999 Free Software Foundation, Inc. 
+@sp 2
+@ifclear HPPA
+Published by the Free Software Foundation @*
+59 Temple Place - Suite 330, @*
+Boston, MA 02111-1307 USA @*
+Printed copies are available for $20 each. @*
+ISBN 1-882114-11-6 @*
+@end ifclear
+                
+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.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+@page
+
+@ifinfo
+@node Top, Summary, (dir), (dir)
+@top Debugging with @value{GDBN}
+
+This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
+
+This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version 
+@value{GDBVN}.
+
+Copyright (C) 1988-1999 Free Software Foundation, Inc.
+@menu
+* Summary::                     Summary of @value{GDBN}
+@ifclear BARETARGET
+* Sample Session::              A sample @value{GDBN} session
+@end ifclear
+
+* Invocation::                  Getting in and out of @value{GDBN}
+* Commands::                    @value{GDBN} commands
+* Running::                     Running programs under @value{GDBN}
+* Stopping::                    Stopping and continuing
+* Stack::                       Examining the stack
+* Source::                      Examining source files
+* Data::                        Examining data
+@ifclear CONLY
+* Languages::                   Using @value{GDBN} with different languages
+@end ifclear
+
+@ifset CONLY
+* C::                           C language support
+@end ifset
+
+* Symbols::                     Examining the symbol table
+* Altering::                    Altering execution
+* GDB Files::                   @value{GDBN} files
+* Targets::                     Specifying a debugging target
+* Controlling GDB::             Controlling @value{GDBN}
+* Sequences::                   Canned sequences of commands
+@ifclear DOSHOST
+* Emacs::                       Using @value{GDBN} under @sc{gnu} Emacs
+@end ifclear
+
+* GDB Bugs::                    Reporting bugs in @value{GDBN}
+
+@ifclear PRECONFIGURED
+@ifclear HPPA
+* Formatting Documentation::    How to format and print @value{GDBN} documentation
+@end ifclear
+
+@end ifclear
+
+* Command Line Editing::        Command Line Editing
+* Using History Interactively:: Using History Interactively
+* Installing GDB::              Installing GDB
+* Index::                       Index
+
+ --- The Detailed Node Listing ---
+
+Summary of @value{GDBN}
+
+* Free Software::               Freely redistributable software
+* Contributors::                Contributors to GDB
+
+Getting In and Out of @value{GDBN}
+
+* Invoking GDB::                How to start @value{GDBN}
+* Quitting GDB::                How to quit @value{GDBN}
+* Shell Commands::              How to use shell commands inside @value{GDBN}
+
+Invoking @value{GDBN}
+
+* File Options::                Choosing files
+* Mode Options::                Choosing modes
+
+@value{GDBN} Commands
+
+* Command Syntax::              How to give commands to @value{GDBN}
+* Completion::                  Command completion
+* Help::                        How to ask @value{GDBN} for help
+
+Running Programs Under @value{GDBN}
+
+* Compilation::                 Compiling for debugging
+* Starting::                    Starting your program
+@ifclear BARETARGET
+* Arguments::                   Your program's arguments
+* Environment::                 Your program's environment
+@end ifclear
+
+* Working Directory::           Your program's working directory
+* Input/Output::                Your program's input and output
+* Attach::                      Debugging an already-running process
+* Kill Process::                Killing the child process
+@ifclear HPPA
+* Process Information::         Additional process information
+@end ifclear
+
+* Threads::                     Debugging programs with multiple threads
+* Processes::                   Debugging programs with multiple processes
+
+Stopping and Continuing
+
+* Breakpoints::                 Breakpoints, watchpoints, and catchpoints
+* Continuing and Stepping::     Resuming execution
+@ifset POSIX
+* Signals::                     Signals
+@end ifset
+@ifclear BARETARGET
+* Thread Stops::                Stopping and starting multi-thread programs
+@end ifclear
+
+Breakpoints and watchpoints
+
+* Set Breaks::                  Setting breakpoints
+* Set Watchpoints::             Setting watchpoints
+* Set Catchpoints::             Setting catchpoints
+* Delete Breaks::               Deleting breakpoints
+* Disabling::                   Disabling breakpoints
+* Conditions::                  Break conditions
+* Break Commands::              Breakpoint command lists
+@ifclear CONLY
+* Breakpoint Menus::            Breakpoint menus
+@end ifclear
+
+Examining the Stack
+
+* Frames::                      Stack frames
+* Backtrace::                   Backtraces
+* Selection::                   Selecting a frame
+* Frame Info::                  Information on a frame
+* Alpha/MIPS Stack::            Alpha and MIPS machines and the function stack
+
+Examining Source Files
+
+* List::                        Printing source lines
+@ifclear DOSHOST
+* Search::                      Searching source files
+@end ifclear
+* Source Path::                 Specifying source directories
+* Machine Code::                Source and machine code
+
+Examining Data
+
+* Expressions::                 Expressions
+* Variables::                   Program variables
+* Arrays::                      Artificial arrays
+* Output Formats::              Output formats
+* Memory::                      Examining memory
+* Auto Display::                Automatic display
+* Print Settings::              Print settings
+* Value History::               Value history
+* Convenience Vars::            Convenience variables
+* Registers::                   Registers
+@ifclear HAVE-FLOAT
+* Floating Point Hardware::     Floating point hardware
+@end ifclear
+
+Using @value{GDBN} with Different Languages
+
+* Setting::                     Switching between source languages
+* Show::                        Displaying the language
+@ifset MOD2
+* Checks::                      Type and range checks
+@end ifset
+
+* Support::                     Supported languages
+
+Switching between source languages
+
+* Filenames::                   Filename extensions and languages.
+* Manually::                    Setting the working language manually
+* Automatically::               Having @value{GDBN} infer the source language
+
+@ifset MOD2
+Type and range checking
+
+* Type Checking::               An overview of type checking
+* Range Checking::              An overview of range checking
+@end ifset
+
+Supported languages
+
+@ifset MOD2
+* C::                           C and C++
+
+C Language Support
+
+* C Operators::                 C operators
+
+C Language Support
+@end ifset
+
+* C Operators::                 C and C++ operators
+* C Constants::                 C and C++ constants
+* Cplus expressions::           C++ expressions
+* C Defaults::                  Default settings for C and C++
+@ifset MOD2
+* C Checks::                    C and C++ type and range checks
+@end ifset
+* Debugging C::                 @value{GDBN} and C
+* Debugging C plus plus::       @value{GDBN} features for C++
+
+@ifset MOD2
+Modula-2
+
+* M2 Operators::                Built-in operators
+* Built-In Func/Proc::          Built-in functions and procedures
+* M2 Constants::                Modula-2 constants
+* M2 Defaults::                 Default settings for Modula-2
+* Deviations::                  Deviations from standard Modula-2
+* M2 Checks::                   Modula-2 type and range checks
+* M2 Scope::                    The scope operators @code{::} and @code{.}
+* GDB/M2::                      @value{GDBN} and Modula-2
+@end ifset
+
+Altering Execution
+
+* Assignment::                  Assignment to variables
+* Jumping::                     Continuing at a different address
+@ifclear BARETARGET
+* Signaling::                   Giving your program a signal
+@end ifclear
+* Returning::                   Returning from a function
+* Calling::                     Calling your program's functions
+* Patching::                    Patching your program
+
+@value{GDBN} Files
+
+* Files::                       Commands to specify files
+* Symbol Errors::               Errors reading symbol files
+
+Specifying a Debugging Target
+
+* Active Targets::              Active targets
+* Target Commands::             Commands for managing targets
+@ifclear HPPA
+* Byte Order::                  Choosing target byte order
+* Remote::                      Remote debugging
+
+Remote debugging
+@end ifclear
+
+@ifset REMOTESTUB
+* Remote Serial::               @value{GDBN} remote serial protocol
+@end ifset
+
+@ifset I960
+* i960-Nindy Remote::		@value{GDBN} with a remote i960 (Nindy)
+@end ifset
+
+@ifset AMD29K
+* UDI29K Remote::               The UDI protocol for AMD29K
+* EB29K Remote::		The EBMON protocol for AMD29K
+@end ifset
+
+@ifset VXWORKS
+* VxWorks Remote::		@value{GDBN} and VxWorks
+@end ifset
+
+@ifset ST2000
+* ST2000 Remote::               @value{GDBN} with a Tandem ST2000
+@end ifset
+
+@ifset H8
+* Hitachi Remote::              @value{GDBN} and Hitachi Microprocessors
+@end ifset
+
+@ifset MIPS
+* MIPS Remote::			@value{GDBN} and MIPS boards
+@end ifset
+
+@ifset SIMS
+* Simulator::                   Simulated CPU target
+@end ifset
+
+Controlling @value{GDBN}
+
+* Prompt::                      Prompt
+* Editing::                     Command editing
+* History::                     Command history
+* Screen Size::                 Screen size
+* Numbers::                     Numbers
+* Messages/Warnings::           Optional warnings and messages
+
+Canned Sequences of Commands
+
+* Define::                      User-defined commands
+* Hooks::                       User-defined command hooks
+* Command Files::               Command files
+* Output::                      Commands for controlled output
+
+Reporting Bugs in @value{GDBN}
+
+* Bug Criteria::                Have you found a bug?
+* Bug Reporting::               How to report bugs
+
+Installing @value{GDBN}
+
+* Separate Objdir::             Compiling @value{GDBN} in another directory
+* Config Names::                Specifying names for hosts and targets
+* Configure Options::           Summary of options for configure
+@end menu
+
+@end ifinfo
+
+@node Summary, Sample Session, Top, Top
+@unnumbered Summary of @value{GDBN}
+
+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
+
+@ifclear CONLY
+You can use @value{GDBN} to debug programs written in C or C++.
+@c "MOD2" used as a "miscellaneous languages" flag here.
+@c This is acceptable while there is no real doc for Chill and Pascal.
+@ifclear MOD2
+For more information, see @ref{Support,,Supported languages}.
+@end ifclear
+@ifset MOD2
+For more information, see @ref{C,,C and C++}.
+
+Support for Modula-2 and Chill is partial.  For information on Modula-2,
+see @ref{Modula-2,,Modula-2}.  There is no further documentation on Chill yet.
+
+Debugging Pascal programs which use sets, subranges, file variables, or nested
+functions does not currently work.  @value{GDBN} does not support
+entering expressions, printing values, or similar features using Pascal syntax.
+@end ifset
+
+@ifset FORTRAN
+@cindex Fortran
+@value{GDBN} can be used to debug programs written in Fortran, although
+it does not yet support entering expressions, printing values, or
+similar features using Fortran syntax.  It may be necessary to refer to
+some variables with a trailing underscore.
+@end ifset
+@end ifclear
+
+@ifset HPPA
+This version of the manual documents HP Wildebeest (WDB) Version 0.75,
+implemented on HP 9000 systems running Release 10.20, 10.30, or 11.0 of
+the HP-UX operating system.  HP WDB 0.75 can be used to debug code
+generated by the HP ANSI C and HP ANSI C++ compilers as well as the
+@sc{gnu} C and C++ compilers.  It does not support the debugging of
+Fortran, Modula-2, or Chill programs.
+@end ifset
+
+@menu
+* Free Software::               Freely redistributable software
+* Contributors::                Contributors to GDB
+@end menu
+
+@node Free Software, Contributors, Summary, Summary
+@unnumberedsec Free software
+
+@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} 
+General Public License
+(GPL).  The GPL gives you the freedom to copy or adapt a licensed
+program---but every person getting a copy also gets with it the
+freedom to modify that copy (which means that they must get access to
+the source code), and the freedom to distribute further copies.
+Typical software companies use copyrights to limit your freedoms; the
+Free Software Foundation uses the GPL to preserve these freedoms.
+
+Fundamentally, the General Public License is a license which says that
+you have these freedoms and that you cannot take these freedoms away
+from anyone else.
+
+@node Contributors,  , Free Software, Summary
+@unnumberedsec Contributors to GDB
+
+Richard Stallman was the original author of GDB, and of many other
+@sc{gnu} programs.  Many others have contributed to its development.
+This section attempts to credit major contributors.  One of the virtues
+of free software is that everyone is free to contribute to it; with
+regret, we cannot actually acknowledge everyone here.  The file
+@file{ChangeLog} in the @value{GDBN} distribution approximates a
+blow-by-blow account.
+
+Changes much prior to version 2.0 are lost in the mists of time.
+
+@quotation
+@emph{Plea:} Additions to this section are particularly welcome.  If you
+or your friends (or enemies, to be evenhanded) have been unfairly
+omitted from this list, we would like to add your names!
+@end quotation
+
+So that they may not regard their many labors as thankless, we
+particularly thank those who shepherded @value{GDBN} through major
+releases:
+Jim Blandy (release 4.18);
+Jason Molenda (release 4.17);
+Stan Shebs (release 4.14);
+Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
+Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
+John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
+Jim Kingdon (releases 3.5, 3.4, and 3.3);
+and Randy Smith (releases 3.2, 3.1, and 3.0).
+
+Richard Stallman, assisted at various times by Peter TerMaat, Chris
+Hanson, and Richard Mlynarik, handled releases through 2.8.
+
+@ifclear CONLY
+Michael Tiemann is the author of most of the @sc{gnu} C++ support in GDB,
+with significant additional contributions from Per Bothner.  James
+Clark wrote the @sc{gnu} C++ demangler.  Early work on C++ was by Peter
+TerMaat (who also did much general update work leading to release 3.0).
+@end ifclear
+
+@value{GDBN} 4 uses the BFD subroutine library to examine multiple
+object-file formats; BFD was a joint project of David V.
+Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
+
+David Johnson wrote the original COFF support; Pace Willison did
+the original support for encapsulated COFF.
+
+Brent Benson of Harris Computer Systems contributed DWARF 2 support.
+
+Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
+Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
+support.
+Jean-Daniel Fekete contributed Sun 386i support.
+Chris Hanson improved the HP9000 support.
+Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
+David Johnson contributed Encore Umax support.
+Jyrki Kuoppala contributed Altos 3068 support.
+Jeff Law contributed HP PA and SOM support.
+Keith Packard contributed NS32K support.
+Doug Rabson contributed Acorn Risc Machine support.
+Bob Rusk contributed Harris Nighthawk CX-UX support.
+Chris Smith contributed Convex support (and Fortran debugging).
+Jonathan Stone contributed Pyramid support.
+Michael Tiemann contributed SPARC support.
+Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
+Pace Willison contributed Intel 386 support.
+Jay Vosburgh contributed Symmetry support.
+
+Andreas Schwab contributed M68K Linux support.
+
+Rich Schaefer and Peter Schauer helped with support of SunOS shared
+libraries.
+
+Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
+about several machine instruction sets.
+
+Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
+remote debugging.  Intel Corporation, Wind River Systems, AMD, and ARM
+contributed remote debugging modules for the i960, VxWorks, A29K UDI,
+and RDI targets, respectively.
+
+Brian Fox is the author of the readline libraries providing
+command-line editing and command history.
+
+Andrew Beers of SUNY Buffalo wrote the language-switching code,
+@ifset MOD2
+the Modula-2 support,
+@end ifset
+and contributed the Languages chapter of this manual.
+
+Fred Fish wrote most of the support for Unix System Vr4.  
+@ifclear CONLY
+He also enhanced the command-completion support to cover C++ overloaded
+symbols.
+@end ifclear
+
+Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and
+Super-H processors.
+
+NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
+
+Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors.
+
+Toshiba sponsored the support for the TX39 Mips processor.
+
+Matsushita sponsored the support for the MN10200 and MN10300 processors.
+
+Fujitsu sponsored the support for SPARClite and FR30 processors
+
+Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
+watchpoints.
+
+Michael Snyder added support for tracepoints.
+
+Stu Grossman wrote gdbserver.
+
+Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
+nearly innumerable bug fixes and cleanups throughout GDB.
+
+The following people at the Hewlett-Packard Company contributed
+support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
+(narrow mode), HP's implementation of kernel threads, HP's aC++
+compiler, and the terminal user interface: Ben Krepp, Richard Title,
+John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve
+Rehrauer, and Elena Zannoni.  Kim Haase provided HP-specific
+information in this manual.
+
+Cygnus Solutions has sponsored GDB maintenance and much of its
+development since 1991.  Cygnus engineers who have worked on GDB
+fulltime include Mark Alexander, Jim Blandy, Per Bothner, Edith Epstein,
+Chris Faylor, Fred Fish, Martin Hunt, Jim Ingham, John Gilmore, Stu
+Grossman, Kung Hsu, Jim Kingdon, John Metzler, Fernando Nasser, Geoffrey
+Noer, Dawn Perchik, Rich Pixley, Zdenek Radouch, Keith Seitz, Stan
+Shebs, David Taylor, and Elena Zannoni.  In addition, Dave Brolley, Ian
+Carmichael, Steve Chamberlain, Nick Clifton, JT Conklin, Stan Cox, DJ
+Delorie, Ulrich Drepper, Frank Eigler, Doug Evans, Sean Fagan, David
+Henkel-Wallace, Richard Henderson, Jeff Holcomb, Jeff Law, Jim Lemke,
+Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, Catherine Moore,
+Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith,
+Mike Stump, Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron
+Unrau, Jim Wilson, and David Zuhn have made contributions both large
+and small.
+
+
+@ifclear BARETARGET
+@node Sample Session, Invocation, Summary, Top
+@chapter A Sample @value{GDBN} Session
+
+You can use this manual at your leisure to read all about @value{GDBN}.
+However, a handful of commands are enough to get started using the
+debugger.  This chapter illustrates those commands.
+
+@iftex
+In this sample session, we emphasize user input like this: @b{input},
+to make it easier to pick out from the surrounding output.
+@end iftex
+
+@c FIXME: this example may not be appropriate for some configs, where
+@c FIXME...primary interest is in remote use.
+
+One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
+processor) exhibits the following bug: sometimes, when we change its
+quote strings from the default, the commands used to capture one macro
+definition within another stop working.  In the following short @code{m4}
+session, we define a macro @code{foo} which expands to @code{0000}; we
+then use the @code{m4} built-in @code{defn} to define @code{bar} as the
+same thing.  However, when we change the open quote string to
+@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
+procedure fails to define a new synonym @code{baz}:
+
+@smallexample
+$ @b{cd gnu/m4}
+$ @b{./m4}
+@b{define(foo,0000)}
+
+@b{foo}
+0000
+@b{define(bar,defn(`foo'))}
+
+@b{bar}
+0000
+@b{changequote(<QUOTE>,<UNQUOTE>)}
+
+@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
+@b{baz}
+@b{C-d}
+m4: End of input: 0: fatal error: EOF in string
+@end smallexample
+
+@noindent
+Let us use @value{GDBN} to try to see what is going on.
+
+@ifclear HPPA
+@smallexample
+$ @b{@value{GDBP} m4}
+@c FIXME: this falsifies the exact text played out, to permit smallbook
+@c FIXME... format to come out better.
+@value{GDBN} is free software and you are welcome to distribute copies
+ of it under certain conditions; type "show copying" to see 
+ the conditions.
+There is absolutely no warranty for @value{GDBN}; type "show warranty" 
+ for details.
+
+@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
+(@value{GDBP})
+@end smallexample
+@end ifclear
+@ifset HPPA
+@smallexample
+$ @b{@value{GDBP} m4}
+Wildebeest is free software and you are welcome to distribute copies of
+it under certain conditions; type "show copying" to see the conditions.
+There is absolutely no warranty for Wildebeest; type "show warranty"
+for details.
+
+Hewlett-Packard Wildebeest 0.75 (based on GDB 4.16)
+(built for PA-RISC 1.1 or 2.0, HP-UX 10.20)
+Copyright 1996, 1997 Free Software Foundation, Inc.
+(@value{GDBP})
+@end smallexample
+@end ifset
+
+@noindent
+@value{GDBN} reads only enough symbol data to know where to find the
+rest when needed; as a result, the first prompt comes up very quickly.
+We now tell @value{GDBN} to use a narrower display width than usual, so
+that examples fit in this manual.
+
+@smallexample
+(@value{GDBP}) @b{set width 70}
+@end smallexample
+
+@noindent
+We need to see how the @code{m4} built-in @code{changequote} works.
+Having looked at the source, we know the relevant subroutine is
+@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}
+@code{break} command.
+
+@smallexample
+(@value{GDBP}) @b{break m4_changequote}
+Breakpoint 1 at 0x62f4: file builtin.c, line 879.
+@end smallexample
+
+@noindent
+Using the @code{run} command, we start @code{m4} running under @value{GDBN}
+control; as long as control does not reach the @code{m4_changequote}
+subroutine, the program runs as usual:
+
+@smallexample
+(@value{GDBP}) @b{run}
+Starting program: /work/Editorial/gdb/gnu/m4/m4
+@b{define(foo,0000)}
+
+@b{foo}
+0000
+@end smallexample
+
+@noindent
+To trigger the breakpoint, we call @code{changequote}.  @value{GDBN}
+suspends execution of @code{m4}, displaying information about the
+context where it stops.
+
+@smallexample
+@b{changequote(<QUOTE>,<UNQUOTE>)}
+
+Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 
+    at builtin.c:879
+879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
+@end smallexample
+
+@noindent
+Now we use the command @code{n} (@code{next}) to advance execution to
+the next line of the current function.
+
+@smallexample
+(@value{GDBP}) @b{n}
+882         set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
+ : nil,
+@end smallexample
+
+@noindent
+@code{set_quotes} looks like a promising subroutine.  We can go into it
+by using the command @code{s} (@code{step}) instead of @code{next}.
+@code{step} goes to the next line to be executed in @emph{any}
+subroutine, so it steps into @code{set_quotes}.
+
+@smallexample
+(@value{GDBP}) @b{s}
+set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
+    at input.c:530
+530         if (lquote != def_lquote)
+@end smallexample
+
+@noindent
+The display that shows the subroutine where @code{m4} is now
+suspended (and its arguments) is called a stack frame display.  It
+shows a summary of the stack.  We can use the @code{backtrace}
+command (which can also be spelled @code{bt}), to see where we are
+in the stack as a whole: the @code{backtrace} command displays a
+stack frame for each active subroutine.
+
+@smallexample
+(@value{GDBP}) @b{bt}
+#0  set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
+    at input.c:530
+#1  0x6344 in m4_changequote (argc=3, argv=0x33c70) 
+    at builtin.c:882
+#2  0x8174 in expand_macro (sym=0x33320) at macro.c:242
+#3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
+    at macro.c:71
+#4  0x79dc in expand_input () at macro.c:40
+#5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
+@end smallexample
+
+@noindent
+We step through a few more lines to see what happens.  The first two
+times, we can use @samp{s}; the next two times we use @code{n} to avoid
+falling into the @code{xstrdup} subroutine.
+
+@smallexample
+(@value{GDBP}) @b{s}
+0x3b5c  532         if (rquote != def_rquote)
+(@value{GDBP}) @b{s}
+0x3b80  535         lquote = (lq == nil || *lq == '\0') ?  \
+def_lquote : xstrdup(lq);
+(@value{GDBP}) @b{n}
+536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
+ : xstrdup(rq);
+(@value{GDBP}) @b{n}
+538         len_lquote = strlen(rquote);
+@end smallexample
+
+@noindent
+The last line displayed looks a little odd; we can examine the variables
+@code{lquote} and @code{rquote} to see if they are in fact the new left
+and right quotes we specified.  We use the command @code{p}
+(@code{print}) to see their values.
+
+@smallexample
+(@value{GDBP}) @b{p lquote}
+$1 = 0x35d40 "<QUOTE>"
+(@value{GDBP}) @b{p rquote}
+$2 = 0x35d50 "<UNQUOTE>"
+@end smallexample
+
+@noindent
+@code{lquote} and @code{rquote} are indeed the new left and right quotes.
+To look at some context, we can display ten lines of source
+surrounding the current line with the @code{l} (@code{list}) command.
+
+@smallexample
+(@value{GDBP}) @b{l}
+533             xfree(rquote);
+534
+535         lquote = (lq == nil || *lq == '\0') ? def_lquote\
+ : xstrdup (lq);
+536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
+ : xstrdup (rq);
+537
+538         len_lquote = strlen(rquote);
+539         len_rquote = strlen(lquote);
+540     @}
+541
+542     void
+@end smallexample
+
+@noindent
+Let us step past the two lines that set @code{len_lquote} and
+@code{len_rquote}, and then examine the values of those variables.
+
+@smallexample
+(@value{GDBP}) @b{n}
+539         len_rquote = strlen(lquote);
+(@value{GDBP}) @b{n}
+540     @}
+(@value{GDBP}) @b{p len_lquote}
+$3 = 9
+(@value{GDBP}) @b{p len_rquote}
+$4 = 7
+@end smallexample
+
+@noindent
+That certainly looks wrong, assuming @code{len_lquote} and
+@code{len_rquote} are meant to be the lengths of @code{lquote} and
+@code{rquote} respectively.  We can set them to better values using
+the @code{p} command, since it can print the value of
+any expression---and that expression can include subroutine calls and
+assignments.
+
+@smallexample
+(@value{GDBP}) @b{p len_lquote=strlen(lquote)}
+$5 = 7
+(@value{GDBP}) @b{p len_rquote=strlen(rquote)}
+$6 = 9
+@end smallexample
+
+@noindent
+Is that enough to fix the problem of using the new quotes with the
+@code{m4} built-in @code{defn}?  We can allow @code{m4} to continue
+executing with the @code{c} (@code{continue}) command, and then try the
+example that caused trouble initially:
+
+@smallexample
+(@value{GDBP}) @b{c}
+Continuing.
+
+@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
+
+baz
+0000
+@end smallexample
+
+@noindent
+Success!  The new quotes now work just as well as the default ones.  The
+problem seems to have been just the two typos defining the wrong
+lengths.  We allow @code{m4} exit by giving it an EOF as input:
+
+@smallexample
+@b{C-d}
+Program exited normally.
+@end smallexample
+
+@noindent
+The message @samp{Program exited normally.} is from @value{GDBN}; it
+indicates @code{m4} has finished executing.  We can end our @value{GDBN}
+session with the @value{GDBN} @code{quit} command.
+
+@smallexample
+(@value{GDBP}) @b{quit}
+@end smallexample
+@end ifclear
+
+@node Invocation, Commands, Sample Session, Top
+@chapter Getting In and Out of @value{GDBN}
+
+This chapter discusses how to start @value{GDBN}, and how to get out of it.
+The essentials are: 
+@itemize @bullet
+@item 
+type @samp{@value{GDBP}} to start GDB.
+@item 
+type @kbd{quit} or @kbd{C-d} to exit.
+@end itemize
+
+@menu
+* Invoking GDB::                How to start @value{GDBN}
+* Quitting GDB::                How to quit @value{GDBN}
+* Shell Commands::              How to use shell commands inside @value{GDBN}
+@end menu
+
+@node Invoking GDB, Quitting GDB, Invocation, Invocation
+@section Invoking @value{GDBN}
+
+@ifset H8EXCLUSIVE
+For details on starting up @value{GDBP} as a
+remote debugger attached to a Hitachi microprocessor, see @ref{Hitachi
+Remote,,@value{GDBN} and Hitachi Microprocessors}.
+@end ifset
+
+Invoke @value{GDBN} by running the program @code{@value{GDBP}}.  Once started,
+@value{GDBN} reads commands from the terminal until you tell it to exit.
+
+You can also run @code{@value{GDBP}} with a variety of arguments and options,
+to specify more of your debugging environment at the outset.
+
+@ifset GENERIC
+The command-line options described here are designed
+to cover a variety of situations; in some environments, some of these
+options may effectively be unavailable.  
+@end ifset
+
+The most usual way to start @value{GDBN} is with one argument,
+specifying an executable program:
+
+@example
+@value{GDBP} @var{program}
+@end example
+
+@ifclear BARETARGET
+@noindent
+You can also start with both an executable program and a core file
+specified:
+
+@example
+@value{GDBP} @var{program} @var{core}
+@end example
+
+You can, instead, specify a process ID as a second argument, if you want
+to debug a running process:
+
+@example
+@value{GDBP} @var{program} 1234
+@end example
+
+@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).
+
+@ifclear HPPA
+Taking advantage of the second command-line argument requires a fairly
+complete operating system; when you use @value{GDBN} as a remote debugger
+attached to a bare board, there may not be any notion of ``process'',
+and there is often no way to get a core dump.
+@end ifclear
+@end ifclear
+
+You can run @code{gdb} without printing the front material, which describes
+@value{GDBN}'s non-warranty, by specifying @code{-silent}:
+
+@smallexample
+@value{GDBP} -silent
+@end smallexample
+
+@noindent
+You can further control how @value{GDBN} starts up by using command-line
+options.  @value{GDBN} itself can remind you of the options available.
+
+@noindent
+Type
+
+@example
+@value{GDBP} -help
+@end example
+
+@noindent
+to display all available options and briefly describe their use
+(@samp{@value{GDBP} -h} is a shorter equivalent).
+
+All options and command line arguments you give are processed
+in sequential order.  The order makes a difference when the
+@samp{-x} option is used.
+
+
+@menu
+@ifclear GENERIC
+@ifset REMOTESTUB
+* Remote Serial::               @value{GDBN} remote serial protocol
+@end ifset
+@ifset I960
+* i960-Nindy Remote::		@value{GDBN} with a remote i960 (Nindy)
+@end ifset
+@ifset AMD29K
+* UDI29K Remote::               The UDI protocol for AMD29K
+* EB29K Remote::		The EBMON protocol for AMD29K
+@end ifset
+@ifset VXWORKS
+* VxWorks Remote::		@value{GDBN} and VxWorks
+@end ifset
+@ifset ST2000
+* ST2000 Remote::               @value{GDBN} with a Tandem ST2000
+@end ifset
+@ifset H8
+* Hitachi Remote::              @value{GDBN} and Hitachi Microprocessors
+@end ifset
+@ifset MIPS
+* MIPS Remote::			@value{GDBN} and MIPS boards
+@end ifset
+@ifset SPARCLET
+* Sparclet Remote::             @value{GDBN} and Sparclet boards
+@end ifset
+@ifset SIMS
+* Simulator::                   Simulated CPU target
+@end ifset
+@end ifclear
+@c remnant makeinfo bug requires this blank line after *two* end-ifblahs:
+
+* File Options::                Choosing files
+* Mode Options::                Choosing modes
+@end menu
+
+@ifclear GENERIC
+@ifclear HPPA
+@include remote.texi
+@end ifclear
+@end ifclear
+
+@node File Options
+@subsection Choosing files
+
+@ifclear BARETARGET
+When @value{GDBN} starts, it reads any arguments other than options as
+specifying an executable file and core file (or process ID).  This is
+the same as if the arguments were specified by the @samp{-se} and
+@samp{-c} options respectively.  (@value{GDBN} reads the first argument
+that does not have an associated option flag as equivalent to the
+@samp{-se} option followed by that argument; and the second argument
+that does not have an associated option flag, if any, as equivalent to
+the @samp{-c} option followed by that argument.)
+@end ifclear
+@ifset BARETARGET
+When @value{GDBN} starts, it reads any argument other than options as
+specifying an executable file.  This is the same as if the argument was
+specified by the @samp{-se} option.
+@end ifset
+
+Many options have both long and short forms; both are shown in the
+following list.  @value{GDBN} also recognizes the long forms 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 @samp{--} rather
+than @samp{-}, though we illustrate the more usual convention.)
+
+@table @code
+@item -symbols @var{file}
+@itemx -s @var{file}
+Read symbol table from file @var{file}.
+
+@item -exec @var{file}
+@itemx -e @var{file}
+Use file @var{file} as the executable file to execute when
+@ifset BARETARGET
+appropriate.
+@end ifset
+@ifclear BARETARGET
+appropriate, and for examining pure data in conjunction with a core
+dump.
+@end ifclear
+
+@item -se @var{file}
+Read symbol table from file @var{file} and use it as the executable
+file.
+
+@ifclear BARETARGET
+@item -core @var{file}
+@itemx -c @var{file}
+Use file @var{file} as a core dump to examine.
+
+@item -c @var{number}
+Connect to process ID @var{number}, as with the @code{attach} command
+(unless there is a file in core-dump format named @var{number}, in which
+case @samp{-c} specifies that file as a core dump to read).
+@end ifclear
+
+@item -command @var{file}
+@itemx -x @var{file}
+Execute @value{GDBN} commands from file @var{file}.  @xref{Command
+Files,, Command files}.
+
+@item -directory @var{directory}
+@itemx -d @var{directory}
+Add @var{directory} to the path to search for source files.
+
+@ifclear BARETARGET
+@ifclear HPPA
+@item -m
+@itemx -mapped
+@emph{Warning: this option depends on operating system facilities that are not
+supported on all systems.}@*
+If memory-mapped files are available on your system through the @code{mmap}
+system call, you can use this option 
+to have @value{GDBN} write the symbols from your
+program into a reusable file in the current directory.  If the program you are debugging is
+called @file{/tmp/fred}, the mapped symbol file is @file{./fred.syms}.
+Future @value{GDBN} debugging sessions notice the presence of this file,
+and can quickly map in symbol information from it, rather than reading
+the symbol table from the executable program.
+
+The @file{.syms} file is specific to the host machine where @value{GDBN}
+is run.  It holds an exact image of the internal @value{GDBN} symbol
+table.  It cannot be shared across multiple host platforms.
+@end ifclear
+@end ifclear
+
+@ifclear HPPA
+@item -r
+@itemx -readnow
+Read each symbol file's entire symbol table immediately, rather than
+the default, which is to read it incrementally as it is needed.
+This makes startup slower, but makes future operations faster.
+@end ifclear
+@end table
+
+@ifclear BARETARGET
+@ifclear HPPA
+The @code{-mapped} and @code{-readnow} options are typically combined in
+order to build a @file{.syms} file that contains complete symbol
+information.  (@xref{Files,,Commands to specify files}, for
+information on @file{.syms} files.) A simple GDB invocation to do
+nothing but build a @file{.syms} file for future use is:
+
+@example
+	gdb -batch -nx -mapped -readnow programname
+@end example
+@end ifclear
+@end ifclear
+
+@node Mode Options,  , File Options, Invoking GDB
+@subsection Choosing modes
+
+You can run @value{GDBN} in various alternative modes---for example, in
+batch mode or quiet mode.
+
+@table @code
+@item -nx
+@itemx -n
+Do not execute commands from any initialization files (normally called
+@file{.gdbinit}, or @file{gdb.ini} on PCs).  Normally, the commands in
+these files are executed after all the command options and arguments
+have been processed.  @xref{Command Files,,Command 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 @samp{-x} (and all commands from
+initialization files, if not inhibited with @samp{-n}).  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
+
+@example
+Program exited normally.
+@end example
+
+@noindent
+(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.
+
+@ifclear DOSHOST
+@item -fullname
+@itemx -f
+@sc{gnu} 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 your 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.
+@end ifclear
+
+@ifset SERIAL
+@ifclear HPPA
+@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.
+@end ifclear
+
+@item -tty @var{device}
+Run using @var{device} for your program's standard input and output.
+@c FIXME: kingdon thinks there is more to -tty.  Investigate.
+@end ifset
+
+@ifset HPPA
+@item -tui
+Use a Terminal User Interface.  For information, use your Web browser to
+read the file @file{TUI.html}, which is usually installed in the
+directory @code{/opt/langtools/wdb/doc} on HP-UX systems.  Do not use
+this option if you run @value{GDBN} from Emacs (see @pxref{Emacs, ,Using
+@value{GDBN} under @sc{gnu} Emacs}).
+
+@item -xdb
+Run in XDB compatibility mode, allowing the use of certain XDB commands.
+For information, see the file @file{xdb_trans.html}, which is usually
+installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
+systems.
+@end ifset
+@end table
+
+@node Quitting GDB, Shell Commands, Invoking GDB, Invocation
+@section Quitting @value{GDBN}
+@cindex exiting @value{GDBN}
+@cindex leaving @value{GDBN}
+
+@table @code
+@kindex quit @r{[}@var{expression}@r{]}
+@kindex q
+@item quit
+To exit @value{GDBN}, use the @code{quit} command (abbreviated @code{q}), or 
+type an end-of-file character (usually @kbd{C-d}).  If you do not supply 
+@var{expression}, @value{GDBN} will terminate normally; otherwise it will 
+terminate using the result of @var{expression} as the error code.
+@end table
+
+@cindex interrupt
+An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather
+terminates the action of any @value{GDBN} command that is in progress and
+returns to @value{GDBN} command level.  It is safe to type the interrupt
+character at any time because @value{GDBN} does not allow it to take effect
+until a time when it is safe.
+
+@ifclear BARETARGET
+If you have been using @value{GDBN} to control an attached process or
+device, you can release it with the @code{detach} command
+(@pxref{Attach, ,Debugging an already-running process}).
+@end ifclear
+
+@node Shell Commands,  , Quitting GDB, Invocation
+@section Shell commands
+
+If you need to execute occasional shell commands during your
+debugging session, there is no need to leave or suspend @value{GDBN}; you can
+just use the @code{shell} command.
+
+@table @code
+@kindex shell
+@cindex shell escape
+@item shell @var{command string}
+Invoke a standard shell to execute @var{command string}.
+@ifclear DOSHOST
+If it exists, the environment variable @code{SHELL} determines which
+shell to run.  Otherwise @value{GDBN} uses @code{/bin/sh}.
+@end ifclear
+@end table
+
+The utility @code{make} is often needed in development environments.
+You do not have to use the @code{shell} command for this purpose in
+@value{GDBN}:
+
+@table @code
+@kindex make
+@cindex calling make
+@item make @var{make-args}
+Execute the @code{make} program with the specified
+arguments.  This is equivalent to @samp{shell make @var{make-args}}.
+@end table
+
+@node Commands, Running, Invocation, Top
+@chapter @value{GDBN} Commands
+
+You can abbreviate a @value{GDBN} command to the first few letters of the command
+name, if that abbreviation is unambiguous; and you can repeat certain
+@value{GDBN} commands by typing just @key{RET}.  You can also use the @key{TAB}
+key to get @value{GDBN} to fill out the rest of a word in a command (or to
+show you the alternatives available, if there is more than one possibility).
+
+@menu
+* Command Syntax::              How to give commands to @value{GDBN}
+* Completion::                  Command completion
+* Help::                        How to ask @value{GDBN} for help
+@end menu
+
+@node Command Syntax, Completion, Commands, Commands
+@section Command syntax
+
+A @value{GDBN} command is a single line of input.  There is no limit on
+how long it can be.  It starts with a command name, which is followed by
+arguments whose meaning depends on the command name.  For example, the
+command @code{step} accepts an argument which is the number of times to
+step, as in @samp{step 5}.  You can also use the @code{step} command
+with no arguments.  Some command names do not allow any arguments.
+
+@cindex abbreviation
+@value{GDBN} command names may always be truncated if that abbreviation is
+unambiguous.  Other possible command abbreviations are listed in the
+documentation for individual commands.  In some cases, even ambiguous
+abbreviations are allowed; for example, @code{s} is specially defined as
+equivalent to @code{step} even though there are other commands whose
+names start with @code{s}.  You can test abbreviations by using them as
+arguments to the @code{help} command.
+
+@cindex repeating commands
+@kindex RET
+A blank line as input to @value{GDBN} (typing just @key{RET}) means to
+repeat the previous command. Certain commands (for example, @code{run})
+will not repeat this way; these are commands whose unintentional
+repetition might cause trouble and which you are unlikely to want to
+repeat.
+
+The @code{list} and @code{x} commands, when you repeat them with
+@key{RET}, construct new arguments rather than repeating
+exactly as typed.  This permits easy scanning of source or memory.
+
+@value{GDBN} can also use @key{RET} in another way: to partition lengthy
+output, in a way similar to the common utility @code{more}
+(@pxref{Screen Size,,Screen size}).  Since it is easy to press one
+@key{RET} too many in this situation, @value{GDBN} disables command
+repetition after any command that generates this sort of display.
+
+@kindex #
+@cindex comment
+Any text from a @kbd{#} to the end of the line is a comment; it does
+nothing.  This is useful mainly in command files (@pxref{Command
+Files,,Command files}).
+
+@node Completion, Help, Command Syntax, Commands
+@section Command completion
+
+@cindex completion
+@cindex word completion
+@value{GDBN} can fill in the rest of a word in a command for you, if there is
+only one possibility; it can also show you what the valid possibilities
+are for the next word in a command, at any time.  This works for @value{GDBN}
+commands, @value{GDBN} subcommands, and the names of symbols in your program.
+
+Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
+of a word.  If there is only one possibility, @value{GDBN} fills in the
+word, and waits for you to finish the command (or press @key{RET} to
+enter it).  For example, if you type
+
+@c FIXME "@key" does not distinguish its argument sufficiently to permit
+@c complete accuracy in these examples; space introduced for clarity.
+@c If texinfo enhancements make it unnecessary, it would be nice to
+@c replace " @key" by "@key" in the following...
+@example
+(@value{GDBP}) info bre @key{TAB}
+@end example
+
+@noindent
+@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
+the only @code{info} subcommand beginning with @samp{bre}:
+
+@example
+(@value{GDBP}) info breakpoints
+@end example
+
+@noindent
+You can either press @key{RET} at this point, to run the @code{info
+breakpoints} command, or backspace and enter something else, if
+@samp{breakpoints} does not look like the command you expected.  (If you
+were sure you wanted @code{info breakpoints} in the first place, you
+might as well just type @key{RET} immediately after @samp{info bre},
+to exploit command abbreviations rather than command completion).
+
+If there is more than one possibility for the next word when you press
+@key{TAB}, @value{GDBN} sounds a bell.  You can either supply more
+characters and try again, or just press @key{TAB} a second time;
+@value{GDBN} displays all the possible completions for that word.  For
+example, you might want to set a breakpoint on a subroutine whose name
+begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
+just sounds the bell.  Typing @key{TAB} again displays all the
+function names in your program that begin with those characters, for
+example:
+
+@example
+(@value{GDBP}) b make_ @key{TAB}
+@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
+make_a_section_from_file     make_environ               
+make_abs_section             make_function_type         
+make_blockvector             make_pointer_type          
+make_cleanup                 make_reference_type        
+make_command                 make_symbol_completion_list
+(@value{GDBP}) b make_
+@end example
+
+@noindent
+After displaying the available possibilities, @value{GDBN} copies your
+partial input (@samp{b make_} in the example) so you can finish the
+command.
+
+If you just want to see the list of alternatives in the first place, you
+can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
+means @kbd{@key{META} ?}.  You can type this
+@ifclear DOSHOST
+either by holding down a
+key designated as the @key{META} shift on your keyboard (if there is
+one) while typing @kbd{?}, or
+@end ifclear
+as @key{ESC} followed by @kbd{?}.
+
+@cindex quotes in commands
+@cindex completion of quoted strings
+Sometimes the string you need, while logically a ``word'', may contain
+parentheses or other characters that @value{GDBN} normally excludes from its
+notion of a word.  To permit word completion to work in this situation,
+you may enclose words in @code{'} (single quote marks) in @value{GDBN} commands.
+
+@ifclear CONLY
+The most likely situation where you might need this is in typing the
+name of a C++ function.  This is because C++ allows function overloading
+(multiple definitions of the same function, distinguished by argument
+type).  For example, when you want to set a breakpoint you may need to
+distinguish whether you mean the version of @code{name} that takes an
+@code{int} parameter, @code{name(int)}, or the version that takes a
+@code{float} parameter, @code{name(float)}.  To use the word-completion
+facilities in this situation, type a single quote @code{'} at the
+beginning of the function name.  This alerts @value{GDBN} that it may need to
+consider more information than usual when you press @key{TAB} or
+@kbd{M-?} to request word completion:
+
+@example
+(@value{GDBP}) b 'bubble( @key{M-?}
+bubble(double,double)    bubble(int,int)
+(@value{GDBP}) b 'bubble(
+@end example
+
+In some cases, @value{GDBN} can tell that completing a name requires using
+quotes.  When this happens, @value{GDBN} inserts the quote for you (while
+completing as much as it can) if you do not type the quote in the first
+place:
+
+@example
+(@value{GDBP}) b bub @key{TAB}
+@exdent @value{GDBN} alters your input line to the following, and rings a bell:
+(@value{GDBP}) b 'bubble(
+@end example
+
+@noindent
+In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
+you have not yet started typing the argument list when you ask for
+completion on an overloaded symbol.
+
+For more information about overloaded functions, @pxref{Cplus
+expressions, ,C++ expressions}.  You can use the command @code{set
+overload-resolution off} to disable overload resolution;
+@pxref{Debugging C plus plus, ,@value{GDBN} features for C++}.
+@end ifclear
+
+
+@node Help,  , Completion, Commands
+@section Getting help
+@cindex online documentation
+@kindex help
+
+You can always ask @value{GDBN} itself for information on its commands, 
+using the command @code{help}.
+
+@table @code
+@kindex h
+@item help
+@itemx h
+You can use @code{help} (abbreviated @code{h}) with no arguments to
+display a short list of named classes of commands:
+
+@smallexample
+(@value{GDBP}) help
+List of classes of commands:
+
+running -- Running the program
+stack -- Examining the stack
+data -- Examining data
+breakpoints -- Making program stop at certain points
+files -- Specifying and examining files
+status -- Status inquiries
+support -- Support facilities
+user-defined -- User-defined commands
+aliases -- Aliases of other commands
+obscure -- Obscure features
+
+Type "help" followed by a class name for a list of 
+commands in that class.
+Type "help" followed by command name for full 
+documentation.
+Command name abbreviations are allowed if unambiguous.
+(@value{GDBP})
+@end smallexample
+
+@item help @var{class}
+Using one of the general help classes as an argument, you can get a
+list of the individual commands in that class.  For example, here is the
+help display for the class @code{status}:
+
+@smallexample
+(@value{GDBP}) help status
+Status inquiries.
+
+List of commands:
+
+@c Line break in "show" line falsifies real output, but needed
+@c to fit in smallbook page size.
+show -- Generic command for showing things set
+ with "set"
+info -- Generic command for printing status
+
+Type "help" followed by command name for full 
+documentation.
+Command name abbreviations are allowed if unambiguous.
+(@value{GDBP})
+@end smallexample
+
+@item help @var{command}
+With a command name as @code{help} argument, @value{GDBN} displays a
+short paragraph on how to use that command.
+
+@kindex complete
+@item complete @var{args}
+The @code{complete @var{args}} command lists all the possible completions
+for the beginning of a command.  Use @var{args} to specify the beginning of the
+command you want completed.  For example:
+
+@smallexample
+complete i
+@end smallexample
+
+@noindent results in:
+
+@smallexample
+@group
+info
+inspect
+ignore
+@end group
+@end smallexample
+
+@noindent This is intended for use by @sc{gnu} Emacs.
+@end table
+
+In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
+and @code{show} to inquire about the state of your program, or the state
+of @value{GDBN} itself.  Each command supports many topics of inquiry; this
+manual introduces each of them in the appropriate context.  The listings
+under @code{info} and under @code{show} in the Index point to
+all the sub-commands.  @xref{Index}.
+
+@c @group
+@table @code
+@kindex info
+@kindex i
+@item info
+This command (abbreviated @code{i}) is for describing the state of your
+program.  For example, you can list the arguments given to your program
+with @code{info args}, list the registers currently in use with @code{info
+registers}, or list the breakpoints you have set with @code{info breakpoints}.
+You can get a complete list of the @code{info} sub-commands with
+@w{@code{help info}}.
+
+@kindex set
+@item set
+You can assign the result of an expression to an environment variable with 
+@code{set}.  For example, you can set the @value{GDBN} prompt to a $-sign with
+@code{set prompt $}.
+
+@kindex show
+@item show
+In contrast to @code{info}, @code{show} is for describing the state of 
+@value{GDBN} itself.
+You can change most of the things you can @code{show}, by using the
+related command @code{set}; for example, you can control what number
+system is used for displays with @code{set radix}, or simply inquire
+which is currently in use with @code{show radix}.
+
+@kindex info set
+To display all the settable parameters and their current
+values, you can use @code{show} with no arguments; you may also use
+@code{info set}.  Both commands produce the same display.
+@c FIXME: "info set" violates the rule that "info" is for state of
+@c FIXME...program.  Ck w/ GNU: "info set" to be called something else,
+@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
+@end table
+@c @end group
+
+Here are three miscellaneous @code{show} subcommands, all of which are
+exceptional in lacking corresponding @code{set} commands:
+
+@table @code
+@kindex show version
+@cindex version number
+@item show version
+Show what version of @value{GDBN} is running.  You should include this
+information in @value{GDBN} bug-reports.  If multiple versions of @value{GDBN} are in
+use at your site, you may occasionally want to determine which version
+of @value{GDBN} you are running; as @value{GDBN} evolves, new commands are introduced,
+and old ones may wither away.  The version number is also announced
+when you start @value{GDBN}.
+
+@kindex show copying
+@item show copying
+Display information about permission for copying @value{GDBN}.
+
+@kindex show warranty
+@item show warranty
+Display the @sc{gnu} ``NO WARRANTY'' statement.
+@end table
+
+@node Running, Stopping, Commands, Top
+@chapter Running Programs Under @value{GDBN}
+
+When you run a program under @value{GDBN}, you must first generate
+debugging information when you compile it.
+@ifclear BARETARGET
+You may start @value{GDBN} with its arguments, if any, in an environment 
+of your choice.  You may redirect your program's input and output, debug an
+already running process, or kill a child process.
+@end ifclear
+
+@menu
+* Compilation::                 Compiling for debugging
+* Starting::                    Starting your program
+@ifclear BARETARGET
+* Arguments::                   Your program's arguments
+* Environment::                 Your program's environment
+@end ifclear
+
+* Working Directory::           Your program's working directory
+* Input/Output::                Your program's input and output
+* Attach::                      Debugging an already-running process
+* Kill Process::                Killing the child process
+@ifclear HPPA
+* Process Information::         Additional process information
+@end ifclear
+
+* Threads::                     Debugging programs with multiple threads
+* Processes::                   Debugging programs with multiple processes
+@end menu
+
+@node Compilation, Starting, Running, Running
+@section Compiling for debugging
+
+In order to debug a program effectively, you need to generate
+debugging information when you compile it.  This debugging information
+is stored in the object file; it describes the data type of each
+variable or function and the correspondence between source line numbers
+and addresses in the executable code.
+
+To request debugging information, specify the @samp{-g} option when you run
+the compiler.
+
+Many C compilers are unable to handle the @samp{-g} and @samp{-O}
+options together.  Using those compilers, you cannot generate optimized
+executables containing debugging information.
+
+@ifclear HPPA
+@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or without
+@end ifclear
+@ifset HPPA
+The HP ANSI C and C++ compilers, as well as @value{NGCC}, the @sc{gnu} C
+compiler, support @samp{-g} with or without
+@end ifset
+@samp{-O}, making it possible to debug optimized code.  We recommend
+that you @emph{always} use @samp{-g} whenever you compile a program.
+You may think your program is correct, but there is no sense in pushing
+your luck.
+
+@cindex optimized code, debugging
+@cindex debugging optimized code
+When you debug a program compiled with @samp{-g -O}, remember that the
+optimizer is rearranging your code; the debugger shows you what is
+really there.  Do not be too surprised when the execution path does not
+exactly match your source file!  An extreme example: if you define a
+variable, but never use it, @value{GDBN} never sees that
+variable---because the compiler optimizes it out of existence.
+
+Some things do not work as well with @samp{-g -O} as with just
+@samp{-g}, particularly on machines with instruction scheduling.  If in
+doubt, recompile with @samp{-g} alone, and if this fixes the problem,
+please report it to us as a bug (including a test case!).
+
+Older versions of the @sc{gnu} C compiler permitted a variant option
+@w{@samp{-gg}} for debugging information.  @value{GDBN} no longer supports this
+format; if your @sc{gnu} C compiler has this option, do not use it.
+
+@need 2000
+@node Starting, Arguments, Compilation, Running
+@section Starting your program
+@cindex starting
+@cindex running
+
+@table @code
+@kindex run
+@item run
+@itemx r
+Use the @code{run} command to start your program under @value{GDBN}.  You must
+first specify the program name
+@ifset VXWORKS
+(except on VxWorks)
+@end ifset
+with an argument to @value{GDBN} (@pxref{Invocation, ,Getting In and
+Out of @value{GDBN}}), or by using the @code{file} or @code{exec-file}
+command (@pxref{Files, ,Commands to specify files}).
+
+@end table
+
+@ifclear BARETARGET
+If you are running your program in an execution environment that
+supports processes, @code{run} creates an inferior process and makes
+that process run your program.  (In environments without processes,
+@code{run} jumps to the start of your program.)
+
+The execution of a program is affected by certain information it
+receives from its superior.  @value{GDBN} provides ways to specify this
+information, which you must do @emph{before} starting your program.  (You
+can change it after starting your program, but such changes only affect
+your program the next time you start it.)  This information may be
+divided into four categories:
+
+@table @asis
+@item The @emph{arguments.}
+Specify the arguments to give your program as the arguments of the
+@code{run} command.  If a shell is available on your target, the shell
+is used to pass the arguments, so that you may use normal conventions
+(such as wildcard expansion or variable substitution) in describing
+the arguments.
+In Unix systems, you can control which shell is used with the
+@code{SHELL} environment variable.
+@xref{Arguments, ,Your program's arguments}.
+
+@item The @emph{environment.}
+Your program normally inherits its environment from @value{GDBN}, but you can
+use the @value{GDBN} commands @code{set environment} and @code{unset
+environment} to change parts of the environment that affect
+your program.  @xref{Environment, ,Your program's environment}.
+
+@item The @emph{working directory.}
+Your program inherits its working directory from @value{GDBN}.  You can set
+the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
+@xref{Working Directory, ,Your program's working directory}.
+
+@item The @emph{standard input and output.}
+Your program normally uses the same device for standard input and
+standard output as @value{GDBN} is using.  You can redirect input and output
+in the @code{run} command line, or you can use the @code{tty} command to
+set a different device for your program.
+@xref{Input/Output, ,Your program's input and output}.
+
+@cindex pipes
+@emph{Warning:} While input and output redirection work, you cannot use
+pipes to pass the output of the program you are debugging to another
+program; if you attempt this, @value{GDBN} is likely to wind up debugging the
+wrong program.
+@end table
+@end ifclear
+
+When you issue the @code{run} command, your program begins to execute
+immediately.  @xref{Stopping, ,Stopping and continuing}, for discussion
+of how to arrange for your program to stop.  Once your program has
+stopped, you may call functions in your program, using the @code{print}
+or @code{call} commands.  @xref{Data, ,Examining Data}.
+
+If the modification time of your symbol file has changed since the last
+time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
+table, and reads it again.  When it does this, @value{GDBN} tries to retain
+your current breakpoints.
+
+@ifclear BARETARGET
+@node Arguments, Environment, Starting, Running
+@section Your program's arguments
+
+@cindex arguments (to your program)
+The arguments to your program can be specified by the arguments of the
+@code{run} command.  
+They are passed to a shell, which expands wildcard characters and
+performs redirection of I/O, and thence to your program.  Your
+@code{SHELL} environment variable (if it exists) specifies what shell
+@value{GDBN} uses.  If you do not define @code{SHELL}, @value{GDBN} uses
+@code{/bin/sh}.
+
+@code{run} with no arguments uses the same arguments used by the previous
+@code{run}, or those set by the @code{set args} command.
+
+@kindex set args
+@table @code
+@item set args
+Specify the arguments to be used the next time your program is run.  If
+@code{set args} has no arguments, @code{run} executes your program
+with no arguments.  Once you have run your program with arguments,
+using @code{set args} before the next @code{run} is the only way to run
+it again without arguments.
+
+@kindex show args
+@item show args
+Show the arguments to give your program when it is started.
+@end table
+
+@node Environment, Working Directory, Arguments, Running
+@section Your program's environment
+
+@cindex environment (of your program)
+The @dfn{environment} consists of a set of environment variables and
+their values.  Environment variables conventionally record such things as
+your user name, your home directory, your terminal type, and your search
+path for programs to run.  Usually you set up environment variables with
+the shell and they are inherited by all the other programs you run.  When
+debugging, it can be useful to try running your program with a modified
+environment without having to start @value{GDBN} over again.
+
+@table @code
+@kindex path
+@item path @var{directory}
+Add @var{directory} to the front of the @code{PATH} environment variable
+(the search path for executables), for both @value{GDBN} and your program.
+You may specify several directory names, separated by @samp{:} or
+whitespace.  If @var{directory} is already in the path, it is moved to
+the front, so it is searched sooner.
+
+You can use the string @samp{$cwd} to refer to whatever is the current
+working directory at the time @value{GDBN} searches the path.  If you
+use @samp{.} instead, it refers to the directory where you executed the
+@code{path} command.  @value{GDBN} replaces @samp{.} in the
+@var{directory} argument (with the current path) before adding
+@var{directory} to the search path.
+@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
+@c document that, since repeating it would be a no-op.
+
+@kindex show paths
+@item show paths
+Display the list of search paths for executables (the @code{PATH}
+environment variable).
+
+@kindex show environment
+@item show environment @r{[}@var{varname}@r{]}
+Print the value of environment variable @var{varname} to be given to
+your program when it starts.  If you do not supply @var{varname},
+print the names and values of all environment variables to be given to
+your program.  You can abbreviate @code{environment} as @code{env}.
+
+@kindex set environment
+@item set environment @var{varname} @r{[}=@r{]} @var{value}
+Set environment variable @var{varname} to @var{value}.  The value
+changes for your program only, not for @value{GDBN} itself.  @var{value} may
+be any string; the values of environment variables are just strings, and
+any interpretation is supplied by your program itself.  The @var{value}
+parameter is optional; if it is eliminated, the variable is set to a
+null value.
+@c "any string" here does not include leading, trailing
+@c blanks. Gnu asks: does anyone care?
+
+For example, this command:
+
+@example
+set env USER = foo
+@end example
+
+@noindent
+tells a Unix program, when subsequently run, that its user is named
+@samp{foo}.  (The spaces around @samp{=} are used for clarity here; they
+are not actually required.)
+
+@kindex unset environment
+@item unset environment @var{varname}
+Remove variable @var{varname} from the environment to be passed to your
+program.  This is different from @samp{set env @var{varname} =};
+@code{unset environment} removes the variable from the environment,
+rather than assigning it an empty value.
+@end table
+
+@emph{Warning:} @value{GDBN} runs your program using the shell indicated
+by your @code{SHELL} environment variable if it exists (or
+@code{/bin/sh} if not).  If your @code{SHELL} variable names a shell
+that runs an initialization file---such as @file{.cshrc} for C-shell, or
+@file{.bashrc} for BASH---any variables you set in that file affect
+your program.  You may wish to move setting of environment variables to
+files that are only run when you sign on, such as @file{.login} or
+@file{.profile}.
+
+@node Working Directory, Input/Output, Environment, Running
+@section Your program's working directory
+
+@cindex working directory (of your program)
+Each time you start your program with @code{run}, it inherits its
+working directory from the current working directory of @value{GDBN}.
+The @value{GDBN} working directory is initially whatever it inherited
+from its parent process (typically the shell), but you can specify a new
+working directory in @value{GDBN} with the @code{cd} command.
+
+The @value{GDBN} working directory also serves as a default for the commands
+that specify files for @value{GDBN} to operate on.  @xref{Files, ,Commands to
+specify files}.
+
+@table @code
+@kindex cd
+@item cd @var{directory}
+Set the @value{GDBN} working directory to @var{directory}.
+
+@kindex pwd
+@item pwd
+Print the @value{GDBN} working directory.
+@end table
+
+@node Input/Output, Attach, Working Directory, Running
+@section Your program's input and output
+
+@cindex redirection
+@cindex i/o
+@cindex terminal
+By default, the program you run under @value{GDBN} does input and output to
+the same terminal that @value{GDBN} uses.  @value{GDBN} switches the terminal 
+to its own terminal modes to interact with you, but it records the terminal
+modes your program was using and switches back to them when you continue
+running your program.
+
+@table @code
+@kindex info terminal
+@item info terminal
+Displays information recorded by @value{GDBN} about the terminal modes your
+program is using.
+@end table
+
+You can redirect your program's input and/or output using shell
+redirection with the @code{run} command.  For example,
+
+@example
+run > outfile
+@end example
+
+@noindent
+starts your program, diverting its output to the file @file{outfile}.
+
+@kindex tty
+@cindex controlling terminal
+Another way to specify where your program should do input and output is
+with the @code{tty} command.  This command accepts a file name as
+argument, and causes this file to be the default for future @code{run}
+commands.  It also resets the controlling terminal for the child
+process, for future @code{run} commands.  For example,
+
+@example
+tty /dev/ttyb
+@end example
+
+@noindent
+directs that processes started with subsequent @code{run} commands
+default to do input and output on the terminal @file{/dev/ttyb} and have
+that as their controlling terminal.
+
+An explicit redirection in @code{run} overrides the @code{tty} command's
+effect on the input/output device, but not its effect on the controlling
+terminal.
+
+When you use the @code{tty} command or redirect input in the @code{run}
+command, only the input @emph{for your program} is affected.  The input
+for @value{GDBN} still comes from your terminal.
+
+@node Attach, Kill Process, Input/Output, Running
+@section Debugging an already-running process
+@kindex attach
+@cindex attach
+
+@table @code
+@item attach @var{process-id}
+This command attaches to a running process---one that was started
+outside @value{GDBN}.  (@code{info files} shows your active
+targets.)  The command takes as argument a process ID.  The usual way to
+find out the process-id of a Unix process is with the @code{ps} utility,
+or with the @samp{jobs -l} shell command.
+
+@code{attach} does not repeat if you press @key{RET} a second time after
+executing the command.
+@end table
+
+To use @code{attach}, your program must be running in an environment
+which supports processes; for example, @code{attach} does not work for
+programs on bare-board targets that lack an operating system.  You must
+also have permission to send the process a signal.
+
+When you use @code{attach}, the debugger finds the program running in
+the process first by looking in the current working directory, then (if
+the program is not found) by using the source file search path
+(@pxref{Source Path, ,Specifying source directories}).  You can also use
+the @code{file} command to load the program.  @xref{Files, ,Commands to
+Specify Files}.
+
+The first thing @value{GDBN} does after arranging to debug the specified
+process is to stop it.  You can examine and modify an attached process
+with all the @value{GDBN} commands that are ordinarily available when you start
+@ifclear HPPA
+processes with @code{run}.  You can insert breakpoints; you can step and
+@end ifclear
+@ifset HPPA
+processes with @code{run}.  You can insert breakpoints (except in shared
+libraries); you can step and
+@end ifset
+continue; you can modify storage.  If you would rather the process
+continue running, you may use the @code{continue} command after
+attaching @value{GDBN} to the process.
+
+@table @code
+@kindex detach
+@item detach
+When you have finished debugging the attached process, you can use the
+@code{detach} command to release it from @value{GDBN} control.  Detaching
+the process continues its execution.  After the @code{detach} command,
+that process and @value{GDBN} become completely independent once more, and you
+are ready to @code{attach} another process or start one with @code{run}.
+@code{detach} does not repeat if you press @key{RET} again after
+executing the command.
+@end table
+
+If you exit @value{GDBN} or use the @code{run} command while you have an
+attached process, you kill that process.  By default, @value{GDBN} asks
+for confirmation if you try to do either of these things; you can
+control whether or not you need to confirm by using the @code{set
+confirm} command (@pxref{Messages/Warnings, ,Optional warnings and
+messages}).
+
+@ifset HPPA
+@node Kill Process, Threads, Attach, Running
+@section Killing the child process
+@end ifset
+@ifclear HPPA
+@node Kill Process, Process Information, Attach, Running
+@section Killing the child process
+@end ifclear
+
+@table @code
+@kindex kill
+@item kill
+Kill the child process in which your program is running under @value{GDBN}.
+@end table
+
+This command is useful if you wish to debug a core dump instead of a
+running process.  @value{GDBN} ignores any core dump file while your program
+is running.
+
+On some operating systems, a program cannot be executed outside @value{GDBN}
+while you have breakpoints set on it inside @value{GDBN}.  You can use the
+@code{kill} command in this situation to permit running your program
+outside the debugger.
+
+The @code{kill} command is also useful if you wish to recompile and
+relink your program, since on many systems it is impossible to modify an
+executable file while it is running in a process.  In this case, when you
+next type @code{run}, @value{GDBN} notices that the file has changed, and
+reads the symbol table again (while trying to preserve your current
+breakpoint settings).
+
+@ifclear HPPA
+@node Process Information, Threads, Kill Process, Running
+@section Additional process information
+
+@kindex /proc
+@cindex process image
+Some operating systems provide a facility called @samp{/proc} that can
+be used to examine the image of a running process using file-system
+subroutines.  If @value{GDBN} is configured for an operating system with this
+facility, the command @code{info proc} is available to report on several
+kinds of information about the process running your program.  
+@code{info proc} works only on SVR4 systems that support @code{procfs}.
+
+@table @code
+@kindex info proc
+@item info proc
+Summarize available information about the process.
+
+@kindex info proc mappings
+@item info proc mappings
+Report on the address ranges accessible in the program, with information
+on whether your program may read, write, or execute each range.
+
+@kindex info proc times
+@item info proc times
+Starting time, user CPU time, and system CPU time for your program and
+its children.
+
+@kindex info proc id
+@item info proc id
+Report on the process IDs related to your program: its own process ID,
+the ID of its parent, the process group ID, and the session ID.
+
+@kindex info proc status
+@item info proc status
+General information on the state of the process.  If the process is
+stopped, this report includes the reason for stopping, and any signal
+received.
+
+@item info proc all
+Show all the above information about the process.
+@end table
+@end ifclear
+
+@ifset HPPA
+@node Threads, Processes, Kill Process, Running
+@section Debugging programs with multiple threads
+@end ifset
+@ifclear HPPA
+@node Threads, Processes, Process Information, Running
+@section Debugging programs with multiple threads
+@end ifclear
+
+@cindex threads of execution
+@cindex multiple threads
+@cindex switching threads
+In some operating systems, such as HP-UX and Solaris, a single program
+may have more than one @dfn{thread} of execution.  The precise semantics
+of threads differ from one operating system to another, but in general
+the threads of a single program are akin to multiple processes---except
+that they share one address space (that is, they can all examine and
+modify the same variables).  On the other hand, each thread has its own
+registers and execution stack, and perhaps private memory.
+
+@value{GDBN} provides these facilities for debugging multi-thread
+programs:
+
+@itemize @bullet
+@item automatic notification of new threads
+@item @samp{thread @var{threadno}}, a command to switch among threads
+@item @samp{info threads}, a command to inquire about existing threads
+@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}}, 
+a command to apply a command to a list of threads
+@item thread-specific breakpoints
+@end itemize
+
+@ifclear HPPA
+@quotation
+@emph{Warning:} These facilities are not yet available on every
+@value{GDBN} configuration where the operating system supports threads.
+If your @value{GDBN} does not support threads, these commands have no
+effect.  For example, a system without thread support shows no output
+from @samp{info threads}, and always rejects the @code{thread} command,
+like this:
+
+@smallexample
+(@value{GDBP}) info threads
+(@value{GDBP}) thread 1
+Thread ID 1 not known.  Use the "info threads" command to
+see the IDs of currently known threads.
+@end smallexample
+@c FIXME to implementors: how hard would it be to say "sorry, this GDB
+@c                        doesn't support threads"?
+@end quotation
+@end ifclear
+
+@cindex focus of debugging
+@cindex current thread
+The @value{GDBN} thread debugging facility allows you to observe all
+threads while your program runs---but whenever @value{GDBN} takes
+control, one thread in particular is always the focus of debugging.
+This thread is called the @dfn{current thread}.  Debugging commands show
+program information from the perspective of the current thread.
+
+@ifclear HPPA
+@kindex New @var{systag}
+@cindex thread identifier (system)
+@c FIXME-implementors!! It would be more helpful if the [New...] message
+@c included GDB's numeric thread handle, so you could just go to that
+@c thread without first checking `info threads'.
+Whenever @value{GDBN} detects a new thread in your program, it displays
+the target system's identification for the thread with a message in the
+form @samp{[New @var{systag}]}.  @var{systag} is a thread identifier
+whose form varies depending on the particular system.  For example, on
+LynxOS, you might see
+
+@example
+[New process 35 thread 27]
+@end example
+
+@noindent
+when @value{GDBN} notices a new thread.  In contrast, on an SGI system,
+the @var{systag} is simply something like @samp{process 368}, with no
+further qualifier.
+
+@c FIXME!! (1) Does the [New...] message appear even for the very first
+@c         thread of a program, or does it only appear for the
+@c         second---i.e., when it becomes obvious we have a multithread
+@c         program?
+@c         (2) *Is* there necessarily a first thread always?  Or do some
+@c         multithread systems permit starting a program with multiple
+@c         threads ab initio?      
+
+@cindex thread number
+@cindex thread identifier (GDB)
+For debugging purposes, @value{GDBN} associates its own thread
+number---always a single integer---with each thread in your program.
+
+@table @code
+@kindex info threads
+@item info threads
+Display a summary of all threads currently in your
+program.  @value{GDBN} displays for each thread (in this order):
+
+@enumerate
+@item the thread number assigned by @value{GDBN}
+
+@item the target system's thread identifier (@var{systag})
+
+@item the current stack frame summary for that thread
+@end enumerate
+
+@noindent
+An asterisk @samp{*} to the left of the @value{GDBN} thread number
+indicates the current thread.
+
+For example, 
+@end table
+@c end table here to get a little more width for example
+
+@smallexample
+(@value{GDBP}) info threads
+  3 process 35 thread 27  0x34e5 in sigpause ()
+  2 process 35 thread 23  0x34e5 in sigpause ()
+* 1 process 35 thread 13  main (argc=1, argv=0x7ffffff8)
+    at threadtest.c:68
+@end smallexample
+@end ifclear
+@ifset HPPA
+
+@cindex thread number
+@cindex thread identifier (GDB)
+For debugging purposes, @value{GDBN} associates its own thread
+number---a small integer assigned in thread-creation order---with each
+thread in your program.
+
+@kindex New @var{systag}
+@cindex thread identifier (system)
+@c FIXME-implementors!! It would be more helpful if the [New...] message
+@c included GDB's numeric thread handle, so you could just go to that
+@c thread without first checking `info threads'.
+Whenever @value{GDBN} detects a new thread in your program, it displays
+both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the
+form @samp{[New @var{systag}]}.  @var{systag} is a thread identifier
+whose form varies depending on the particular system.  For example, on
+HP-UX, you see
+
+@example
+[New thread 2 (system thread 26594)]
+@end example
+
+@noindent
+when @value{GDBN} notices a new thread. 
+
+@table @code
+@kindex info threads
+@item info threads
+Display a summary of all threads currently in your
+program.  @value{GDBN} displays for each thread (in this order):
+
+@enumerate
+@item the thread number assigned by @value{GDBN}
+
+@item the target system's thread identifier (@var{systag})
+
+@item the current stack frame summary for that thread
+@end enumerate
+
+@noindent
+An asterisk @samp{*} to the left of the @value{GDBN} thread number
+indicates the current thread.
+
+For example, 
+@end table
+@c end table here to get a little more width for example
+
+@example
+(@value{GDBP}) info threads
+    * 3 system thread 26607  worker (wptr=0x7b09c318 "@@") at quicksort.c:137
+      2 system thread 26606  0x7b0030d8 in __ksleep () from /usr/lib/libc.2
+      1 system thread 27905  0x7b003498 in _brk () from /usr/lib/libc.2
+@end example
+@end ifset
+
+@table @code
+@kindex thread @var{threadno}
+@item thread @var{threadno}
+Make thread number @var{threadno} the current thread.  The command
+argument @var{threadno} is the internal @value{GDBN} thread number, as
+shown in the first field of the @samp{info threads} display.
+@value{GDBN} responds by displaying the system identifier of the thread
+you selected, and its current stack frame summary:
+
+@smallexample
+@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one
+(@value{GDBP}) thread 2
+@ifclear HPPA
+[Switching to process 35 thread 23]
+@end ifclear
+@ifset HPPA
+[Switching to thread 2 (system thread 26594)]
+@end ifset
+0x34e5 in sigpause ()
+@end smallexample
+
+@noindent
+As with the @samp{[New @dots{}]} message, the form of the text after
+@samp{Switching to} depends on your system's conventions for identifying
+threads.  
+
+@kindex thread apply
+@item thread apply [@var{threadno}] [@var{all}]  @var{args}
+The @code{thread apply} command allows you to apply a command to one or
+more threads.  Specify the numbers of the threads that you want affected
+with the command argument @var{threadno}.  @var{threadno} is the internal
+@value{GDBN} thread number, as shown in the first field of the @samp{info
+threads} display.  To apply a command to all threads, use 
+@code{thread apply all} @var{args}. 
+@end table
+
+@cindex automatic thread selection
+@cindex switching threads automatically
+@cindex threads, automatic switching
+Whenever @value{GDBN} stops your program, due to a breakpoint or a
+signal, it automatically selects the thread where that breakpoint or
+signal happened.  @value{GDBN} alerts you to the context switch with a
+message of the form @samp{[Switching to @var{systag}]} to identify the
+thread.
+
+@xref{Thread Stops,,Stopping and starting multi-thread programs}, for
+more information about how @value{GDBN} behaves when you stop and start
+programs with multiple threads.
+
+@xref{Set Watchpoints,,Setting watchpoints}, for information about
+watchpoints in programs with multiple threads.
+@end ifclear
+
+@ifclear HPPA
+@node Processes,  , Threads, Running
+@section Debugging programs with multiple processes
+
+@cindex fork, debugging programs which call
+@cindex multiple processes
+@cindex processes, multiple
+@value{GDBN} has no special support for debugging programs which create
+additional processes using the @code{fork} function.  When a program
+forks, @value{GDBN} will continue to debug the parent process and the
+child process will run unimpeded.  If you have set a breakpoint in any
+code which the child then executes, the child will get a @code{SIGTRAP}
+signal which (unless it catches the signal) will cause it to terminate.
+
+However, if you want to debug the child process there is a workaround
+which isn't too painful.  Put a call to @code{sleep} in the code which
+the child process executes after the fork.  It may be useful to sleep
+only if a certain environment variable is set, or a certain file exists,
+so that the delay need not occur when you don't want to run @value{GDBN}
+on the child.  While the child is sleeping, use the @code{ps} program to
+get its process ID.  Then tell @value{GDBN} (a new invocation of
+@value{GDBN} if you are also debugging the parent process) to attach to
+the child process (see @ref{Attach}).  From that point on you can debug
+the child process just like any other process which you attached to.
+@end ifclear
+@ifset HPPA
+@node Processes,  , Threads, Running
+@section Debugging programs with multiple processes
+
+@cindex fork, debugging programs which call
+@cindex multiple processes
+@cindex processes, multiple
+
+@value{GDBN} provides support for debugging programs that create
+additional processes using the @code{fork} or @code{vfork} function.
+
+By default, when a program forks, @value{GDBN} will continue to debug
+the parent process and the child process will run unimpeded.
+
+If you want to follow the child process instead of the parent process,
+use the command @w{@code{set follow-fork-mode}}.
+
+@table @code
+@kindex set follow-fork-mode
+@item set follow-fork-mode @var{mode}
+Set the debugger response to a program call of @code{fork} or
+@code{vfork}.  A call to @code{fork} or @code{vfork} creates a new
+process.  The @var{mode} can be:
+
+@table @code
+@item parent
+The original process is debugged after a fork.  The child process runs
+unimpeded.
+
+@item child
+The new process is debugged after a fork.  The parent process runs
+unimpeded.
+
+@item ask
+The debugger will ask for one of the above choices.
+@end table
+
+@item show follow-fork-mode
+Display the current debugger response to a fork or vfork call.
+@end table
+
+If you ask to debug a child process and a @code{vfork} is followed by an
+@code{exec}, @value{GDBN} executes the new target up to the first
+breakpoint in the new target.  If you have a breakpoint set on
+@code{main} in your original program, the breakpoint will also be set on
+the child process's @code{main}.
+
+When a child process is spawned by @code{vfork}, you cannot debug the
+child or parent until an @code{exec} call completes.
+
+If you issue a @code{run} command to @value{GDBN} after an @code{exec}
+call executes, the new target restarts.  To restart the parent process,
+use the @code{file} command with the parent executable name as its
+argument.
+
+You can use the @code{catch} command to make @value{GDBN} stop whenever
+a @code{fork}, @code{vfork}, or @code{exec} call is made.  @xref{Set
+Catchpoints, ,Setting catchpoints}.
+@end ifset
+
+@node Stopping, Stack, Running, Top
+@chapter Stopping and Continuing
+
+The principal purposes of using a debugger are so that you can stop your
+program before it terminates; or so that, if your program runs into
+trouble, you can investigate and find out why.
+
+Inside @value{GDBN}, your program may stop for any of several reasons, such
+as
+@ifclear BARETARGET
+a signal,
+@end ifclear
+a breakpoint, or reaching a new line after a @value{GDBN}
+command such as @code{step}.  You may then examine and change
+variables, set new breakpoints or remove old ones, and then continue
+execution.  Usually, the messages shown by @value{GDBN} provide ample
+explanation of the status of your program---but you can also explicitly
+request this information at any time.
+
+@table @code
+@kindex info program
+@item info program
+Display information about the status of your program: whether it is
+running or not,
+@ifclear BARETARGET
+what process it is,
+@end ifclear
+and why it stopped.
+@end table
+
+@menu
+* Breakpoints::                 Breakpoints, watchpoints, and catchpoints
+* Continuing and Stepping::     Resuming execution
+@ifset POSIX
+* Signals::                     Signals
+@end ifset
+
+@ifclear BARETARGET
+* Thread Stops::                Stopping and starting multi-thread programs
+@end ifclear
+
+@end menu
+
+@node Breakpoints, Continuing and Stepping, Stopping, Stopping
+@section Breakpoints, watchpoints, and catchpoints
+
+@cindex breakpoints
+A @dfn{breakpoint} makes your program stop whenever a certain point in
+the program is reached.  For each breakpoint, you can add conditions to
+control in finer detail whether your program stops.  You can set
+breakpoints with the @code{break} command and its variants (@pxref{Set
+Breaks, ,Setting breakpoints}), to specify the place where your program
+should stop by line number, function name or exact address in the
+program.
+
+In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can set
+breakpoints in shared libraries before the executable is run.  There is
+a minor limitation on HP-UX systems: you must wait until the executable
+is run in order to set breakpoints in shared library routines that are
+not called directly by the program (for example, routines that are
+arguments in a @code{pthread_create} call).
+
+@cindex watchpoints
+@cindex memory tracing
+@cindex breakpoint on memory address
+@cindex breakpoint on variable modification
+A @dfn{watchpoint} is a special breakpoint that stops your program
+when the value of an expression changes.  You must use a different
+command to set watchpoints (@pxref{Set Watchpoints, ,Setting
+watchpoints}), but aside from that, you can manage a watchpoint like
+any other breakpoint: you enable, disable, and delete both breakpoints
+and watchpoints using the same commands.
+
+You can arrange to have values from your program displayed automatically
+whenever @value{GDBN} stops at a breakpoint.  @xref{Auto Display,,
+Automatic display}.
+
+@cindex catchpoints
+@cindex breakpoint on events
+A @dfn{catchpoint} is another special breakpoint that stops your program
+when a certain kind of event occurs, such as the throwing of a C++
+exception or the loading of a library.  As with watchpoints, you use a
+different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
+catchpoints}), but aside from that, you can manage a catchpoint like any
+other breakpoint.  (To stop when your program receives a signal, use the
+@code{handle} command; @pxref{Signals, ,Signals}.)
+
+@cindex breakpoint numbers
+@cindex numbers for breakpoints
+@value{GDBN} assigns a number to each breakpoint, watchpoint, or
+catchpoint when you create it; these numbers are successive integers
+starting with one.  In many of the commands for controlling various
+features of breakpoints you use the breakpoint number to say which
+breakpoint you want to change.  Each breakpoint may be @dfn{enabled} or
+@dfn{disabled}; if disabled, it has no effect on your program until you
+enable it again.
+
+@menu
+* Set Breaks::                  Setting breakpoints
+* Set Watchpoints::             Setting watchpoints
+* Set Catchpoints::             Setting catchpoints
+* Delete Breaks::               Deleting breakpoints
+* Disabling::                   Disabling breakpoints
+* Conditions::                  Break conditions
+* Break Commands::              Breakpoint command lists
+@ifclear CONLY
+* Breakpoint Menus::            Breakpoint menus
+@end ifclear
+
+@c  @ifclear BARETARGET
+@c  * Error in Breakpoints::        ``Cannot insert breakpoints''
+@c  @end ifclear
+@end menu
+
+@node Set Breaks, Set Watchpoints, Breakpoints, Breakpoints
+@subsection Setting breakpoints
+
+@c FIXME LMB what does GDB do if no code on line of breakpt?  
+@c       consider in particular declaration with/without initialization.
+@c
+@c FIXME 2 is there stuff on this already? break at fun start, already init?
+
+@kindex break
+@kindex b
+@kindex $bpnum
+@cindex latest breakpoint
+Breakpoints are set with the @code{break} command (abbreviated
+@code{b}).  The debugger convenience variable @samp{$bpnum} records the 
+number of the breakpoints you've set most recently; see @ref{Convenience
+Vars,, Convenience variables}, for a discussion of what you can do with
+convenience variables.
+
+You have several ways to say where the breakpoint should go.
+
+@table @code
+@item break @var{function}
+Set a breakpoint at entry to function @var{function}.  
+@ifclear CONLY
+When using source languages that permit overloading of symbols, such as
+C++, @var{function} may refer to more than one possible place to break.
+@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation.
+@end ifclear
+
+@item break +@var{offset}
+@itemx break -@var{offset}
+Set a breakpoint some number of lines forward or back from the position
+at which execution stopped in the currently selected frame.
+
+@item break @var{linenum}
+Set a breakpoint at line @var{linenum} in the current source file.
+That file is the last file whose source text was printed.  This
+breakpoint stops your program just before it executes any of the
+code on that line.
+
+@item break @var{filename}:@var{linenum}
+Set a breakpoint at line @var{linenum} in source file @var{filename}.
+
+@item break @var{filename}:@var{function}
+Set a breakpoint at entry to function @var{function} found in file
+@var{filename}.  Specifying a file name as well as a function name is
+superfluous except when multiple files contain similarly named
+functions.
+
+@item break *@var{address}
+Set a breakpoint at address @var{address}.  You can use this to set
+breakpoints in parts of your program which do not have debugging
+information or source files.
+
+@item break
+When called without any arguments, @code{break} sets a breakpoint at
+the next instruction to be executed in the selected stack frame
+(@pxref{Stack, ,Examining the Stack}).  In any selected frame but the
+innermost, this makes your program stop as soon as control
+returns to that frame.  This is similar to the effect of a
+@code{finish} command in the frame inside the selected frame---except
+that @code{finish} does not leave an active breakpoint.  If you use
+@code{break} without an argument in the innermost frame, @value{GDBN} stops
+the next time it reaches the current location; this may be useful
+inside loops.
+
+@value{GDBN} normally ignores breakpoints when it resumes execution, until at
+least one instruction has been executed.  If it did not do this, you
+would be unable to proceed past a breakpoint without first disabling the
+breakpoint.  This rule applies whether or not the breakpoint already
+existed when your program stopped.
+
+@item break @dots{} if @var{cond}
+Set a breakpoint with condition @var{cond}; evaluate the expression
+@var{cond} each time the breakpoint is reached, and stop only if the
+value is nonzero---that is, if @var{cond} evaluates as true.
+@samp{@dots{}} stands for one of the possible arguments described
+above (or no argument) specifying where to break.  @xref{Conditions,
+,Break conditions}, for more information on breakpoint conditions.
+
+@kindex tbreak
+@item tbreak @var{args}
+Set a breakpoint enabled only for one stop.  @var{args} are the
+same as for the @code{break} command, and the breakpoint is set in the same
+way, but the breakpoint is automatically deleted after the first time your
+program stops there.  @xref{Disabling, ,Disabling breakpoints}.
+
+@ifclear HPPA
+@kindex hbreak
+@item hbreak @var{args}
+Set a hardware-assisted breakpoint.  @var{args} are the same as for the 
+@code{break} command and the breakpoint is set in the same way, but the 
+breakpoint requires hardware support and some target hardware may not
+have this support.  The main purpose of this is EPROM/ROM code
+debugging, so you can set a breakpoint at an instruction without 
+changing the instruction.  This can be used with the new trap-generation 
+provided by SPARClite DSU.  DSU will generate traps when a program accesses
+some data or instruction address that is assigned to the debug registers.  
+However the hardware breakpoint registers can only take two data breakpoints,
+and @value{GDBN} will reject this command if more than two are used.  
+Delete or disable unused hardware breakpoints before setting
+new ones.  @xref{Conditions, ,Break conditions}.
+
+@kindex thbreak
+@item thbreak @var{args}
+Set a hardware-assisted breakpoint enabled only for one stop.  @var{args}
+are the same as for the @code{hbreak} command and the breakpoint is set in
+the same way.  However, like the @code{tbreak} command,  
+the breakpoint is automatically deleted after the
+first time your program stops there.  Also, like the @code{hbreak}
+command, the breakpoint requires hardware support and some target hardware 
+may not have this support.  @xref{Disabling, ,Disabling breakpoints}.  
+Also @xref{Conditions, ,Break conditions}.
+@end ifclear
+
+@kindex rbreak
+@cindex regular expression
+@item rbreak @var{regex}
+@c FIXME what kind of regexp?
+Set breakpoints on all functions matching the regular expression
+@var{regex}.  This command
+sets an unconditional breakpoint on all matches, printing a list of all
+breakpoints it set.  Once these breakpoints are set, they are treated
+just like the breakpoints set with the @code{break} command.  You can
+delete them, disable them, or make them conditional the same way as any
+other breakpoint.
+
+@ifclear CONLY
+When debugging C++ programs, @code{rbreak} is useful for setting
+breakpoints on overloaded functions that are not members of any special
+classes.
+@end ifclear
+
+@kindex info breakpoints
+@cindex @code{$_} and @code{info breakpoints}
+@item info breakpoints @r{[}@var{n}@r{]}
+@itemx info break @r{[}@var{n}@r{]}
+@itemx info watchpoints @r{[}@var{n}@r{]}
+Print a table of all breakpoints, watchpoints, and catchpoints set and
+not deleted, with the following columns for each breakpoint:
+
+@table @emph
+@item Breakpoint Numbers
+@item Type
+Breakpoint, watchpoint, or catchpoint.
+@item Disposition
+Whether the breakpoint is marked to be disabled or deleted when hit.
+@item Enabled or Disabled
+Enabled breakpoints are marked with @samp{y}.  @samp{n} marks breakpoints
+that are not enabled.
+@item Address
+Where the breakpoint is in your program, as a memory address
+@item What
+Where the breakpoint is in the source for your program, as a file and
+line number.
+@end table
+
+@noindent
+If a breakpoint is conditional, @code{info break} shows the condition on
+the line following the affected breakpoint; breakpoint commands, if any,
+are listed after that.
+
+@noindent
+@code{info break} with a breakpoint
+number @var{n} as argument lists only that breakpoint.  The
+convenience variable @code{$_} and the default examining-address for
+the @code{x} command are set to the address of the last breakpoint
+listed (@pxref{Memory, ,Examining memory}).  
+
+@noindent
+@code{info break} displays a count of the number of times the breakpoint
+has been hit.  This is especially useful in conjunction with the
+@code{ignore} command.  You can ignore a large number of breakpoint
+hits, look at the breakpoint info to see how many times the breakpoint
+was hit, and then run again, ignoring one less than that number.  This
+will get you quickly to the last hit of that breakpoint.
+@end table
+
+@value{GDBN} allows you to set any number of breakpoints at the same place in
+your program.  There is nothing silly or meaningless about this.  When
+the breakpoints are conditional, this is even useful
+(@pxref{Conditions, ,Break conditions}).
+
+@cindex negative breakpoint numbers
+@cindex internal @value{GDBN} breakpoints
+@value{GDBN} itself sometimes sets breakpoints in your program for special
+purposes, such as proper handling of @code{longjmp} (in C programs).
+These internal breakpoints are assigned negative numbers, starting with
+@code{-1}; @samp{info breakpoints} does not display them.
+
+You can see these breakpoints with the @value{GDBN} maintenance command
+@samp{maint info breakpoints}.
+
+@table @code
+@kindex maint info breakpoints
+@item maint info breakpoints
+Using the same format as @samp{info breakpoints}, display both the
+breakpoints you've set explicitly, and those @value{GDBN} is using for
+internal purposes.  Internal breakpoints are shown with negative
+breakpoint numbers.  The type column identifies what kind of breakpoint
+is shown:
+
+@table @code
+@item breakpoint
+Normal, explicitly set breakpoint.
+
+@item watchpoint
+Normal, explicitly set watchpoint.
+
+@item longjmp
+Internal breakpoint, used to handle correctly stepping through
+@code{longjmp} calls.
+
+@item longjmp resume
+Internal breakpoint at the target of a @code{longjmp}.
+
+@item until
+Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
+
+@item finish
+Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
+
+@ifset HPPA
+@item shlib events
+Shared library events.
+@end ifset
+@end table
+@end table
+
+
+@node Set Watchpoints, Set Catchpoints, Set Breaks, Breakpoints
+@subsection Setting watchpoints
+
+@cindex setting watchpoints
+@cindex software watchpoints
+@cindex hardware watchpoints
+You can use a watchpoint to stop execution whenever the value of an
+expression changes, without having to predict a particular place where
+this may happen.
+
+Depending on your system, watchpoints may be implemented in software or
+hardware.  GDB does software watchpointing by single-stepping your
+program and testing the variable's value each time, which is hundreds of
+times slower than normal execution.  (But this may still be worth it, to
+catch errors where you have no clue what part of your program is the
+culprit.)
+
+On some systems, such as HP-UX and Linux, GDB includes support for
+hardware watchpoints, which do not slow down the running of your
+program.
+
+@table @code
+@kindex watch
+@item watch @var{expr}
+Set a watchpoint for an expression.  @value{GDBN} will break when @var{expr}
+is written into by the program and its value changes.
+
+@kindex rwatch
+@item rwatch @var{expr}
+Set a watchpoint that will break when watch @var{expr} is read by the program.
+If you use both watchpoints, both must be set with the @code{rwatch}
+command.
+
+@kindex awatch
+@item awatch @var{expr}
+Set a watchpoint that will break when @var{args} is read and written into
+by the program.  If you use both watchpoints, both must be set with the
+@code{awatch} command.
+
+@kindex info watchpoints
+@item info watchpoints
+This command prints a list of watchpoints, breakpoints, and catchpoints;
+it is the same as @code{info break}.
+@end table
+
+@value{GDBN} sets a @dfn{hardware watchpoint} if possible.  Hardware
+watchpoints execute very quickly, and the debugger reports a change in
+value at the exact instruction where the change occurs.  If @value{GDBN}
+cannot set a hardware watchpoint, it sets a software watchpoint, which
+executes more slowly and reports the change in value at the next
+statement, not the instruction, after the change occurs.
+
+When you issue the @code{watch} command, @value{GDBN} reports
+
+@example
+Hardware watchpoint @var{num}: @var{expr}
+@end example
+
+@noindent
+if it was able to set a hardware watchpoint.
+
+The SPARClite DSU will generate traps when a program accesses
+some data or instruction address that is assigned to the debug registers.  
+For the data addresses, DSU facilitates the @code{watch} command.
+However the hardware breakpoint registers can only take two data watchpoints,
+and both watchpoints must be the same kind.  For example, you can set two
+watchpoints with @code{watch} commands, two with @code{rwatch}
+commands, @strong{or} two with @code{awatch} commands, but you cannot set one
+watchpoint with one command and the other with a different command. 
+@value{GDBN} will reject the command if you try to mix watchpoints.
+Delete or disable unused watchpoint commands before setting new ones.
+
+If you call a function interactively using @code{print} or @code{call},
+any watchpoints you have set will be inactive until GDB reaches another
+kind of breakpoint or the call completes.
+
+@ifclear BARETARGET
+@quotation
+@cindex watchpoints and threads
+@cindex threads and watchpoints
+@ifclear HPPA
+@emph{Warning:} In multi-thread programs, watchpoints have only limited
+usefulness.  With the current watchpoint implementation, @value{GDBN}
+can only watch the value of an expression @emph{in a single thread}.  If
+you are confident that the expression can only change due to the current
+thread's activity (and if you are also confident that no other thread
+can become current), then you can use watchpoints as usual.  However,
+@value{GDBN} may not notice when a non-current thread's activity changes
+the expression.
+@end ifclear
+@ifset HPPA
+@emph{Warning:} In multi-thread programs, software watchpoints have only
+limited usefulness.  If @value{GDBN} creates a software watchpoint, it
+can only watch the value of an expression @emph{in a single thread}.  If
+you are confident that the expression can only change due to the current
+thread's activity (and if you are also confident that no other thread
+can become current), then you can use software watchpoints as usual.
+However, @value{GDBN} may not notice when a non-current thread's
+activity changes the expression.  (Hardware watchpoints, in contrast,
+watch an expression in all threads.)
+@end ifset
+@end quotation
+@end ifclear
+
+@node Set Catchpoints, Delete Breaks, Set Watchpoints, Breakpoints
+@subsection Setting catchpoints
+@cindex catchpoints
+@cindex exception handlers
+@cindex event handling
+
+You can use @dfn{catchpoints} to cause the debugger to stop for certain
+kinds of program events, such as C++ exceptions or the loading of a
+shared library.  Use the @code{catch} command to set a catchpoint.
+
+@table @code
+@kindex catch
+@item catch @var{event}
+Stop when @var{event} occurs.  @var{event} can be any of the following:
+@table @code
+@item throw
+@kindex catch throw
+The throwing of a C++ exception.
+
+@item catch
+@kindex catch catch
+The catching of a C++ exception.
+
+@item exec
+@kindex catch exec
+A call to @code{exec}.  This is currently only available for HP-UX.
+
+@item fork
+@kindex catch fork
+A call to @code{fork}.  This is currently only available for HP-UX.
+
+@item vfork
+@kindex catch vfork
+A call to @code{vfork}.  This is currently only available for HP-UX.
+
+@item load
+@itemx load @var{libname}
+@kindex catch load
+The dynamic loading of any shared library, or the loading of the library
+@var{libname}.  This is currently only available for HP-UX.
+
+@item unload
+@itemx unload @var{libname}
+@kindex catch unload
+The unloading of any dynamically loaded shared library, or the unloading
+of the library @var{libname}.  This is currently only available for HP-UX.
+@end table
+
+@item tcatch @var{event}
+Set a catchpoint that is enabled only for one stop.  The catchpoint is
+automatically deleted after the first time the event is caught.
+
+@end table
+
+Use the @code{info break} command to list the current catchpoints.
+
+There are currently some limitations to C++ exception handling
+(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
+
+@itemize @bullet
+@item
+If you call a function interactively, @value{GDBN} normally returns
+control to you when the function has finished executing.  If the call
+raises an exception, however, the call may bypass the mechanism that
+returns control to you and cause your program either to abort or to
+simply continue running until it hits a breakpoint, catches a signal
+that @value{GDBN} is listening for, or exits.  This is the case even if
+you set a catchpoint for the exception; catchpoints on exceptions are
+disabled within interactive calls.
+
+@item
+You cannot raise an exception interactively.
+
+@item
+You cannot install an exception handler interactively.
+@end itemize
+
+@cindex raise exceptions
+Sometimes @code{catch} is not the best way to debug exception handling:
+if you need to know exactly where an exception is raised, it is better to
+stop @emph{before} the exception handler is called, since that way you
+can see the stack before any unwinding takes place.  If you set a
+breakpoint in an exception handler instead, it may not be easy to find
+out where the exception was raised.
+
+To stop just before an exception handler is called, you need some
+knowledge of the implementation.  In the case of @sc{gnu} C++, exceptions are
+raised by calling a library function named @code{__raise_exception}
+which has the following ANSI C interface:
+
+@example
+    /* @var{addr} is where the exception identifier is stored.
+       ID is the exception identifier.  */
+    void __raise_exception (void **@var{addr}, void *@var{id});
+@end example
+
+@noindent
+To make the debugger catch all exceptions before any stack
+unwinding takes place, set a breakpoint on @code{__raise_exception}
+(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}).
+
+With a conditional breakpoint (@pxref{Conditions, ,Break conditions})
+that depends on the value of @var{id}, you can stop your program when
+a specific exception is raised.  You can use multiple conditional
+breakpoints to stop your program when any of a number of exceptions are
+raised.
+
+
+@node Delete Breaks, Disabling, Set Catchpoints, Breakpoints
+@subsection Deleting breakpoints
+
+@cindex clearing breakpoints, watchpoints, catchpoints
+@cindex deleting breakpoints, watchpoints, catchpoints
+It is often necessary to eliminate a breakpoint, watchpoint, or
+catchpoint once it has done its job and you no longer want your program
+to stop there.  This is called @dfn{deleting} the breakpoint.  A
+breakpoint that has been deleted no longer exists; it is forgotten.
+
+With the @code{clear} command you can delete breakpoints according to
+where they are in your program.  With the @code{delete} command you can
+delete individual breakpoints, watchpoints, or catchpoints by specifying
+their breakpoint numbers.
+
+It is not necessary to delete a breakpoint to proceed past it.  @value{GDBN}
+automatically ignores breakpoints on the first instruction to be executed
+when you continue execution without changing the execution address.
+
+@table @code
+@kindex clear
+@item clear
+Delete any breakpoints at the next instruction to be executed in the
+selected stack frame (@pxref{Selection, ,Selecting a frame}).  When
+the innermost frame is selected, this is a good way to delete a
+breakpoint where your program just stopped.
+
+@item clear @var{function}
+@itemx clear @var{filename}:@var{function}
+Delete any breakpoints set at entry to the function @var{function}.
+
+@item clear @var{linenum}
+@itemx clear @var{filename}:@var{linenum}
+Delete any breakpoints set at or within the code of the specified line.
+
+@cindex delete breakpoints
+@kindex delete
+@kindex d
+@item delete @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
+Delete the breakpoints, watchpoints, or catchpoints of the numbers
+specified as arguments.  If no argument is specified, delete all
+breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
+confirm off}).  You can abbreviate this command as @code{d}.
+@end table
+
+@node Disabling, Conditions, Delete Breaks, Breakpoints
+@subsection Disabling breakpoints
+
+@kindex disable breakpoints
+@kindex enable breakpoints
+Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
+prefer to @dfn{disable} it.  This makes the breakpoint inoperative as if
+it had been deleted, but remembers the information on the breakpoint so
+that you can @dfn{enable} it again later.
+
+You disable and enable breakpoints, watchpoints, and catchpoints with
+the @code{enable} and @code{disable} commands, optionally specifying one
+or more breakpoint numbers as arguments.  Use @code{info break} or
+@code{info watch} to print a list of breakpoints, watchpoints, and
+catchpoints if you do not know which numbers to use.
+
+A breakpoint, watchpoint, or catchpoint can have any of four different
+states of enablement:
+
+@itemize @bullet
+@item
+Enabled.  The breakpoint stops your program.  A breakpoint set
+with the @code{break} command starts out in this state.
+@item
+Disabled.  The breakpoint has no effect on your program.
+@item
+Enabled once.  The breakpoint stops your program, but then becomes
+disabled.  A breakpoint set with the @code{tbreak} command starts out in
+this state.
+@item
+Enabled for deletion.  The breakpoint stops your program, but
+immediately after it does so it is deleted permanently.
+@end itemize
+
+You can use the following commands to enable or disable breakpoints,
+watchpoints, and catchpoints:
+
+@table @code
+@kindex disable breakpoints
+@kindex disable
+@kindex dis
+@item disable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
+Disable the specified breakpoints---or all breakpoints, if none are
+listed.  A disabled breakpoint has no effect but is not forgotten.  All
+options such as ignore-counts, conditions and commands are remembered in
+case the breakpoint is enabled again later.  You may abbreviate
+@code{disable} as @code{dis}.
+
+@kindex enable breakpoints
+@kindex enable
+@item enable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
+Enable the specified breakpoints (or all defined breakpoints).  They
+become effective once again in stopping your program.
+
+@item enable @r{[}breakpoints@r{]} once @var{bnums}@dots{}
+Enable the specified breakpoints temporarily.  @value{GDBN} disables any
+of these breakpoints immediately after stopping your program.
+
+@item enable @r{[}breakpoints@r{]} delete @var{bnums}@dots{}
+Enable the specified breakpoints to work once, then die.  @value{GDBN}
+deletes any of these breakpoints as soon as your program stops there.
+@end table
+
+Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
+,Setting breakpoints}), breakpoints that you set are initially enabled;
+subsequently, they become disabled or enabled only when you use one of
+the commands above.  (The command @code{until} can set and delete a
+breakpoint of its own, but it does not change the state of your other
+breakpoints; see @ref{Continuing and Stepping, ,Continuing and
+stepping}.)
+
+@node Conditions, Break Commands, Disabling, Breakpoints
+@subsection Break conditions
+@cindex conditional breakpoints
+@cindex breakpoint conditions
+
+@c FIXME what is scope of break condition expr?  Context where wanted?
+@c      in particular for a watchpoint?  
+The simplest sort of breakpoint breaks every time your program reaches a
+specified place.  You can also specify a @dfn{condition} for a
+breakpoint.  A condition is just a Boolean expression in your
+programming language (@pxref{Expressions, ,Expressions}).  A breakpoint with
+a condition evaluates the expression each time your program reaches it,
+and your program stops only if the condition is @emph{true}.
+
+This is the converse of using assertions for program validation; in that
+situation, you want to stop when the assertion is violated---that is,
+when the condition is false.  In C, if you want to test an assertion expressed
+by the condition @var{assert}, you should set the condition
+@samp{! @var{assert}} on the appropriate breakpoint.
+
+Conditions are also accepted for watchpoints; you may not need them,
+since a watchpoint is inspecting the value of an expression anyhow---but
+it might be simpler, say, to just set a watchpoint on a variable name,
+and specify a condition that tests whether the new value is an interesting
+one.
+
+Break conditions can have side effects, and may even call functions in
+your program.  This can be useful, for example, to activate functions
+that log program progress, or to use your own print functions to
+format special data structures. The effects are completely predictable
+unless there is another enabled breakpoint at the same address.  (In
+that case, @value{GDBN} might see the other breakpoint first and stop your
+program without checking the condition of this one.)  Note that
+breakpoint commands are usually more convenient and flexible for the
+purpose of performing side effects when a breakpoint is reached
+(@pxref{Break Commands, ,Breakpoint command lists}).
+
+Break conditions can be specified when a breakpoint is set, by using
+@samp{if} in the arguments to the @code{break} command.  @xref{Set
+Breaks, ,Setting breakpoints}.  They can also be changed at any time
+with the @code{condition} command.
+@ifclear HPPA
+@c The watch command now seems to recognize the if keyword.
+@c catch doesn't, though.
+The @code{watch} command does not recognize the @code{if} keyword;
+@code{condition} is the only way to impose a further condition on a
+watchpoint.
+@end ifclear
+@ifset HPPA
+You can also use the @code{if} keyword with the @code{watch} command.
+The @code{catch} command does not recognize the @code{if} keyword;
+@code{condition} is the only way to impose a further condition on a
+catchpoint.
+@end ifset
+
+@table @code
+@kindex condition
+@item condition @var{bnum} @var{expression}
+Specify @var{expression} as the break condition for breakpoint,
+watchpoint, or catchpoint number @var{bnum}.  After you set a condition,
+breakpoint @var{bnum} stops your program only if the value of
+@var{expression} is true (nonzero, in C).  When you use
+@code{condition}, @value{GDBN} checks @var{expression} immediately for
+syntactic correctness, and to determine whether symbols in it have
+referents in the context of your breakpoint.
+@c FIXME so what does GDB do if there is no referent?  Moreover, what
+@c about watchpoints?
+@value{GDBN} does
+not actually evaluate @var{expression} at the time the @code{condition}
+command is given, however.  @xref{Expressions, ,Expressions}.
+
+@item condition @var{bnum}
+Remove the condition from breakpoint number @var{bnum}.  It becomes
+an ordinary unconditional breakpoint.
+@end table
+
+@cindex ignore count (of breakpoint)
+A special case of a breakpoint condition is to stop only when the
+breakpoint has been reached a certain number of times.  This is so
+useful that there is a special way to do it, using the @dfn{ignore
+count} of the breakpoint.  Every breakpoint has an ignore count, which
+is an integer.  Most of the time, the ignore count is zero, and
+therefore has no effect.  But if your program reaches a breakpoint whose
+ignore count is positive, then instead of stopping, it just decrements
+the ignore count by one and continues.  As a result, if the ignore count
+value is @var{n}, the breakpoint does not stop the next @var{n} times
+your program reaches it.
+
+@table @code
+@kindex ignore
+@item ignore @var{bnum} @var{count}
+Set the ignore count of breakpoint number @var{bnum} to @var{count}.
+The next @var{count} times the breakpoint is reached, your program's
+execution does not stop; other than to decrement the ignore count, @value{GDBN}
+takes no action.
+
+To make the breakpoint stop the next time it is reached, specify
+a count of zero.
+
+When you use @code{continue} to resume execution of your program from a
+breakpoint, you can specify an ignore count directly as an argument to
+@code{continue}, rather than using @code{ignore}.  @xref{Continuing and
+Stepping,,Continuing and stepping}.
+
+If a breakpoint has a positive ignore count and a condition, the
+condition is not checked.  Once the ignore count reaches zero,
+@value{GDBN} resumes checking the condition.
+
+You could achieve the effect of the ignore count with a condition such
+as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
+is decremented each time.  @xref{Convenience Vars, ,Convenience
+variables}.
+@end table
+
+Ignore counts apply to breakpoints, watchpoints, and catchpoints.
+
+
+@node Break Commands, Breakpoint Menus, Conditions, Breakpoints
+@subsection Breakpoint command lists
+
+@cindex breakpoint commands
+You can give any breakpoint (or watchpoint or catchpoint) a series of
+commands to execute when your program stops due to that breakpoint.  For
+example, you might want to print the values of certain expressions, or
+enable other breakpoints.
+
+@table @code
+@kindex commands
+@kindex end
+@item commands @r{[}@var{bnum}@r{]}
+@itemx @dots{} @var{command-list} @dots{}
+@itemx end
+Specify a list of commands for breakpoint number @var{bnum}.  The commands
+themselves appear on the following lines.  Type a line containing just
+@code{end} to terminate the commands.
+
+To remove all commands from a breakpoint, type @code{commands} and
+follow it immediately with @code{end}; that is, give no commands.
+
+With no @var{bnum} argument, @code{commands} refers to the last
+breakpoint, watchpoint, or catchpoint set (not to the breakpoint most
+recently encountered).
+@end table
+
+Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
+disabled within a @var{command-list}.
+
+You can use breakpoint commands to start your program up again.  Simply
+use the @code{continue} command, or @code{step}, or any other command
+that resumes execution.
+
+Any other commands in the command list, after a command that resumes
+execution, are ignored.  This is because any time you resume execution
+(even with a simple @code{next} or @code{step}), you may encounter
+another breakpoint---which could have its own command list, leading to
+ambiguities about which list to execute.
+
+@kindex silent
+If the first command you specify in a command list is @code{silent}, the
+usual message about stopping at a breakpoint is not printed.  This may
+be desirable for breakpoints that are to print a specific message and
+then continue.  If none of the remaining commands print anything, you
+see no sign that the breakpoint was reached.  @code{silent} is
+meaningful only at the beginning of a breakpoint command list.
+
+The commands @code{echo}, @code{output}, and @code{printf} allow you to
+print precisely controlled output, and are often useful in silent
+breakpoints.  @xref{Output, ,Commands for controlled output}.
+
+For example, here is how you could use breakpoint commands to print the
+value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
+
+@example
+break foo if x>0
+commands
+silent
+printf "x is %d\n",x
+cont
+end
+@end example
+
+One application for breakpoint commands is to compensate for one bug so
+you can test for another.  Put a breakpoint just after the erroneous line
+of code, give it a condition to detect the case in which something
+erroneous has been done, and give it commands to assign correct values
+to any variables that need them.  End with the @code{continue} command
+so that your program does not stop, and start with the @code{silent}
+command so that no output is produced.  Here is an example:
+
+@example
+break 403
+commands
+silent
+set x = y + 4
+cont
+end
+@end example
+
+@ifclear CONLY
+@node Breakpoint Menus,  , Break Commands, Breakpoints
+@subsection Breakpoint menus
+@cindex overloading
+@cindex symbol overloading
+
+Some programming languages (notably C++) permit a single function name
+to be defined several times, for application in different contexts.
+This is called @dfn{overloading}.  When a function name is overloaded,
+@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
+a breakpoint.  If you realize this is a problem, you can use
+something like @samp{break @var{function}(@var{types})} to specify which
+particular version of the function you want.  Otherwise, @value{GDBN} offers
+you a menu of numbered choices for different possible breakpoints, and
+waits for your selection with the prompt @samp{>}.  The first two
+options are always @samp{[0] cancel} and @samp{[1] all}.  Typing @kbd{1}
+sets a breakpoint at each definition of @var{function}, and typing
+@kbd{0} aborts the @code{break} command without setting any new
+breakpoints.
+
+For example, the following session excerpt shows an attempt to set a
+breakpoint at the overloaded symbol @code{String::after}.
+We choose three particular definitions of that function name:
+
+@c FIXME! This is likely to change to show arg type lists, at least
+@smallexample
+@group
+(@value{GDBP}) b String::after
+[0] cancel
+[1] all
+[2] file:String.cc; line number:867
+[3] file:String.cc; line number:860
+[4] file:String.cc; line number:875
+[5] file:String.cc; line number:853
+[6] file:String.cc; line number:846
+[7] file:String.cc; line number:735
+> 2 4 6
+Breakpoint 1 at 0xb26c: file String.cc, line 867.
+Breakpoint 2 at 0xb344: file String.cc, line 875.
+Breakpoint 3 at 0xafcc: file String.cc, line 846.
+Multiple breakpoints were set.
+Use the "delete" command to delete unwanted
+ breakpoints.
+(@value{GDBP})
+@end group
+@end smallexample
+@end ifclear
+
+@c  @ifclear BARETARGET
+@c  @node Error in Breakpoints
+@c  @subsection ``Cannot insert breakpoints''
+@c
+@c  FIXME!! 14/6/95  Is there a real example of this?  Let's use it.
+@c
+@c  Under some operating systems, breakpoints cannot be used in a program if
+@c  any other process is running that program.  In this situation,
+@c  attempting to run or continue a program with a breakpoint causes 
+@c  @value{GDBN} to stop the other process.
+@c
+@c  When this happens, you have three ways to proceed:
+@c
+@c  @enumerate
+@c  @item
+@c  Remove or disable the breakpoints, then continue.
+@c
+@c  @item
+@c  Suspend @value{GDBN}, and copy the file containing your program to a new 
+@c  name.  Resume @value{GDBN} and use the @code{exec-file} command to specify
+@c  that @value{GDBN} should run your program under that name.  
+@c  Then start your program again.
+@c
+@c  @item
+@c  Relink your program so that the text segment is nonsharable, using the
+@c  linker option @samp{-N}.  The operating system limitation may not apply
+@c  to nonsharable executables.
+@c  @end enumerate
+@c  @end ifclear
+
+@node Continuing and Stepping, Signals, Breakpoints, Stopping
+@section Continuing and stepping
+
+@cindex stepping
+@cindex continuing
+@cindex resuming execution
+@dfn{Continuing} means resuming program execution until your program
+completes normally.  In contrast, @dfn{stepping} means executing just
+one more ``step'' of your program, where ``step'' may mean either one
+line of source code, or one machine instruction (depending on what
+particular command you use).  Either when continuing
+or when stepping, your program may stop even sooner, due to 
+@ifset BARETARGET
+a breakpoint.
+@end ifset
+@ifclear BARETARGET
+a breakpoint or a signal.  (If due to a signal, you may want to use
+@code{handle}, or use @samp{signal 0} to resume execution.
+@xref{Signals, ,Signals}.)
+@end ifclear
+
+@table @code
+@kindex continue
+@kindex c
+@kindex fg
+@item continue @r{[}@var{ignore-count}@r{]}
+@itemx c @r{[}@var{ignore-count}@r{]}
+@itemx fg @r{[}@var{ignore-count}@r{]}
+Resume program execution, at the address where your program last stopped;
+any breakpoints set at that address are bypassed.  The optional argument
+@var{ignore-count} allows you to specify a further number of times to
+ignore a breakpoint at this location; its effect is like that of
+@code{ignore} (@pxref{Conditions, ,Break conditions}).
+
+The argument @var{ignore-count} is meaningful only when your program
+stopped due to a breakpoint.  At other times, the argument to
+@code{continue} is ignored.
+
+The synonyms @code{c} and @code{fg} are provided purely for convenience,
+and have exactly the same behavior as @code{continue}.
+@end table
+
+To resume execution at a different place, you can use @code{return}
+(@pxref{Returning, ,Returning from a function}) to go back to the
+calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
+different address}) to go to an arbitrary location in your program.
+
+A typical technique for using stepping is to set a breakpoint
+(@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the
+beginning of the function or the section of your program where a problem
+is believed to lie, run your program until it stops at that breakpoint,
+and then step through the suspect area, examining the variables that are
+interesting, until you see the problem happen.
+
+@table @code
+@kindex step
+@kindex s
+@item step
+Continue running your program until control reaches a different source
+line, then stop it and return control to @value{GDBN}.  This command is
+abbreviated @code{s}.
+
+@quotation
+@c "without debugging information" is imprecise; actually "without line
+@c numbers in the debugging information".  (gcc -g1 has debugging info but
+@c not line numbers).  But it seems complex to try to make that
+@c distinction here.
+@emph{Warning:} If you use the @code{step} command while control is
+within a function that was compiled without debugging information,
+execution proceeds until control reaches a function that does have
+debugging information.  Likewise, it will not step into a function which
+is compiled without debugging information.  To step through functions
+without debugging information, use the @code{stepi} command, described
+below.
+@end quotation
+
+The @code{step} command now only stops at the first instruction of a
+source line.  This prevents the multiple stops that used to occur in
+switch statements, for loops, etc.  @code{step} continues to stop if a
+function that has debugging information is called within the line.
+
+Also, the @code{step} command now only enters a subroutine if there is line
+number information for the subroutine.  Otherwise it acts like the
+@code{next} command.  This avoids problems when using @code{cc -gl} 
+on MIPS machines.  Previously, @code{step} entered subroutines if there
+was any debugging information about the routine.  
+
+@item step @var{count}
+Continue running as in @code{step}, but do so @var{count} times.  If a
+breakpoint is reached,
+@ifclear BARETARGET
+or a signal not related to stepping occurs before @var{count} steps,
+@end ifclear
+stepping stops right away.
+
+@kindex next
+@kindex n
+@item next @r{[}@var{count}@r{]}
+Continue to the next source line in the current (innermost) stack frame.
+This is similar to @code{step}, but function calls that appear within the line
+of code are executed without stopping.  Execution stops when control
+reaches a different line of code at the original stack level that was 
+executing when you gave the @code{next} command.  This command is abbreviated
+@code{n}.
+
+An argument @var{count} is a repeat count, as for @code{step}.
+
+
+@c  FIX ME!!  Do we delete this, or is there a way it fits in with
+@c  the following paragraph?   ---  Vctoria
+@c
+@c  @code{next} within a function that lacks debugging information acts like
+@c  @code{step}, but any function calls appearing within the code of the
+@c  function are executed without stopping.
+
+The @code{next} command now only stops at the first instruction of a
+source line.  This prevents the multiple stops that used to occur in
+switch statements, for loops, etc. 
+
+@kindex finish
+@item finish
+Continue running until just after function in the selected stack frame
+returns.  Print the returned value (if any).
+
+Contrast this with the @code{return} command (@pxref{Returning,
+,Returning from a function}).
+
+@kindex until
+@kindex u
+@item until
+@itemx u
+Continue running until a source line past the current line, in the
+current stack frame, is reached.  This command is used to avoid single
+stepping through a loop more than once.  It is like the @code{next}
+command, except that when @code{until} encounters a jump, it
+automatically continues execution until the program counter is greater
+than the address of the jump.
+
+This means that when you reach the end of a loop after single stepping
+though it, @code{until} makes your program continue execution until it
+exits the loop.  In contrast, a @code{next} command at the end of a loop
+simply steps back to the beginning of the loop, which forces you to step
+through the next iteration.
+
+@code{until} always stops your program if it attempts to exit the current
+stack frame.
+
+@code{until} may produce somewhat counterintuitive results if the order
+of machine code does not match the order of the source lines.  For
+example, in the following excerpt from a debugging session, the @code{f}
+(@code{frame}) command shows that execution is stopped at line
+@code{206}; yet when we use @code{until}, we get to line @code{195}:
+
+@example
+(@value{GDBP}) f
+#0  main (argc=4, argv=0xf7fffae8) at m4.c:206
+206                 expand_input();
+(@value{GDBP}) until
+195             for ( ; argc > 0; NEXTARG) @{
+@end example
+
+This happened because, for execution efficiency, the compiler had
+generated code for the loop closure test at the end, rather than the
+start, of the loop---even though the test in a C @code{for}-loop is
+written before the body of the loop.  The @code{until} command appeared
+to step back to the beginning of the loop when it advanced to this
+expression; however, it has not really gone to an earlier
+statement---not in terms of the actual machine code.
+
+@code{until} with no argument works by means of single
+instruction stepping, and hence is slower than @code{until} with an
+argument.
+
+@item until @var{location}
+@itemx u @var{location}
+Continue running your program until either the specified location is
+reached, or the current stack frame returns.  @var{location} is any of
+the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
+,Setting breakpoints}).  This form of the command uses breakpoints,
+and hence is quicker than @code{until} without an argument.
+
+@kindex stepi
+@kindex si
+@item stepi
+@itemx si
+Execute one machine instruction, then stop and return to the debugger.
+
+It is often useful to do @samp{display/i $pc} when stepping by machine
+instructions.  This makes @value{GDBN} automatically display the next
+instruction to be executed, each time your program stops.  @xref{Auto
+Display,, Automatic display}.
+
+An argument is a repeat count, as in @code{step}.
+
+@need 750
+@kindex nexti
+@kindex ni
+@item nexti
+@itemx ni
+Execute one machine instruction, but if it is a function call,
+proceed until the function returns.
+
+An argument is a repeat count, as in @code{next}.
+@end table
+
+@ifset POSIX
+@node Signals, Thread Stops, Continuing and Stepping, Stopping
+@section Signals
+@cindex signals
+
+A signal is an asynchronous event that can happen in a program.  The
+operating system defines the possible kinds of signals, and gives each
+kind a name and a number.  For example, in Unix @code{SIGINT} is the
+signal a program gets when you type an interrupt (often @kbd{C-c});
+@code{SIGSEGV} is the signal a program gets from referencing a place in
+memory far away from all the areas in use; @code{SIGALRM} occurs when
+the alarm clock timer goes off (which happens only if your program has
+requested an alarm).
+
+@cindex fatal signals
+Some signals, including @code{SIGALRM}, are a normal part of the
+functioning of your program.  Others, such as @code{SIGSEGV}, indicate
+errors; these signals are @dfn{fatal} (kill your program immediately) if the
+program has not specified in advance some other way to handle the signal.
+@code{SIGINT} does not indicate an error in your program, but it is normally
+fatal so it can carry out the purpose of the interrupt: to kill the program.
+
+@value{GDBN} has the ability to detect any occurrence of a signal in your
+program.  You can tell @value{GDBN} in advance what to do for each kind of
+signal.
+
+@cindex handling signals
+Normally, @value{GDBN} is set up to ignore non-erroneous signals like @code{SIGALRM}
+(so as not to interfere with their role in the functioning of your program)
+but to stop your program immediately whenever an error signal happens.
+You can change these settings with the @code{handle} command.
+
+@table @code
+@kindex info signals
+@item info signals
+Print a table of all the kinds of signals and how @value{GDBN} has been told to
+handle each one.  You can use this to see the signal numbers of all
+the defined types of signals.
+
+@code{info handle} is the new alias for @code{info signals}.
+
+@kindex handle
+@item handle @var{signal} @var{keywords}@dots{}
+Change the way @value{GDBN} handles signal @var{signal}.  @var{signal} can 
+be the number of a signal or its name (with or without the @samp{SIG} at the
+beginning).  The @var{keywords} say what change to make.
+@end table
+
+@c @group
+The keywords allowed by the @code{handle} command can be abbreviated.
+Their full names are:
+
+@table @code
+@item nostop
+@value{GDBN} should not stop your program when this signal happens.  It may
+still print a message telling you that the signal has come in.
+
+@item stop
+@value{GDBN} should stop your program when this signal happens.  This implies
+the @code{print} keyword as well.
+
+@item print
+@value{GDBN} should print a message when this signal happens.
+
+@item noprint
+@value{GDBN} should not mention the occurrence of the signal at all.  This
+implies the @code{nostop} keyword as well.
+
+@item pass
+@value{GDBN} should allow your program to see this signal; your program
+can handle the signal, or else it may terminate if the signal is fatal
+and not handled.
+
+@item nopass
+@value{GDBN} should not allow your program to see this signal.
+@end table
+@c @end group
+
+When a signal stops your program, the signal is not visible until you
+continue.  Your program sees the signal then, if @code{pass} is in
+effect for the signal in question @emph{at that time}.  In other words,
+after @value{GDBN} reports a signal, you can use the @code{handle}
+command with @code{pass} or @code{nopass} to control whether your
+program sees that signal when you continue.
+
+You can also use the @code{signal} command to prevent your program from
+seeing a signal, or cause it to see a signal it normally would not see,
+or to give it any signal at any time.  For example, if your program stopped
+due to some sort of memory reference error, you might store correct
+values into the erroneous variables and continue, hoping to see more
+execution; but your program would probably terminate immediately as
+a result of the fatal signal once it saw the signal.  To prevent this,
+you can continue with @samp{signal 0}.  @xref{Signaling, ,Giving your
+program a signal}. 
+@end ifset
+
+@ifclear BARETARGET
+@node Thread Stops,  , Signals, Stopping
+@section Stopping and starting multi-thread programs
+
+When your program has multiple threads (@pxref{Threads,, Debugging
+programs with multiple threads}), you can choose whether to set
+breakpoints on all threads, or on a particular thread.
+
+@table @code
+@cindex breakpoints and threads
+@cindex thread breakpoints
+@kindex break @dots{} thread @var{threadno}
+@item break @var{linespec} thread @var{threadno}
+@itemx break @var{linespec} thread @var{threadno} if @dots{}
+@var{linespec} specifies source lines; there are several ways of
+writing them, but the effect is always to specify some source line.
+
+Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
+to specify that you only want @value{GDBN} to stop the program when a
+particular thread reaches this breakpoint.  @var{threadno} is one of the
+numeric thread identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info threads} display.
+
+If you do not specify @samp{thread @var{threadno}} when you set a
+breakpoint, the breakpoint applies to @emph{all} threads of your
+program.
+
+You can use the @code{thread} qualifier on conditional breakpoints as
+well; in this case, place @samp{thread @var{threadno}} before the
+breakpoint condition, like this:
+
+@smallexample
+(gdb) break frik.c:13 thread 28 if bartab > lim
+@end smallexample
+
+@end table
+
+@cindex stopped threads
+@cindex threads, stopped
+Whenever your program stops under @value{GDBN} for any reason,
+@emph{all} threads of execution stop, not just the current thread.  This
+allows you to examine the overall state of the program, including
+switching between threads, without worrying that things may change
+underfoot.
+
+@cindex continuing threads
+@cindex threads, continuing
+Conversely, whenever you restart the program, @emph{all} threads start
+executing.  @emph{This is true even when single-stepping} with commands
+like @code{step} or @code{next}.  
+
+In particular, @value{GDBN} cannot single-step all threads in lockstep.
+Since thread scheduling is up to your debugging target's operating
+system (not controlled by @value{GDBN}), other threads may
+execute more than one statement while the current thread completes a
+single step.  Moreover, in general other threads stop in the middle of a
+statement, rather than at a clean statement boundary, when the program
+stops.
+
+You might even find your program stopped in another thread after
+continuing or even single-stepping.  This happens whenever some other
+thread runs into a breakpoint, a signal, or an exception before the
+first thread completes whatever you requested.
+
+On some OSes, you can lock the OS scheduler and thus allow only a single
+thread to run.
+
+@table @code
+@item set scheduler-locking @var{mode}
+Set the scheduler locking mode.  If it is @code{off}, then there is no
+locking and any thread may run at any time.  If @code{on}, then only the
+current thread may run when the inferior is resumed.  The @code{step}
+mode optimizes for single-stepping.  It stops other threads from
+``seizing the prompt'' by preempting the current thread while you are
+stepping.  Other threads will only rarely (or never) get a chance to run
+when you step.  They are more likely to run when you ``next'' over a
+function call, and they are completely free to run when you use commands
+like ``continue'', ``until'', or ``finish''.  However, unless another
+thread hits a breakpoint during its timeslice, they will never steal the
+GDB prompt away from the thread that you are debugging.
+
+@item show scheduler-locking
+Display the current scheduler locking mode.
+@end table
+
+@end ifclear
+
+
+@node Stack, Source, Stopping, Top
+@chapter Examining the Stack
+
+When your program has stopped, the first thing you need to know is where it
+stopped and how it got there.
+
+@cindex call stack
+Each time your program performs a function call, information about the call 
+is generated. 
+That information includes the location of the call in your program, 
+the arguments of the call, 
+and the local variables of the function being called.
+The information is saved in a block of data called a @dfn{stack frame}.  
+The stack frames are allocated in a region of memory called the @dfn{call
+stack}.
+
+When your program stops, the @value{GDBN} commands for examining the
+stack allow you to see all of this information.
+
+@cindex selected frame
+One of the stack frames is @dfn{selected} by @value{GDBN} and many
+@value{GDBN} commands refer implicitly to the selected frame.  In
+particular, whenever you ask @value{GDBN} for the value of a variable in
+your program, the value is found in the selected frame.  There are
+special @value{GDBN} commands to select whichever frame you are
+interested in. @xref{Selection, ,Selecting a frame}.
+
+When your program stops, @value{GDBN} automatically selects the
+currently executing frame and describes it briefly, similar to the 
+@code{frame} command (@pxref{Frame Info, ,Information about a frame}).
+
+@menu
+* Frames::                      Stack frames
+* Backtrace::                   Backtraces
+* Selection::                   Selecting a frame
+* Frame Info::                  Information on a frame
+* Alpha/MIPS Stack::            Alpha and MIPS machines and the function stack
+
+@end menu
+
+@node Frames, Backtrace, Stack, Stack
+@section Stack frames
+
+@cindex frame
+@cindex stack frame
+The call stack is divided up into contiguous pieces called @dfn{stack
+frames}, or @dfn{frames} for short; each frame is the data associated
+with one call to one function.  The frame contains the arguments given
+to the function, the function's local variables, and the address at
+which the function is executing.
+
+@cindex initial frame
+@cindex outermost frame
+@cindex innermost frame
+When your program is started, the stack has only one frame, that of the
+function @code{main}.  This is called the @dfn{initial} frame or the
+@dfn{outermost} frame.  Each time a function is called, a new frame is
+made.  Each time a function returns, the frame for that function invocation
+is eliminated.  If a function is recursive, there can be many frames for
+the same function.  The frame for the function in which execution is
+actually occurring is called the @dfn{innermost} frame.  This is the most
+recently created of all the stack frames that still exist.
+
+@cindex frame pointer
+Inside your program, stack frames are identified by their addresses.  A
+stack frame consists of many bytes, each of which has its own address; each
+kind of computer has a convention for choosing one byte whose
+address serves as the address of the frame.  Usually this address is kept
+in a register called the @dfn{frame pointer register} while execution is
+going on in that frame.
+
+@cindex frame number
+@value{GDBN} assigns numbers to all existing stack frames, starting with
+zero for the innermost frame, one for the frame that called it,
+and so on upward.  These numbers do not really exist in your program;
+they are assigned by @value{GDBN} to give you a way of designating stack
+frames in @value{GDBN} commands.
+
+@c below produces an acceptable overful hbox. --mew 13aug1993
+@cindex frameless execution
+Some compilers provide a way to compile functions so that they operate
+without stack frames.  (For example, the @code{@value{GCC}} option
+@samp{-fomit-frame-pointer} generates functions without a frame.)
+This is occasionally done with heavily used library functions to save
+the frame setup time.  @value{GDBN} has limited facilities for dealing
+with these function invocations.  If the innermost function invocation
+has no stack frame, @value{GDBN} nevertheless regards it as though
+it had a separate frame, which is numbered zero as usual, allowing
+correct tracing of the function call chain.  However, @value{GDBN} has
+no provision for frameless functions elsewhere in the stack.
+
+@table @code
+@kindex frame
+@item frame @var{args}
+The @code{frame} command allows you to move from one stack frame to another, 
+and to print the stack frame you select.  @var{args} may be either the
+address of the frame or the stack frame number.  Without an argument, 
+@code{frame} prints the current stack frame.  
+
+@kindex select-frame
+@item select-frame
+The @code{select-frame} command allows you to move from one stack frame
+to another without printing the frame.  This is the silent version of
+@code{frame}.
+@end table
+
+@node Backtrace, Selection, Frames, Stack
+@section Backtraces
+
+@cindex backtraces
+@cindex tracebacks
+@cindex stack traces
+A backtrace is a summary of how your program got where it is.  It shows one
+line per frame, for many frames, starting with the currently executing
+frame (frame zero), followed by its caller (frame one), and on up the
+stack.
+
+@table @code
+@kindex backtrace
+@kindex bt
+@item backtrace
+@itemx bt
+Print a backtrace of the entire stack: one line per frame for all
+frames in the stack.
+
+You can stop the backtrace at any time by typing the system interrupt
+character, normally @kbd{C-c}.
+
+@item backtrace @var{n}
+@itemx bt @var{n}
+Similar, but print only the innermost @var{n} frames.
+
+@item backtrace -@var{n}
+@itemx bt -@var{n}
+Similar, but print only the outermost @var{n} frames.
+@end table
+
+@kindex where
+@kindex info stack
+@kindex info s
+The names @code{where} and @code{info stack} (abbreviated @code{info s})
+are additional aliases for @code{backtrace}.
+
+Each line in the backtrace shows the frame number and the function name.
+The program counter value is also shown---unless you use @code{set
+print address off}.  The backtrace also shows the source file name and
+line number, as well as the arguments to the function.  The program
+counter value is omitted if it is at the beginning of the code for that
+line number.
+
+Here is an example of a backtrace.  It was made with the command
+@samp{bt 3}, so it shows the innermost three frames.
+
+@smallexample
+@group
+#0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 
+    at builtin.c:993
+#1  0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
+#2  0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
+    at macro.c:71
+(More stack frames follow...)
+@end group
+@end smallexample
+
+@noindent
+The display for frame zero does not begin with a program counter
+value, indicating that your program has stopped at the beginning of the
+code for line @code{993} of @code{builtin.c}.
+
+@node Selection, Frame Info, Backtrace, Stack
+@section Selecting a frame
+
+Most commands for examining the stack and other data in your program work on
+whichever stack frame is selected at the moment.  Here are the commands for
+selecting a stack frame; all of them finish by printing a brief description
+of the stack frame just selected.
+
+@table @code
+@kindex frame
+@kindex f
+@item frame @var{n}
+@itemx f @var{n}
+Select frame number @var{n}.  Recall that frame zero is the innermost
+(currently executing) frame, frame one is the frame that called the
+innermost one, and so on.  The highest-numbered frame is the one for
+@code{main}.
+
+@item frame @var{addr}
+@itemx f @var{addr}
+Select the frame at address @var{addr}.  This is useful mainly if the
+chaining of stack frames has been damaged by a bug, making it
+impossible for @value{GDBN} to assign numbers properly to all frames.  In
+addition, this can be useful when your program has multiple stacks and
+switches between them.
+
+@ifclear H8EXCLUSIVE
+@ifclear HPPA
+On the SPARC architecture, @code{frame} needs two addresses to
+select an arbitrary frame: a frame pointer and a stack pointer.
+
+On the MIPS and Alpha architecture, it needs two addresses: a stack
+pointer and a program counter.
+
+On the 29k architecture, it needs three addresses: a register stack
+pointer, a program counter, and a memory stack pointer.
+@c note to future updaters: this is conditioned on a flag
+@c SETUP_ARBITRARY_FRAME in the tm-*.h files.  The above is up to date
+@c as of 27 Jan 1994.
+@end ifclear
+@end ifclear
+
+@kindex up
+@item up @var{n}
+Move @var{n} frames up the stack.  For positive numbers @var{n}, this
+advances toward the outermost frame, to higher frame numbers, to frames
+that have existed longer.  @var{n} defaults to one.
+
+@kindex down
+@kindex do
+@item down @var{n}
+Move @var{n} frames down the stack.  For positive numbers @var{n}, this
+advances toward the innermost frame, to lower frame numbers, to frames
+that were created more recently.  @var{n} defaults to one.  You may
+abbreviate @code{down} as @code{do}.
+@end table
+
+All of these commands end by printing two lines of output describing the
+frame.  The first line shows the frame number, the function name, the
+arguments, and the source file and line number of execution in that
+frame.  The second line shows the text of that source line.  
+
+@need 1000
+For example:
+
+@smallexample
+@group
+(@value{GDBP}) up
+#1  0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
+    at env.c:10
+10              read_input_file (argv[i]);
+@end group
+@end smallexample
+
+After such a printout, the @code{list} command with no arguments
+prints ten lines centered on the point of execution in the frame.
+@xref{List, ,Printing source lines}.
+
+@table @code
+@kindex down-silently
+@kindex up-silently
+@item up-silently @var{n}
+@itemx down-silently @var{n}
+These two commands are variants of @code{up} and @code{down},
+respectively; they differ in that they do their work silently, without
+causing display of the new frame.  They are intended primarily for use
+in @value{GDBN} command scripts, where the output might be unnecessary and
+distracting.
+@end table
+
+@node Frame Info, Alpha/MIPS Stack, Selection, Stack
+@section Information about a frame
+
+There are several other commands to print information about the selected
+stack frame.
+
+@table @code
+@item frame
+@itemx f
+When used without any argument, this command does not change which
+frame is selected, but prints a brief description of the currently
+selected stack frame.  It can be abbreviated @code{f}.  With an
+argument, this command is used to select a stack frame.
+@xref{Selection, ,Selecting a frame}.
+
+@kindex info frame
+@kindex info f
+@item info frame
+@itemx info f
+This command prints a verbose description of the selected stack frame,
+including:
+
+@itemize @bullet
+@item 
+the address of the frame 
+@item
+the address of the next frame down (called by this frame)
+@item
+the address of the next frame up (caller of this frame)
+@item
+the language in which the source code corresponding to this frame is written
+@item
+the address of the frame's arguments
+@item
+the program counter saved in it (the address of execution in the caller frame)
+@item
+which registers were saved in the frame
+@end itemize
+
+@noindent The verbose description is useful when
+something has gone wrong that has made the stack format fail to fit
+the usual conventions.
+
+@item info frame @var{addr}
+@itemx info f @var{addr}
+Print a verbose description of the frame at address @var{addr}, without
+selecting that frame.  The selected frame remains unchanged by this
+command.  This requires the same kind of address (more than one for some
+architectures) that you specify in the @code{frame} command.
+@xref{Selection, ,Selecting a frame}.
+
+@kindex info args
+@item info args
+Print the arguments of the selected frame, each on a separate line.
+
+@item info locals
+@kindex info locals
+Print the local variables of the selected frame, each on a separate
+line.  These are all variables (declared either static or automatic)
+accessible at the point of execution of the selected frame.
+
+@ifclear CONLY
+@ifclear HPPA
+@kindex info catch
+@cindex catch exceptions
+@cindex exception handlers
+@item info catch
+Print a list of all the exception handlers that are active in the
+current stack frame at the current point of execution.  To see other
+exception handlers, visit the associated frame (using the @code{up},
+@code{down}, or @code{frame} commands); then type @code{info catch}.
+@xref{Set Catchpoints, , Setting catchpoints}.
+@end ifclear
+@end ifclear
+@end table
+
+@node Alpha/MIPS Stack,  , Frame Info, Stack
+@section MIPS/Alpha machines and the function stack
+
+@cindex stack on Alpha
+@cindex stack on MIPS
+@cindex Alpha stack
+@cindex MIPS stack
+Alpha- and MIPS-based computers use an unusual stack frame, which
+sometimes requires @value{GDBN} to search backward in the object code to
+find the beginning of a function.
+
+@cindex response time, MIPS debugging
+To improve response time (especially for embedded applications, where
+@value{GDBN} may be restricted to a slow serial line for this search)
+you may want to limit the size of this search, using one of these
+commands:
+
+@table @code
+@cindex @code{heuristic-fence-post} (Alpha,MIPS)
+@item set heuristic-fence-post @var{limit}
+Restrict @value{GDBN} to examining at most @var{limit} bytes in its search
+for the beginning of a function.  A value of @var{0} (the default)
+means there is no limit.  However, except for @var{0}, the larger the
+limit the more bytes @code{heuristic-fence-post} must search and 
+therefore the longer it takes to run.
+
+@item show heuristic-fence-post
+Display the current limit.
+@end table
+
+@noindent
+These commands are available @emph{only} when @value{GDBN} is configured
+for debugging programs on Alpha or MIPS processors.
+
+
+@node Source, Data, Stack, Top
+@chapter Examining Source Files
+
+@value{GDBN} can print parts of your program's source, since the debugging
+information recorded in the program tells @value{GDBN} what source files were
+used to build it.  When your program stops, @value{GDBN} spontaneously prints
+the line where it stopped.  Likewise, when you select a stack frame
+(@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where
+execution in that frame has stopped.  You can print other portions of
+source files by explicit command.
+
+@ifclear DOSHOST
+If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may prefer 
+to use
+Emacs facilities to view source; @pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}.
+@end ifclear
+
+@menu
+* List::                        Printing source lines
+@ifclear DOSHOST
+* Search::                      Searching source files
+@end ifclear
+
+* Source Path::                 Specifying source directories
+* Machine Code::                Source and machine code
+@end menu
+
+@node List, Search, Source, Source
+@section Printing source lines
+
+@kindex list
+@kindex l
+To print lines from a source file, use the @code{list} command
+(abbreviated @code{l}).  By default, ten lines are printed.  
+There are several ways to specify what part of the file you want to print.
+
+Here are the forms of the @code{list} command most commonly used:
+
+@table @code
+@item list @var{linenum}
+Print lines centered around line number @var{linenum} in the
+current source file.
+
+@item list @var{function}
+Print lines centered around the beginning of function
+@var{function}.
+
+@item list
+Print more lines.  If the last lines printed were printed with a
+@code{list} command, this prints lines following the last lines
+printed; however, if the last line printed was a solitary line printed
+as part of displaying a stack frame (@pxref{Stack, ,Examining the
+Stack}), this prints lines centered around that line.
+
+@item list -
+Print lines just before the lines last printed.
+@end table
+
+By default, @value{GDBN} prints ten source lines with any of these forms of
+the @code{list} command.  You can change this using @code{set listsize}:
+
+@table @code
+@kindex set listsize
+@item set listsize @var{count}
+Make the @code{list} command display @var{count} source lines (unless
+the @code{list} argument explicitly specifies some other number).
+
+@kindex show listsize
+@item show listsize
+Display the number of lines that @code{list} prints.
+@end table
+
+Repeating a @code{list} command with @key{RET} discards the argument,
+so it is equivalent to typing just @code{list}.  This is more useful
+than listing the same lines again.  An exception is made for an
+argument of @samp{-}; that argument is preserved in repetition so that
+each repetition moves up in the source file.
+
+@cindex linespec
+In general, the @code{list} command expects you to supply zero, one or two
+@dfn{linespecs}.  Linespecs specify source lines; there are several ways
+of writing them but the effect is always to specify some source line.
+Here is a complete description of the possible arguments for @code{list}:
+
+@table @code
+@item list @var{linespec}
+Print lines centered around the line specified by @var{linespec}.
+
+@item list @var{first},@var{last}
+Print lines from @var{first} to @var{last}.  Both arguments are
+linespecs.
+
+@item list ,@var{last}
+Print lines ending with @var{last}.
+
+@item list @var{first},
+Print lines starting with @var{first}.
+
+@item list +
+Print lines just after the lines last printed.
+
+@item list -
+Print lines just before the lines last printed.
+
+@item list
+As described in the preceding table.
+@end table
+
+Here are the ways of specifying a single source line---all the
+kinds of linespec.
+
+@table @code
+@item @var{number}
+Specifies line @var{number} of the current source file.
+When a @code{list} command has two linespecs, this refers to
+the same source file as the first linespec.
+
+@item +@var{offset}
+Specifies the line @var{offset} lines after the last line printed.
+When used as the second linespec in a @code{list} command that has
+two, this specifies the line @var{offset} lines down from the
+first linespec.
+
+@item -@var{offset}
+Specifies the line @var{offset} lines before the last line printed.
+
+@item @var{filename}:@var{number}
+Specifies line @var{number} in the source file @var{filename}.
+
+@item @var{function}
+Specifies the line that begins the body of the function @var{function}.
+For example: in C, this is the line with the open brace.
+
+@item @var{filename}:@var{function}
+Specifies the line of the open-brace that begins the body of the
+function @var{function} in the file @var{filename}.  You only need the
+file name with a function name to avoid ambiguity when there are
+identically named functions in different source files.
+
+@item *@var{address}
+Specifies the line containing the program address @var{address}.
+@var{address} may be any expression.
+@end table
+
+@ifclear DOSHOST
+@node Search, Source Path, List, Source
+@section Searching source files
+@cindex searching
+@kindex reverse-search
+
+There are two commands for searching through the current source file for a
+regular expression.
+
+@table @code
+@kindex search
+@kindex forward-search
+@item forward-search @var{regexp}
+@itemx search @var{regexp}
+The command @samp{forward-search @var{regexp}} checks each line,
+starting with the one following the last line listed, for a match for
+@var{regexp}.  It lists the line that is found.  You can use the 
+synonym @samp{search @var{regexp}} or abbreviate the command name as
+@code{fo}.
+
+@item reverse-search @var{regexp}
+The command @samp{reverse-search @var{regexp}} checks each line, starting
+with the one before the last line listed and going backward, for a match
+for @var{regexp}.  It lists the line that is found.  You can abbreviate
+this command as @code{rev}.
+@end table
+@end ifclear
+
+@node Source Path, Machine Code, Search, Source
+@section Specifying source directories
+
+@cindex source path
+@cindex directories for source files
+Executable programs sometimes do not record the directories of the source
+files from which they were compiled, just the names.  Even when they do,
+the directories could be moved between the compilation and your debugging
+session.  @value{GDBN} has a list of directories to search for source files;
+this is called the @dfn{source path}.  Each time @value{GDBN} wants a source file,
+it tries all the directories in the list, in the order they are present
+in the list, until it finds a file with the desired name.  Note that
+the executable search path is @emph{not} used for this purpose.  Neither is
+the current working directory, unless it happens to be in the source
+path.
+
+If @value{GDBN} cannot find a source file in the source path, and the
+object program records a directory, @value{GDBN} tries that directory
+too.  If the source path is empty, and there is no record of the
+compilation directory, @value{GDBN} looks in the current directory as a
+last resort.
+
+Whenever you reset or rearrange the source path, @value{GDBN} clears out
+any information it has cached about where source files are found and where
+each line is in the file.
+
+@kindex directory
+@kindex dir
+When you start @value{GDBN}, its source path is empty.
+To add other directories, use the @code{directory} command.
+
+@table @code
+@item directory @var{dirname} @dots{}
+@item dir @var{dirname} @dots{}
+Add directory @var{dirname} to the front of the source path.  Several
+directory names may be given to this command, separated by @samp{:} or
+whitespace.  You may specify a directory that is already in the source
+path; this moves it forward, so @value{GDBN} searches it sooner.
+
+@kindex cdir
+@kindex cwd
+@kindex $cdir
+@kindex $cwd
+@cindex compilation directory
+@cindex current directory
+@cindex working directory
+@cindex directory, current
+@cindex directory, compilation
+You can use the string @samp{$cdir} to refer to the compilation
+directory (if one is recorded), and @samp{$cwd} to refer to the current
+working directory.  @samp{$cwd} is not the same as @samp{.}---the former
+tracks the current working directory as it changes during your @value{GDBN}
+session, while the latter is immediately expanded to the current
+directory at the time you add an entry to the source path.
+
+@item directory
+Reset the source path to empty again.  This requires confirmation.
+
+@c RET-repeat for @code{directory} is explicitly disabled, but since
+@c repeating it would be a no-op we do not say that.  (thanks to RMS)
+
+@item show directories
+@kindex show directories
+Print the source path: show which directories it contains.
+@end table
+
+If your source path is cluttered with directories that are no longer of
+interest, @value{GDBN} may sometimes cause confusion by finding the wrong
+versions of source.  You can correct the situation as follows:
+
+@enumerate
+@item
+Use @code{directory} with no argument to reset the source path to empty.
+
+@item
+Use @code{directory} with suitable arguments to reinstall the
+directories you want in the source path.  You can add all the
+directories in one command.
+@end enumerate
+
+@node Machine Code,  , Source Path, Source
+@section Source and machine code
+
+You can use the command @code{info line} to map source lines to program
+addresses (and vice versa), and the command @code{disassemble} to display
+a range of addresses as machine instructions.  When run under @sc{gnu} Emacs
+mode, the @code{info line} command now causes the arrow to point to the
+line specified.  Also, @code{info line} prints addresses in symbolic form as 
+well as hex.
+
+@table @code
+@kindex info line
+@item info line @var{linespec}
+Print the starting and ending addresses of the compiled code for
+source line @var{linespec}.  You can specify source lines in any of
+the ways understood by the @code{list} command (@pxref{List, ,Printing
+source lines}).
+@end table
+
+For example, we can use @code{info line} to discover the location of
+the object code for the first line of function
+@code{m4_changequote}:
+
+@smallexample
+(@value{GDBP}) info line m4_changecom
+Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
+@end smallexample
+
+@noindent
+We can also inquire (using @code{*@var{addr}} as the form for
+@var{linespec}) what source line covers a particular address:
+@smallexample
+(@value{GDBP}) info line *0x63ff
+Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
+@end smallexample
+
+@cindex @code{$_} and @code{info line}
+After @code{info line}, the default address for the @code{x} command
+is changed to the starting address of the line, so that @samp{x/i} is
+sufficient to begin examining the machine code (@pxref{Memory,
+,Examining memory}).  Also, this address is saved as the value of the
+convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
+variables}).
+
+@table @code
+@kindex disassemble
+@cindex assembly instructions
+@cindex instructions, assembly
+@cindex machine instructions
+@cindex listing machine instructions
+@item disassemble
+This specialized command dumps a range of memory as machine
+instructions.  The default memory range is the function surrounding the
+program counter of the selected frame.  A single argument to this
+command is a program counter value; @value{GDBN} dumps the function
+surrounding this value.  Two arguments specify a range of addresses
+(first inclusive, second exclusive) to dump.
+@end table
+
+@ifclear H8EXCLUSIVE
+The following example shows the disassembly of a range of addresses of
+HP PA-RISC 2.0 code:
+
+@smallexample
+(@value{GDBP}) disas 0x32c4 0x32e4
+Dump of assembler code from 0x32c4 to 0x32e4:
+0x32c4 <main+204>:      addil 0,dp
+0x32c8 <main+208>:      ldw 0x22c(sr0,r1),r26
+0x32cc <main+212>:      ldil 0x3000,r31
+0x32d0 <main+216>:      ble 0x3f8(sr4,r31)
+0x32d4 <main+220>:      ldo 0(r31),rp
+0x32d8 <main+224>:      addil -0x800,dp
+0x32dc <main+228>:      ldo 0x588(r1),r26
+0x32e0 <main+232>:      ldil 0x3000,r31
+End of assembler dump.
+@end smallexample
+@end ifclear
+
+@ifset H8EXCLUSIVE
+For example, here is the beginning of the output for the
+disassembly of a function @code{fact}:
+
+
+@smallexample
+(@value{GDBP}) disas fact
+Dump of assembler code for function fact:
+to 0x808c:
+0x802c <fact>: 6d f2		mov.w r2,@@-r7
+0x802e <fact+2>:  6d f3		mov.w r3,@@-r7
+0x8030 <fact+4>:  6d f6		mov.w r6,@@-r7
+0x8032 <fact+6>:  0d 76		mov.w r7,r6
+0x8034 <fact+8>:  6f 70 00 08	mov.w @@(0x8,r7),r0
+0x8038 <fact+12>  19 11		sub.w	r1,r1
+ .
+ .
+ . 
+@end smallexample
+@end ifset
+
+Some architectures have more than one commonly-used set of instruction
+mnemonics or other syntax.
+
+@table @code
+@kindex set assembly-language
+@cindex assembly instructions
+@cindex instructions, assembly
+@cindex machine instructions
+@cindex listing machine instructions
+@item set assembly-language @var{instruction-set}
+Select the instruction set to use when disassembling the
+program via the @code{disassemble} or @code{x/i} commands.
+
+Currently this command is only defined for the Intel x86 family.  You
+can set @var{instruction-set} to either @code{i386} or @code{i8086}.
+The default is @code{i386}.
+@end table
+
+
+@node Data, Languages, Source, Top
+@chapter Examining Data
+
+@cindex printing data
+@cindex examining data
+@kindex print
+@kindex inspect
+@c "inspect" is not quite a synonym if you are using Epoch, which we do not
+@c document because it is nonstandard...  Under Epoch it displays in a
+@c different window or something like that.
+The usual way to examine data in your program is with the @code{print}
+command (abbreviated @code{p}), or its synonym @code{inspect}.  
+@ifclear CONLY
+It evaluates and prints the value of an expression of the language your
+program is written in (@pxref{Languages, ,Using @value{GDBN} with Different
+Languages}).
+@end ifclear
+
+@table @code
+@item print @var{exp}
+@itemx print /@var{f} @var{exp}
+@var{exp} is an expression (in the source language).  By default the
+value of @var{exp} is printed in a format appropriate to its data type;
+you can choose a different format by specifying @samp{/@var{f}}, where
+@var{f} is a letter specifying the format; @pxref{Output Formats,,Output
+formats}.
+
+@item print
+@itemx print /@var{f}
+If you omit @var{exp}, @value{GDBN} displays the last value again (from the
+@dfn{value history}; @pxref{Value History, ,Value history}).  This allows you to
+conveniently inspect the same value in an alternative format.
+@end table
+
+A more low-level way of examining data is with the @code{x} command.
+It examines data in memory at a specified address and prints it in a
+specified format.  @xref{Memory, ,Examining memory}.
+
+If you are interested in information about types, or about how the fields
+of a struct
+@ifclear CONLY
+or class
+@end ifclear
+are declared, use the @code{ptype @var{exp}}
+command rather than @code{print}. @xref{Symbols, ,Examining the Symbol Table}.
+
+@menu
+* Expressions::                 Expressions
+* Variables::                   Program variables
+* Arrays::                      Artificial arrays
+* Output Formats::              Output formats
+* Memory::                      Examining memory
+* Auto Display::                Automatic display
+* Print Settings::              Print settings
+* Value History::               Value history
+* Convenience Vars::            Convenience variables
+* Registers::                   Registers
+@ifclear HAVE-FLOAT
+* Floating Point Hardware::     Floating point hardware
+@end ifclear
+
+@end menu
+
+@node Expressions, Variables, Data, Data
+@section Expressions
+
+@cindex expressions
+@code{print} and many other @value{GDBN} commands accept an expression and
+compute its value.  Any kind of constant, variable or operator defined
+by the programming language you are using is valid in an expression in
+@value{GDBN}.  This includes conditional expressions, function calls, casts
+and string constants.  It unfortunately does not include symbols defined
+by preprocessor @code{#define} commands.
+
+@value{GDBN} now supports array constants in expressions input by
+the user.  The syntax is @var{@{element, element@dots{}@}}.  For example,
+you can now use the command @code{print @{1, 2, 3@}} to build up an array in 
+memory that is malloc'd in the target program.
+
+@ifclear CONLY
+Because C is so widespread, most of the expressions shown in examples in
+this manual are in C.  @xref{Languages, , Using @value{GDBN} with Different
+Languages}, for information on how to use expressions in other
+languages.
+
+In this section, we discuss operators that you can use in @value{GDBN}
+expressions regardless of your programming language.
+
+Casts are supported in all languages, not just in C, because it is so
+useful to cast a number into a pointer in order to examine a structure
+at that address in memory.
+@c FIXME: casts supported---Mod2 true?
+@end ifclear
+
+@value{GDBN} supports these operators, in addition to those common
+to programming languages:
+
+@table @code
+@item @@
+@samp{@@} is a binary operator for treating parts of memory as arrays.
+@xref{Arrays, ,Artificial arrays}, for more information.
+
+@item ::
+@samp{::} allows you to specify a variable in terms of the file or
+function where it is defined.  @xref{Variables, ,Program variables}.
+
+@cindex @{@var{type}@}
+@cindex type casting memory
+@cindex memory, viewing as typed object
+@cindex casts, to view memory
+@item @{@var{type}@} @var{addr}
+Refers to an object of type @var{type} stored at address @var{addr} in
+memory.  @var{addr} may be any expression whose value is an integer or
+pointer (but parentheses are required around binary operators, just as in
+a cast).  This construct is allowed regardless of what kind of data is
+normally supposed to reside at @var{addr}.
+@end table
+
+@node Variables, Arrays, Expressions, Data
+@section Program variables
+
+The most common kind of expression to use is the name of a variable
+in your program.
+
+Variables in expressions are understood in the selected stack frame
+(@pxref{Selection, ,Selecting a frame}); they must be either:
+
+@itemize @bullet
+@item
+global (or file-static)
+@end itemize
+
+@noindent or 
+
+@itemize @bullet
+@item
+visible according to the scope rules of the
+programming language from the point of execution in that frame
+@end itemize  
+
+@noindent This means that in the function
+
+@example
+foo (a)
+     int a;
+@{
+  bar (a);
+  @{
+    int b = test ();
+    bar (b);
+  @}
+@}
+@end example
+
+@noindent
+you can examine and use the variable @code{a} whenever your program is
+executing within the function @code{foo}, but you can only use or
+examine the variable @code{b} while your program is executing inside
+the block where @code{b} is declared.
+
+@cindex variable name conflict
+There is an exception: you can refer to a variable or function whose
+scope is a single source file even if the current execution point is not
+in this file.  But it is possible to have more than one such variable or
+function with the same name (in different source files).  If that
+happens, referring to that name has unpredictable effects.  If you wish,
+you can specify a static variable in a particular function or file,
+using the colon-colon notation:
+
+@cindex colon-colon
+@iftex
+@c info cannot cope with a :: index entry, but why deprive hard copy readers?
+@kindex ::
+@end iftex
+@example
+@var{file}::@var{variable}
+@var{function}::@var{variable}
+@end example
+
+@noindent
+Here @var{file} or @var{function} is the name of the context for the
+static @var{variable}.  In the case of file names, you can use quotes to
+make sure @value{GDBN} parses the file name as a single word---for example,
+to print a global value of @code{x} defined in @file{f2.c}:
+
+@example
+(@value{GDBP}) p 'f2.c'::x
+@end example
+
+@ifclear CONLY
+@cindex C++ scope resolution
+This use of @samp{::} is very rarely in conflict with the very similar
+use of the same notation in C++.  @value{GDBN} also supports use of the C++
+scope resolution operator in @value{GDBN} expressions.
+@c FIXME: Um, so what happens in one of those rare cases where it's in
+@c conflict??  --mew
+@end ifclear
+
+@cindex wrong values
+@cindex variable values, wrong
+@quotation
+@emph{Warning:} Occasionally, a local variable may appear to have the
+wrong value at certain points in a function---just after entry to a new
+scope, and just before exit.
+@end quotation
+You may see this problem when you are stepping by machine instructions.
+This is because, on most machines, it takes more than one instruction to
+set up a stack frame (including local variable definitions); if you are
+stepping by machine instructions, variables may appear to have the wrong
+values until the stack frame is completely built.  On exit, it usually
+also takes more than one machine instruction to destroy a stack frame;
+after you begin stepping through that group of instructions, local
+variable definitions may be gone.
+
+This may also happen when the compiler does significant optimizations.
+To be sure of always seeing accurate values, turn off all optimization
+when compiling.
+
+@node Arrays, Output Formats, Variables, Data
+@section Artificial arrays
+
+@cindex artificial array
+@kindex @@
+It is often useful to print out several successive objects of the
+same type in memory; a section of an array, or an array of
+dynamically determined size for which only a pointer exists in the
+program.
+
+You can do this by referring to a contiguous span of memory as an
+@dfn{artificial array}, using the binary operator @samp{@@}.  The left
+operand of @samp{@@} should be the first element of the desired array
+and be an individual object.  The right operand should be the desired length
+of the array.  The result is an array value whose elements are all of
+the type of the left argument.  The first element is actually the left
+argument; the second element comes from bytes of memory immediately
+following those that hold the first element, and so on.  Here is an
+example.  If a program says
+
+@example
+int *array = (int *) malloc (len * sizeof (int));
+@end example
+
+@noindent
+you can print the contents of @code{array} with
+
+@example
+p *array@@len
+@end example
+
+The left operand of @samp{@@} must reside in memory.  Array values made
+with @samp{@@} in this way behave just like other arrays in terms of
+subscripting, and are coerced to pointers when used in expressions.
+Artificial arrays most often appear in expressions via the value history
+(@pxref{Value History, ,Value history}), after printing one out.
+
+Another way to create an artificial array is to use a cast.
+This re-interprets a value as if it were an array.
+The value need not be in memory:
+@example
+(@value{GDBP}) p/x (short[2])0x12345678
+$1 = @{0x1234, 0x5678@}
+@end example
+
+As a convenience, if you leave the array length out (as in
+@samp{(@var{type})[])@var{value}}) gdb calculates the size to fill
+the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
+@example
+(@value{GDBP}) p/x (short[])0x12345678
+$2 = @{0x1234, 0x5678@}
+@end example
+
+Sometimes the artificial array mechanism is not quite enough; in
+moderately complex data structures, the elements of interest may not
+actually be adjacent---for example, if you are interested in the values
+of pointers in an array.  One useful work-around in this situation is
+to use a convenience variable (@pxref{Convenience Vars, ,Convenience
+variables}) as a counter in an expression that prints the first
+interesting value, and then repeat that expression via @key{RET}.  For
+instance, suppose you have an array @code{dtab} of pointers to
+structures, and you are interested in the values of a field @code{fv}
+in each structure.  Here is an example of what you might type:
+
+@example
+set $i = 0
+p dtab[$i++]->fv
+@key{RET}
+@key{RET}
+@dots{}
+@end example
+
+@node Output Formats, Memory, Arrays, Data
+@section Output formats
+
+@cindex formatted output
+@cindex output formats
+By default, @value{GDBN} prints a value according to its data type.  Sometimes
+this is not what you want.  For example, you might want to print a number
+in hex, or a pointer in decimal.  Or you might want to view data in memory
+at a certain address as a character string or as an instruction.  To do
+these things, specify an @dfn{output format} when you print a value.
+
+The simplest use of output formats is to say how to print a value
+already computed.  This is done by starting the arguments of the
+@code{print} command with a slash and a format letter.  The format
+letters supported are:
+
+@table @code
+@item x
+Regard the bits of the value as an integer, and print the integer in
+hexadecimal.
+
+@item d
+Print as integer in signed decimal.
+
+@item u
+Print as integer in unsigned decimal.
+
+@item o
+Print as integer in octal.
+
+@item t
+Print as integer in binary.  The letter @samp{t} stands for ``two''.
+@footnote{@samp{b} cannot be used because these format letters are also
+used with the @code{x} command, where @samp{b} stands for ``byte'';
+@pxref{Memory,,Examining memory}.}
+
+@item a
+@cindex unknown address, locating
+Print as an address, both absolute in hexadecimal and as an offset from
+the nearest preceding symbol.  You can use this format used to discover
+where (in what function) an unknown address is located:
+
+@example
+(@value{GDBP}) p/a 0x54320
+$3 = 0x54320 <_initialize_vx+396>
+@end example
+
+@item c
+Regard as an integer and print it as a character constant.
+
+@item f
+Regard the bits of the value as a floating point number and print
+using typical floating point syntax.
+@end table
+
+For example, to print the program counter in hex (@pxref{Registers}), type
+
+@example
+p/x $pc
+@end example
+
+@noindent
+Note that no space is required before the slash; this is because command
+names in @value{GDBN} cannot contain a slash.
+
+To reprint the last value in the value history with a different format,
+you can use the @code{print} command with just a format and no
+expression.  For example, @samp{p/x} reprints the last value in hex.
+
+@node Memory, Auto Display, Output Formats, Data
+@section Examining memory
+
+You can use the command @code{x} (for ``examine'') to examine memory in
+any of several formats, independently of your program's data types.
+
+@cindex examining memory
+@table @code
+@kindex x
+@item x/@var{nfu} @var{addr}
+@itemx x @var{addr}
+@itemx x
+Use the @code{x} command to examine memory.
+@end table
+
+@var{n}, @var{f}, and @var{u} are all optional parameters that specify how
+much memory to display and how to format it; @var{addr} is an
+expression giving the address where you want to start displaying memory.
+If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
+Several commands set convenient defaults for @var{addr}.
+
+@table @r
+@item @var{n}, the repeat count
+The repeat count is a decimal integer; the default is 1.  It specifies
+how much memory (counting by units @var{u}) to display.
+@c This really is **decimal**; unaffected by 'set radix' as of GDB
+@c 4.1.2.
+
+@item @var{f}, the display format
+The display format is one of the formats used by @code{print},
+@samp{s} (null-terminated string), or @samp{i} (machine instruction).
+The default is @samp{x} (hexadecimal) initially.
+The default changes each time you use either @code{x} or @code{print}.
+
+@item @var{u}, the unit size
+The unit size is any of
+
+@table @code
+@item b
+Bytes.
+@item h
+Halfwords (two bytes).
+@item w
+Words (four bytes).  This is the initial default.
+@item g
+Giant words (eight bytes).
+@end table
+
+Each time you specify a unit size with @code{x}, that size becomes the
+default unit the next time you use @code{x}.  (For the @samp{s} and
+@samp{i} formats, the unit size is ignored and is normally not written.)
+
+@item @var{addr}, starting display address
+@var{addr} is the address where you want @value{GDBN} to begin displaying
+memory.  The expression need not have a pointer value (though it may);
+it is always interpreted as an integer address of a byte of memory.
+@xref{Expressions, ,Expressions}, for more information on expressions.  The default for
+@var{addr} is usually just after the last address examined---but several
+other commands also set the default address: @code{info breakpoints} (to
+the address of the last breakpoint listed), @code{info line} (to the
+starting address of a line), and @code{print} (if you use it to display
+a value from memory).
+@end table
+
+For example, @samp{x/3uh 0x54320} is a request to display three halfwords
+(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
+starting at address @code{0x54320}.  @samp{x/4xw $sp} prints the four
+words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
+@pxref{Registers}) in hexadecimal (@samp{x}).
+
+Since the letters indicating unit sizes are all distinct from the
+letters specifying output formats, you do not have to remember whether
+unit size or format comes first; either order works.  The output
+specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
+(However, the count @var{n} must come first; @samp{wx4} does not work.)
+
+Even though the unit size @var{u} is ignored for the formats @samp{s}
+and @samp{i}, you might still want to use a count @var{n}; for example,
+@samp{3i} specifies that you want to see three machine instructions,
+including any operands.  The command @code{disassemble} gives an
+alternative way of inspecting machine instructions; @pxref{Machine
+Code,,Source and machine code}.
+
+All the defaults for the arguments to @code{x} are designed to make it
+easy to continue scanning memory with minimal specifications each time
+you use @code{x}.  For example, after you have inspected three machine
+instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
+with just @samp{x/7}.  If you use @key{RET} to repeat the @code{x} command,
+the repeat count @var{n} is used again; the other arguments default as
+for successive uses of @code{x}.
+
+@cindex @code{$_}, @code{$__}, and value history
+The addresses and contents printed by the @code{x} command are not saved
+in the value history because there is often too much of them and they
+would get in the way.  Instead, @value{GDBN} makes these values available for
+subsequent use in expressions as values of the convenience variables
+@code{$_} and @code{$__}.  After an @code{x} command, the last address
+examined is available for use in expressions in the convenience variable
+@code{$_}.  The contents of that address, as examined, are available in
+the convenience variable @code{$__}.
+
+If the @code{x} command has a repeat count, the address and contents saved
+are from the last memory unit printed; this is not the same as the last
+address printed if several units were printed on the last line of output.
+
+@node Auto Display, Print Settings, Memory, Data
+@section Automatic display
+@cindex automatic display
+@cindex display of expressions
+
+If you find that you want to print the value of an expression frequently
+(to see how it changes), you might want to add it to the @dfn{automatic
+display list} so that @value{GDBN} prints its value each time your program stops.
+Each expression added to the list is given a number to identify it;
+to remove an expression from the list, you specify that number.
+The automatic display looks like this:
+
+@example
+2: foo = 38
+3: bar[5] = (struct hack *) 0x3804
+@end example
+
+@noindent
+This display shows item numbers, expressions and their current values.  As with
+displays you request manually using @code{x} or @code{print}, you can
+specify the output format you prefer; in fact, @code{display} decides
+whether to use @code{print} or @code{x} depending on how elaborate your
+format specification is---it uses @code{x} if you specify a unit size,
+or one of the two formats (@samp{i} and @samp{s}) that are only
+supported by @code{x}; otherwise it uses @code{print}.
+
+@table @code
+@kindex display
+@item display @var{exp}
+Add the expression @var{exp} to the list of expressions to display
+each time your program stops.  @xref{Expressions, ,Expressions}.
+
+@code{display} does not repeat if you press @key{RET} again after using it.
+
+@item display/@var{fmt} @var{exp}
+For @var{fmt} specifying only a display format and not a size or
+count, add the expression @var{exp} to the auto-display list but
+arrange to display it each time in the specified format @var{fmt}.
+@xref{Output Formats,,Output formats}.
+
+@item display/@var{fmt} @var{addr}
+For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
+number of units, add the expression @var{addr} as a memory address to
+be examined each time your program stops.  Examining means in effect
+doing @samp{x/@var{fmt} @var{addr}}.  @xref{Memory, ,Examining memory}.
+@end table
+
+For example, @samp{display/i $pc} can be helpful, to see the machine
+instruction about to be executed each time execution stops (@samp{$pc}
+is a common name for the program counter; @pxref{Registers}).
+
+@table @code
+@kindex delete display
+@kindex undisplay
+@item undisplay @var{dnums}@dots{}
+@itemx delete display @var{dnums}@dots{}
+Remove item numbers @var{dnums} from the list of expressions to display.
+
+@code{undisplay} does not repeat if you press @key{RET} after using it.
+(Otherwise you would just get the error @samp{No display number @dots{}}.)
+
+@kindex disable display
+@item disable display @var{dnums}@dots{}
+Disable the display of item numbers @var{dnums}.  A disabled display
+item is not printed automatically, but is not forgotten.  It may be
+enabled again later.
+
+@kindex enable display
+@item enable display @var{dnums}@dots{}
+Enable display of item numbers @var{dnums}.  It becomes effective once
+again in auto display of its expression, until you specify otherwise.
+
+@item display
+Display the current values of the expressions on the list, just as is
+done when your program stops.
+
+@kindex info display
+@item info display
+Print the list of expressions previously set up to display
+automatically, each one with its item number, but without showing the
+values.  This includes disabled expressions, which are marked as such.
+It also includes expressions which would not be displayed right now
+because they refer to automatic variables not currently available.
+@end table
+
+If a display expression refers to local variables, then it does not make
+sense outside the lexical context for which it was set up.  Such an
+expression is disabled when execution enters a context where one of its
+variables is not defined.  For example, if you give the command
+@code{display last_char} while inside a function with an argument
+@code{last_char}, @value{GDBN} displays this argument while your program
+continues to stop inside that function.  When it stops elsewhere---where
+there is no variable @code{last_char}---the display is disabled
+automatically.  The next time your program stops where @code{last_char}
+is meaningful, you can enable the display expression once again.
+
+@node Print Settings, Value History, Auto Display, Data
+@section Print settings
+
+@cindex format options
+@cindex print settings
+@value{GDBN} provides the following ways to control how arrays, structures,
+and symbols are printed.
+
+@noindent
+These settings are useful for debugging programs in any language:
+
+@table @code
+@kindex set print address
+@item set print address
+@itemx set print address on
+@value{GDBN} prints memory addresses showing the location of stack
+traces, structure values, pointer values, breakpoints, and so forth,
+even when it also displays the contents of those addresses.  The default
+is @code{on}.  For example, this is what a stack frame display looks like with
+@code{set print address on}:
+
+@smallexample
+@group
+(@value{GDBP}) f
+#0  set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
+    at input.c:530
+530         if (lquote != def_lquote)
+@end group
+@end smallexample
+
+@item set print address off
+Do not print addresses when displaying their contents.  For example,
+this is the same stack frame displayed with @code{set print address off}:
+
+@smallexample
+@group
+(@value{GDBP}) set print addr off
+(@value{GDBP}) f
+#0  set_quotes (lq="<<", rq=">>") at input.c:530
+530         if (lquote != def_lquote)
+@end group
+@end smallexample
+
+You can use @samp{set print address off} to eliminate all machine
+dependent displays from the @value{GDBN} interface.  For example, with
+@code{print address off}, you should get the same text for backtraces on
+all machines---whether or not they involve pointer arguments.
+
+@kindex show print address
+@item show print address
+Show whether or not addresses are to be printed.
+@end table
+
+When @value{GDBN} prints a symbolic address, it normally prints the
+closest earlier symbol plus an offset.  If that symbol does not uniquely
+identify the address (for example, it is a name whose scope is a single
+source file), you may need to clarify.  One way to do this is with
+@code{info line}, for example @samp{info line *0x4537}.  Alternately,
+you can set @value{GDBN} to print the source file and line number when
+it prints a symbolic address:
+
+@table @code
+@kindex set print symbol-filename
+@item set print symbol-filename on
+Tell @value{GDBN} to print the source file name and line number of a
+symbol in the symbolic form of an address.
+
+@item set print symbol-filename off
+Do not print source file name and line number of a symbol.  This is the
+default.
+
+@kindex show print symbol-filename
+@item show print symbol-filename
+Show whether or not @value{GDBN} will print the source file name and
+line number of a symbol in the symbolic form of an address.
+@end table
+
+Another situation where it is helpful to show symbol filenames and line
+numbers is when disassembling code; @value{GDBN} shows you the line
+number and source file that corresponds to each instruction.
+
+Also, you may wish to see the symbolic form only if the address being
+printed is reasonably close to the closest earlier symbol:
+
+@table @code
+@kindex set print max-symbolic-offset
+@item set print max-symbolic-offset @var{max-offset}
+Tell @value{GDBN} to only display the symbolic form of an address if the
+offset between the closest earlier symbol and the address is less than
+@var{max-offset}.  The default is 0, which tells @value{GDBN} 
+to always print the symbolic form of an address if any symbol precedes it.
+
+@kindex show print max-symbolic-offset
+@item show print max-symbolic-offset
+Ask how large the maximum offset is that @value{GDBN} prints in a
+symbolic address.
+@end table
+
+@cindex wild pointer, interpreting
+@cindex pointer, finding referent
+If you have a pointer and you are not sure where it points, try
+@samp{set print symbol-filename on}.  Then you can determine the name
+and source file location of the variable where it points, using
+@samp{p/a @var{pointer}}.  This interprets the address in symbolic form.
+For example, here @value{GDBN} shows that a variable @code{ptt} points
+at another variable @code{t}, defined in @file{hi2.c}:
+
+@example
+(@value{GDBP}) set print symbol-filename on
+(@value{GDBP}) p/a ptt
+$4 = 0xe008 <t in hi2.c>
+@end example
+
+@quotation
+@emph{Warning:} For pointers that point to a local variable, @samp{p/a}
+does not show the symbol name and filename of the referent, even with
+the appropriate @code{set print} options turned on.
+@end quotation
+
+Other settings control how different kinds of objects are printed:
+
+@table @code
+@kindex set print array
+@item set print array
+@itemx set print array on
+Pretty print arrays.  This format is more convenient to read,
+but uses more space.  The default is off.
+
+@item set print array off
+Return to compressed format for arrays.
+
+@kindex show print array
+@item show print array
+Show whether compressed or pretty format is selected for displaying
+arrays.
+
+@kindex set print elements
+@item set print elements @var{number-of-elements}
+Set a limit on how many elements of an array @value{GDBN} will print.
+If @value{GDBN} is printing a large array, it stops printing after it has
+printed the number of elements set by the @code{set print elements} command.
+This limit also applies to the display of strings.
+Setting  @var{number-of-elements} to zero means that the printing is unlimited.
+
+@kindex show print elements
+@item show print elements
+Display the number of elements of a large array that @value{GDBN} will print.
+If the number is 0, then the printing is unlimited.
+
+@kindex set print null-stop
+@item set print null-stop
+Cause @value{GDBN} to stop printing the characters of an array when the first
+@sc{NULL} is encountered.  This is useful when large arrays actually
+contain only short strings.
+
+@kindex set print pretty
+@item set print pretty on
+Cause @value{GDBN} to print structures in an indented format with one member 
+per line, like this:
+
+@smallexample
+@group
+$1 = @{
+  next = 0x0,
+  flags = @{
+    sweet = 1,
+    sour = 1
+  @},
+  meat = 0x54 "Pork"
+@}
+@end group
+@end smallexample
+
+@item set print pretty off
+Cause @value{GDBN} to print structures in a compact format, like this:
+
+@smallexample
+@group
+$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
+meat = 0x54 "Pork"@}
+@end group
+@end smallexample
+
+@noindent
+This is the default format.
+
+@kindex show print pretty
+@item show print pretty
+Show which format @value{GDBN} is using to print structures.
+
+@kindex set print sevenbit-strings
+@item set print sevenbit-strings on
+Print using only seven-bit characters; if this option is set,
+@value{GDBN} displays any eight-bit characters (in strings or
+character values) using the notation @code{\}@var{nnn}.  This setting is
+best if you are working in English (@sc{ascii}) and you use the
+high-order bit of characters as a marker or ``meta'' bit.
+
+@item set print sevenbit-strings off
+Print full eight-bit characters.  This allows the use of more
+international character sets, and is the default.
+
+@kindex show print sevenbit-strings
+@item show print sevenbit-strings
+Show whether or not @value{GDBN} is printing only seven-bit characters.
+
+@kindex set print union
+@item set print union on
+Tell @value{GDBN} to print unions which are contained in structures.  This 
+is the default setting.
+
+@item set print union off
+Tell @value{GDBN} not to print unions which are contained in structures.
+
+@kindex show print union
+@item show print union
+Ask @value{GDBN} whether or not it will print unions which are contained in
+structures.
+
+For example, given the declarations
+
+@smallexample
+typedef enum @{Tree, Bug@} Species;
+typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
+typedef enum @{Caterpillar, Cocoon, Butterfly@} 
+              Bug_forms;
+
+struct thing @{
+  Species it;
+  union @{
+    Tree_forms tree;
+    Bug_forms bug;
+  @} form;
+@};
+
+struct thing foo = @{Tree, @{Acorn@}@};
+@end smallexample
+
+@noindent
+with @code{set print union on} in effect @samp{p foo} would print
+
+@smallexample
+$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
+@end smallexample
+
+@noindent
+and with @code{set print union off} in effect it would print
+
+@smallexample
+$1 = @{it = Tree, form = @{...@}@}
+@end smallexample
+@end table
+
+@ifclear CONLY
+@need 1000
+@noindent
+These settings are of interest when debugging C++ programs:
+
+@table @code
+@cindex demangling
+@kindex set print demangle
+@item set print demangle
+@itemx set print demangle on
+Print C++ names in their source form rather than in the encoded
+(``mangled'') form passed to the assembler and linker for type-safe
+linkage.  The default is @samp{on}.
+
+@kindex show print demangle
+@item show print demangle
+Show whether C++ names are printed in mangled or demangled form.
+
+@kindex set print asm-demangle
+@item set print asm-demangle
+@itemx set print asm-demangle on
+Print C++ names in their source form rather than their mangled form, even
+in assembler code printouts such as instruction disassemblies.
+The default is off.
+
+@kindex show print asm-demangle
+@item show print asm-demangle
+Show whether C++ names in assembly listings are printed in mangled
+or demangled form.
+
+@kindex set demangle-style
+@cindex C++ symbol decoding style
+@cindex symbol decoding style, C++
+@item set demangle-style @var{style}
+Choose among several encoding schemes used by different compilers to
+represent C++ names.  The choices for @var{style} are currently:
+
+@table @code
+@item auto
+Allow @value{GDBN} to choose a decoding style by inspecting your program.
+
+@item gnu
+Decode based on the @sc{gnu} C++ compiler (@code{g++}) encoding algorithm.  
+@ifclear HPPA
+This is the default.
+@end ifclear
+
+@item hp
+Decode based on the HP ANSI C++ (@code{aCC}) encoding algorithm.
+
+@item lucid
+Decode based on the Lucid C++ compiler (@code{lcc}) encoding algorithm.
+
+@item arm
+Decode using the algorithm in the @cite{C++ Annotated Reference Manual}.
+@strong{Warning:} this setting alone is not sufficient to allow
+debugging @code{cfront}-generated executables.  @value{GDBN} would
+require further enhancement to permit that.
+
+@end table
+If you omit @var{style}, you will see a list of possible formats.
+
+@kindex show demangle-style
+@item show demangle-style
+Display the encoding style currently in use for decoding C++ symbols.
+
+@kindex set print object
+@item set print object
+@itemx set print object on
+When displaying a pointer to an object, identify the @emph{actual}
+(derived) type of the object rather than the @emph{declared} type, using
+the virtual function table.
+
+@item set print object off
+Display only the declared type of objects, without reference to the
+virtual function table.  This is the default setting.
+
+@kindex show print object
+@item show print object
+Show whether actual, or declared, object types are displayed.
+
+@kindex set print static-members
+@item set print static-members
+@itemx set print static-members on
+Print static members when displaying a C++ object.  The default is on.
+
+@item set print static-members off
+Do not print static members when displaying a C++ object.
+
+@kindex show print static-members
+@item show print static-members
+Show whether C++ static members are printed, or not.
+
+@c These don't work with HP ANSI C++ yet.
+@kindex set print vtbl
+@item set print vtbl
+@itemx set print vtbl on
+Pretty print C++ virtual function tables.  The default is off.
+@ifset HPPA
+(The @code{vtbl} commands do not work on programs compiled with the HP
+ANSI C++ compiler (@code{aCC}).)
+@end ifset
+
+@item set print vtbl off
+Do not pretty print C++ virtual function tables.
+
+@kindex show print vtbl
+@item show print vtbl
+Show whether C++ virtual function tables are pretty printed, or not.
+@end table
+@end ifclear
+
+@node Value History, Convenience Vars, Print Settings, Data
+@section Value history
+
+@cindex value history
+Values printed by the @code{print} command are saved in the @value{GDBN} 
+@dfn{value history}.  This allows you to refer to them in other expressions.  
+Values are kept until the symbol table is re-read or discarded 
+(for example with the @code{file} or @code{symbol-file} commands).  
+When the symbol table changes, the value history is discarded, 
+since the values may contain pointers back to the types defined in the 
+symbol table.
+
+@cindex @code{$}
+@cindex @code{$$}
+@cindex history number
+The values printed are given @dfn{history numbers} by which you can
+refer to them.  These are successive integers starting with one.
+@code{print} shows you the history number assigned to a value by
+printing @samp{$@var{num} = } before the value; here @var{num} is the
+history number.
+
+To refer to any previous value, use @samp{$} followed by the value's
+history number.  The way @code{print} labels its output is designed to
+remind you of this.  Just @code{$} refers to the most recent value in
+the history, and @code{$$} refers to the value before that.
+@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
+is the value just prior to @code{$$}, @code{$$1} is equivalent to
+@code{$$}, and @code{$$0} is equivalent to @code{$}.
+
+For example, suppose you have just printed a pointer to a structure and
+want to see the contents of the structure.  It suffices to type
+
+@example
+p *$
+@end example
+
+If you have a chain of structures where the component @code{next} points
+to the next one, you can print the contents of the next one with this:
+
+@example
+p *$.next
+@end example
+
+@noindent
+You can print successive links in the chain by repeating this
+command---which you can do by just typing @key{RET}.
+
+Note that the history records values, not expressions.  If the value of
+@code{x} is 4 and you type these commands:
+
+@example
+print x
+set x=5
+@end example
+
+@noindent
+then the value recorded in the value history by the @code{print} command
+remains 4 even though the value of @code{x} has changed.
+
+@table @code
+@kindex show values
+@item show values
+Print the last ten values in the value history, with their item numbers.
+This is like @samp{p@ $$9} repeated ten times, except that @code{show
+values} does not change the history.
+
+@item show values @var{n}
+Print ten history values centered on history item number @var{n}.
+
+@item show values +
+Print ten history values just after the values last printed.  If no more
+values are available, @code{show values +} produces no display.
+@end table
+
+Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
+same effect as @samp{show values +}.
+
+@node Convenience Vars, Registers, Value History, Data
+@section Convenience variables
+
+@cindex convenience variables
+@value{GDBN} provides @dfn{convenience variables} that you can use within
+@value{GDBN} to hold on to a value and refer to it later.  These variables
+exist entirely within @value{GDBN}; they are not part of your program, and
+setting a convenience variable has no direct effect on further execution
+of your program.  That is why you can use them freely.
+
+Convenience variables are prefixed with @samp{$}.  Any name preceded by
+@samp{$} can be used for a convenience variable, unless it is one of
+the predefined machine-specific register names (@pxref{Registers}).
+(Value history references, in contrast, are @emph{numbers} preceded
+by @samp{$}.  @xref{Value History, ,Value history}.)
+
+You can save a value in a convenience variable with an assignment
+expression, just as you would set a variable in your program.
+For example:
+
+@example
+set $foo = *object_ptr
+@end example
+
+@noindent
+would save in @code{$foo} the value contained in the object pointed to by
+@code{object_ptr}.
+
+Using a convenience variable for the first time creates it, but its
+value is @code{void} until you assign a new value.  You can alter the
+value with another assignment at any time.
+
+Convenience variables have no fixed types.  You can assign a convenience
+variable any type of value, including structures and arrays, even if
+that variable already has a value of a different type.  The convenience
+variable, when used as an expression, has the type of its current value.
+
+@table @code
+@kindex show convenience
+@item show convenience
+Print a list of convenience variables used so far, and their values.
+Abbreviated @code{show con}.
+@end table
+
+One of the ways to use a convenience variable is as a counter to be
+incremented or a pointer to be advanced.  For example, to print
+a field from successive elements of an array of structures:
+
+@example
+set $i = 0
+print bar[$i++]->contents
+@end example
+
+@noindent Repeat that command by typing @key{RET}.
+
+Some convenience variables are created automatically by @value{GDBN} and given
+values likely to be useful.
+
+@table @code
+@kindex $_
+@item $_
+The variable @code{$_} is automatically set by the @code{x} command to
+the last address examined (@pxref{Memory, ,Examining memory}).  Other
+commands which provide a default address for @code{x} to examine also
+set @code{$_} to that address; these commands include @code{info line}
+and @code{info breakpoint}.  The type of @code{$_} is @code{void *}
+except when set by the @code{x} command, in which case it is a pointer
+to the type of @code{$__}.
+
+@kindex $__
+@item $__
+The variable @code{$__} is automatically set by the @code{x} command
+to the value found in the last address examined.  Its type is chosen
+to match the format in which the data was printed.
+
+@item $_exitcode
+@kindex $_exitcode
+The variable @code{$_exitcode} is automatically set to the exit code when
+the program being debugged terminates.
+@end table
+
+@ifset HPPA
+If you refer to a function or variable name that begins with a dollar
+sign, @value{GDBN} searches for a user or system name first, before it
+searches for a convenience variable.
+@end ifset
+
+@node Registers, Floating Point Hardware, Convenience Vars, Data
+@section Registers
+
+@cindex registers
+You can refer to machine register contents, in expressions, as variables
+with names starting with @samp{$}.  The names of registers are different
+for each machine; use @code{info registers} to see the names used on
+your machine.
+
+@table @code
+@kindex info registers
+@item info registers
+Print the names and values of all registers except floating-point
+registers (in the selected stack frame).
+
+@kindex info all-registers
+@cindex floating point registers
+@item info all-registers
+Print the names and values of all registers, including floating-point
+registers.
+
+@item info registers @var{regname} @dots{}
+Print the @dfn{relativized} value of each specified register @var{regname}.
+As discussed in detail below, register values are normally relative to 
+the selected stack frame.  @var{regname} may be any register name valid on 
+the machine you are using, with or without the initial @samp{$}.
+@end table
+
+@value{GDBN} has four ``standard'' register names that are available (in
+expressions) on most machines---whenever they do not conflict with an
+architecture's canonical mnemonics for registers.  The register names
+@code{$pc} and @code{$sp} are used for the program counter register and
+the stack pointer.  @code{$fp} is used for a register that contains a
+pointer to the current stack frame, and @code{$ps} is used for a
+register that contains the processor status.  For example,
+you could print the program counter in hex with
+
+@example
+p/x $pc
+@end example
+
+@noindent
+or print the instruction to be executed next with
+
+@example
+x/i $pc
+@end example
+
+@noindent
+or add four to the stack pointer@footnote{This is a way of removing
+one word from the stack, on machines where stacks grow downward in
+memory (most machines, nowadays).  This assumes that the innermost
+stack frame is selected; setting @code{$sp} is not allowed when other
+stack frames are selected.  To pop entire frames off the stack,
+regardless of machine architecture, use @code{return};
+@pxref{Returning, ,Returning from a function}.} with
+
+@example
+set $sp += 4
+@end example
+
+Whenever possible, these four standard register names are available on
+your machine even though the machine has different canonical mnemonics,
+so long as there is no conflict.  The @code{info registers} command
+shows the canonical names.  For example, on the SPARC, @code{info
+registers} displays the processor status register as @code{$psr} but you
+can also refer to it as @code{$ps}.
+
+@value{GDBN} always considers the contents of an ordinary register as an
+integer when the register is examined in this way.  Some machines have
+special registers which can hold nothing but floating point; these
+registers are considered to have floating point values.  There is no way
+to refer to the contents of an ordinary register as floating point value
+(although you can @emph{print} it as a floating point value with
+@samp{print/f $@var{regname}}).
+
+Some registers have distinct ``raw'' and ``virtual'' data formats.  This
+means that the data format in which the register contents are saved by
+the operating system is not the same one that your program normally
+sees.  For example, the registers of the 68881 floating point
+coprocessor are always saved in ``extended'' (raw) format, but all C
+programs expect to work with ``double'' (virtual) format.  In such
+cases, @value{GDBN} normally works with the virtual format only (the format 
+that makes sense for your program), but the @code{info registers} command
+prints the data in both formats.
+
+Normally, register values are relative to the selected stack frame
+(@pxref{Selection, ,Selecting a frame}).  This means that you get the
+value that the register would contain if all stack frames farther in
+were exited and their saved registers restored.  In order to see the
+true contents of hardware registers, you must select the innermost
+frame (with @samp{frame 0}).
+
+However, @value{GDBN} must deduce where registers are saved, from the machine
+code generated by your compiler.  If some registers are not saved, or if
+@value{GDBN} is unable to locate the saved registers, the selected stack
+frame makes no difference.
+
+@ifset AMD29K
+@table @code
+@kindex set rstack_high_address
+@cindex AMD 29K register stack
+@cindex register stack, AMD29K
+@item set rstack_high_address @var{address}
+On AMD 29000 family processors, registers are saved in a separate
+``register stack''.  There is no way for @value{GDBN} to determine the extent
+of this stack.  Normally, @value{GDBN} just assumes that the stack is ``large
+enough''.  This may result in @value{GDBN} referencing memory locations that
+do not exist.  If necessary, you can get around this problem by
+specifying the ending address of the register stack with the @code{set
+rstack_high_address} command.  The argument should be an address, which
+you probably want to precede with @samp{0x} to specify in
+hexadecimal.
+
+@kindex show rstack_high_address
+@item show rstack_high_address
+Display the current limit of the register stack, on AMD 29000 family
+processors.
+@end table
+@end ifset
+
+@ifclear HAVE-FLOAT
+@node Floating Point Hardware,  , Registers, Data
+@section Floating point hardware
+@cindex floating point
+
+Depending on the configuration, @value{GDBN} may be able to give
+you more information about the status of the floating point hardware.
+
+@table @code
+@kindex info float
+@item info float
+Display hardware-dependent information about the floating
+point unit.  The exact contents and layout vary depending on the
+floating point chip.  Currently, @samp{info float} is supported on
+the ARM and x86 machines.
+@end table
+@end ifclear
+
+@ifclear CONLY
+@node Languages, Symbols, Data, Top
+@chapter Using @value{GDBN} with Different Languages
+@cindex languages
+
+@ifset MOD2
+Although programming languages generally have common aspects, they are
+rarely expressed in the same manner.  For instance, in ANSI C,
+dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
+Modula-2, it is accomplished by @code{p^}.  Values can also be
+represented (and displayed) differently.  Hex numbers in C appear as 
+@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
+@end ifset
+
+@cindex working language
+Language-specific information is built into @value{GDBN} for some languages,
+allowing you to express operations like the above in your program's
+native language, and allowing @value{GDBN} to output values in a manner
+consistent with the syntax of your program's native language.  The
+language you use to build expressions is called the @dfn{working
+language}.
+
+@menu
+* Setting::                     Switching between source languages
+* Show::                        Displaying the language
+@ifset MOD2
+* Checks::                      Type and range checks
+@end ifset
+
+* Support::                     Supported languages
+@end menu
+
+@node Setting, Show, Languages, Languages
+@section Switching between source languages
+
+There are two ways to control the working language---either have @value{GDBN}
+set it automatically, or select it manually yourself.  You can use the
+@code{set language} command for either purpose.  On startup, @value{GDBN}
+defaults to setting the language automatically.  The working language is
+used to determine how expressions you type are interpreted, how values
+are printed, etc.
+
+In addition to the working language, every source file that
+@value{GDBN} knows about has its own working language.  For some object
+file formats, the compiler might indicate which language a particular
+source file is in.  However, most of the time @value{GDBN} infers the
+language from the name of the file.  The language of a source file
+controls whether C++ names are demangled---this way @code{backtrace} can
+show each frame appropriately for its own language.  There is no way to
+set the language of a source file from within @value{GDBN}.  
+
+This is most commonly a problem when you use a program, such
+as @code{cfront} or @code{f2c}, that generates C but is written in 
+another language.  In that case, make the
+program use @code{#line} directives in its C output; that way
+@value{GDBN} will know the correct language of the source code of the original
+program, and will display that source code, not the generated C code.
+
+@menu
+* Filenames::                   Filename extensions and languages.
+* Manually::                    Setting the working language manually
+* Automatically::               Having @value{GDBN} infer the source language
+@end menu
+
+@node Filenames, Manually, Setting, Setting
+@subsection List of filename extensions and languages
+
+If a source file name ends in one of the following extensions, then
+@value{GDBN} infers that its language is the one indicated.
+
+@table @file
+
+@item .c
+C source file
+
+@item .C
+@itemx .cc
+@itemx .cp
+@itemx .cpp
+@itemx .cxx
+@itemx .c++
+C++ source file
+
+@item .f
+@itemx .F
+Fortran source file
+
+@ifclear HPPA
+@item .ch
+@itemx .c186
+@itemx .c286
+CHILL source file.
+@end ifclear
+
+@ifset MOD2
+@item .mod
+Modula-2 source file
+@end ifset
+
+@item .s
+@itemx .S
+Assembler source file.  This actually behaves almost like C, but
+@value{GDBN} does not skip over function prologues when stepping.
+@end table
+
+In addition, you may set the language associated with a filename
+extension.  @xref{Show, , Displaying the language}.
+
+@node Manually, Automatically, Filenames, Setting
+@subsection Setting the working language
+
+If you allow @value{GDBN} to set the language automatically,
+expressions are interpreted the same way in your debugging session and
+your program.
+
+@kindex set language
+If you wish, you may set the language manually.  To do this, issue the
+command @samp{set language @var{lang}}, where @var{lang} is the name of
+a language, such as 
+@ifclear MOD2
+@code{c}.
+@end ifclear
+@ifset MOD2
+@code{c} or @code{modula-2}.
+@end ifset
+For a list of the supported languages, type @samp{set language}.
+
+@ifclear MOD2
+Setting the language manually prevents @value{GDBN} from updating the
+working language automatically.  For example, if you used the @code{c}
+setting to debug a C++ program, names might not be demangled properly,
+overload resolution would not work, user-defined operators might not be
+interpreted correctly, and so on.
+@end ifclear
+@ifset MOD2
+Setting the language manually prevents @value{GDBN} from updating the working
+language automatically.  This can lead to confusion if you try
+to debug a program when the working language is not the same as the
+source language, when an expression is acceptable to both
+languages---but means different things.  For instance, if the current
+source file were written in C, and @value{GDBN} was parsing Modula-2, a
+command such as:
+
+@example
+print a = b + c
+@end example
+
+@noindent
+might not have the effect you intended.  In C, this means to add
+@code{b} and @code{c} and place the result in @code{a}.  The result
+printed would be the value of @code{a}.  In Modula-2, this means to compare
+@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
+@end ifset
+
+@node Automatically,  , Manually, Setting
+@subsection Having @value{GDBN} infer the source language
+
+To have @value{GDBN} set the working language automatically, use
+@samp{set language local} or @samp{set language auto}.  @value{GDBN}
+then infers the working language.  That is, when your program stops in a
+frame (usually by encountering a breakpoint), @value{GDBN} sets the
+working language to the language recorded for the function in that
+frame.  If the language for a frame is unknown (that is, if the function
+or block corresponding to the frame was defined in a source file that
+does not have a recognized extension), the current working language is
+not changed, and @value{GDBN} issues a warning.
+
+This may not seem necessary for most programs, which are written
+entirely in one source language.  However, program modules and libraries
+written in one source language can be used by a main program written in
+a different source language.  Using @samp{set language auto} in this
+case frees you from having to set the working language manually.
+
+@ifset MOD2
+@node Show, Checks, Setting, Languages
+@section Displaying the language
+@end ifset
+@ifclear MOD2
+@node Show, Support, Setting, Languages
+@section Displaying the language
+@end ifclear
+
+The following commands help you find out which language is the
+working language, and also what language source files were written in.
+
+@kindex show language
+@kindex info frame
+@kindex info source
+@table @code
+@item show language
+Display the current working language.  This is the
+language you can use with commands such as @code{print} to
+build and compute expressions that may involve variables in your program.
+
+@item info frame
+Display the source language for this frame.  This language becomes the 
+working language if you use an identifier from this frame.
+@xref{Frame Info, ,Information about a frame}, to identify the other 
+information listed here.
+
+@item info source
+Display the source language of this source file.
+@xref{Symbols, ,Examining the Symbol Table}, to identify the other 
+information listed here.
+@end table
+
+In unusual circumstances, you may have source files with extensions
+not in the standard list.  You can then set the extension associated
+with a language explicitly:
+
+@kindex set extension-language
+@kindex info extensions
+@table @code
+@item set extension-language @var{.ext} @var{language}
+Set source files with extension @var{.ext} to be assumed to be in
+the source language @var{language}.
+
+@item info extensions
+List all the filename extensions and the associated languages.
+@end table
+
+@ifset MOD2
+@node Checks, Support, Show, Languages
+@section Type and range checking
+
+@quotation
+@emph{Warning:} In this release, the @value{GDBN} commands for type and range
+checking are included, but they do not yet have any effect.  This
+section documents the intended facilities.
+@end quotation
+@c FIXME remove warning when type/range code added
+
+Some languages are designed to guard you against making seemingly common
+errors through a series of compile- and run-time checks.  These include
+checking the type of arguments to functions and operators, and making
+sure mathematical overflows are caught at run time.  Checks such as
+these help to ensure a program's correctness once it has been compiled
+by eliminating type mismatches, and providing active checks for range
+errors when your program is running.
+
+@value{GDBN} can check for conditions like the above if you wish.
+Although @value{GDBN} does not check the statements in your program, it
+can check expressions entered directly into @value{GDBN} for evaluation via
+the @code{print} command, for example.  As with the working language,
+@value{GDBN} can also decide whether or not to check automatically based on
+your program's source language.  @xref{Support, ,Supported languages},
+for the default settings of supported languages.
+
+@menu
+* Type Checking::               An overview of type checking
+* Range Checking::              An overview of range checking
+@end menu
+
+@cindex type checking
+@cindex checks, type
+@node Type Checking, Range Checking, Checks, Checks
+@subsection An overview of type checking
+
+Some languages, such as Modula-2, are strongly typed, meaning that the
+arguments to operators and functions have to be of the correct type,
+otherwise an error occurs.  These checks prevent type mismatch
+errors from ever causing any run-time problems.  For example,
+
+@smallexample
+1 + 2 @result{} 3
+@exdent but
+@error{} 1 + 2.3
+@end smallexample
+
+The second example fails because the @code{CARDINAL} 1 is not
+type-compatible with the @code{REAL} 2.3.
+
+For the expressions you use in @value{GDBN} commands, you can tell the 
+@value{GDBN} type checker to skip checking; 
+to treat any mismatches as errors and abandon the expression; 
+or to only issue warnings when type mismatches occur, 
+but evaluate the expression anyway.  When you choose the last of
+these, @value{GDBN} evaluates expressions like the second example above, but
+also issues a warning.
+
+Even if you turn type checking off, there may be other reasons 
+related to type that prevent @value{GDBN} from evaluating an expression.  
+For instance, @value{GDBN} does not know how to add an @code{int} and 
+a @code{struct foo}.  These particular type errors have nothing to do 
+with the language in use, and usually arise from expressions, such as 
+the one described above, which make little sense to evaluate anyway.
+
+Each language defines to what degree it is strict about type.  For
+instance, both Modula-2 and C require the arguments to arithmetical
+operators to be numbers.  In C, enumerated types and pointers can be
+represented as numbers, so that they are valid arguments to mathematical
+operators.  @xref{Support, ,Supported languages}, for further
+details on specific languages.
+
+@value{GDBN} provides some additional commands for controlling the type checker:
+
+@kindex set check
+@kindex set check type
+@kindex show check type
+@table @code
+@item set check type auto
+Set type checking on or off based on the current working language.
+@xref{Support, ,Supported languages}, for the default settings for
+each language.
+
+@item set check type on
+@itemx set check type off
+Set type checking on or off, overriding the default setting for the
+current working language.  Issue a warning if the setting does not
+match the language default.  If any type mismatches occur in
+evaluating an expression while typechecking is on, @value{GDBN} prints a
+message and aborts evaluation of the expression.
+
+@item set check type warn
+Cause the type checker to issue warnings, but to always attempt to
+evaluate the expression.  Evaluating the expression may still
+be impossible for other reasons.  For example, @value{GDBN} cannot add
+numbers and structures.
+
+@item show type
+Show the current setting of the type checker, and whether or not @value{GDBN} 
+is setting it automatically.
+@end table
+
+@cindex range checking
+@cindex checks, range
+@node Range Checking,  , Type Checking, Checks
+@subsection An overview of range checking
+
+In some languages (such as Modula-2), it is an error to exceed the
+bounds of a type; this is enforced with run-time checks.  Such range
+checking is meant to ensure program correctness by making sure
+computations do not overflow, or indices on an array element access do
+not exceed the bounds of the array.
+
+For expressions you use in @value{GDBN} commands, you can tell
+@value{GDBN} to treat range errors in one of three ways: ignore them,
+always treat them as errors and abandon the expression, or issue
+warnings but evaluate the expression anyway.
+
+A range error can result from numerical overflow, from exceeding an
+array index bound, or when you type a constant that is not a member
+of any type.  Some languages, however, do not treat overflows as an
+error.  In many implementations of C, mathematical overflow causes the
+result to ``wrap around'' to lower values---for example, if @var{m} is
+the largest integer value, and @var{s} is the smallest, then
+
+@example
+@var{m} + 1 @result{} @var{s}
+@end example
+
+This, too, is specific to individual languages, and in some cases
+specific to individual compilers or machines.  @xref{Support, ,
+Supported languages}, for further details on specific languages.
+
+@value{GDBN} provides some additional commands for controlling the range checker:
+
+@kindex set check
+@kindex set check range
+@kindex show check range
+@table @code
+@item set check range auto
+Set range checking on or off based on the current working language.
+@xref{Support, ,Supported languages}, for the default settings for
+each language.
+
+@item set check range on
+@itemx set check range off
+Set range checking on or off, overriding the default setting for the
+current working language.  A warning is issued if the setting does not
+match the language default.  If a range error occurs, then a message
+is printed and evaluation of the expression is aborted.
+
+@item set check range warn
+Output messages when the @value{GDBN} range checker detects a range error,
+but attempt to evaluate the expression anyway.  Evaluating the
+expression may still be impossible for other reasons, such as accessing
+memory that the process does not own (a typical example from many Unix
+systems).
+
+@item show range
+Show the current setting of the range checker, and whether or not it is
+being set automatically by @value{GDBN}.
+@end table
+@end ifset
+
+@ifset MOD2
+@node Support,  , Checks, Languages
+@section Supported languages
+@end ifset
+@ifclear MOD2
+@node Support,  , Show, Languages
+@section Supported languages
+@end ifclear
+
+@ifset MOD2
+@value{GDBN} supports C, C++, Fortran, Chill, assembly, and Modula-2.
+@end ifset
+@ifclear MOD2
+@value{GDBN} supports C, C++, Fortran, Chill, and assembly.
+@end ifclear
+Some @value{GDBN} features may be used in expressions regardless of the
+language you use: the @value{GDBN} @code{@@} and @code{::} operators,
+and the @samp{@{type@}addr} construct (@pxref{Expressions,
+,Expressions}) can be used with the constructs of any supported
+language.
+
+The following sections detail to what degree each source language is
+supported by @value{GDBN}.  These sections are not meant to be language
+tutorials or references, but serve only as a reference guide to what the
+@value{GDBN} expression parser accepts, and what input and output
+formats should look like for different languages.  There are many good
+books written on each of these languages; please look to these for a
+language reference or tutorial.
+
+@ifset MOD2
+@menu
+* C::                           C and C++
+* Modula-2::                    Modula-2
+@end menu
+
+@node C, Modula-2, , Support
+@subsection C and C++
+@cindex C and C++
+@cindex expressions in C or C++
+@end ifset
+
+Since C and C++ are so closely related, many features of @value{GDBN} apply
+to both languages.  Whenever this is the case, we discuss those languages
+together.
+
+@ifclear MOD2
+@c Cancel this below, under same condition, at end of this chapter!
+@raisesections
+@end ifclear
+
+@ifclear HPPA
+@cindex C++
+@kindex g++
+@cindex @sc{gnu} C++
+The C++ debugging facilities are jointly implemented by the C++
+compiler and @value{GDBN}.  Therefore, to debug your C++ code
+effectively, you must compile your C++ programs with a supported
+C++ compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C++
+compiler (@code{aCC}).
+
+For best results when using @sc{gnu} C++, use the stabs debugging
+format.  You can select that format explicitly with the @code{g++}
+command-line options @samp{-gstabs} or @samp{-gstabs+}.  See
+@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
+CC, gcc.info, Using @sc{gnu} CC}, for more information.
+@end ifclear
+@ifset HPPA
+@cindex C++
+@kindex g++
+@cindex @sc{gnu} C++
+You can use @value{GDBN} to debug C programs compiled with either the HP
+C compiler (@code{cc}) or the GNU C compiler (@code{gcc}), and to debug
+programs compiled with either the HP ANSI C++ compiler (@code{aCC}) or
+the @sc{gnu} C++ compiler (@code{g++}).
+
+If you compile with the @sc{gnu} C++ compiler, use the stabs debugging
+format for best results when debugging.  You can select that format
+explicitly with the @code{g++} command-line options @samp{-gstabs} or
+@samp{-gstabs+}.  See @ref{Debugging Options,,Options for Debugging Your
+Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
+information.
+@end ifset
+@end ifclear
+
+@ifset CONLY
+@node C, Symbols, Data, Top
+@chapter C Language Support
+@cindex C language
+@cindex expressions in C
+
+Information specific to the C language is built into @value{GDBN} so that you
+can use C expressions while debugging.  This also permits @value{GDBN} to
+output values in a manner consistent with C conventions.
+
+@menu
+* C Operators::                 C operators
+@end menu
+@end ifset
+
+@ifclear CONLY
+@menu
+* C Operators::                 C and C++ operators
+* C Constants::                 C and C++ constants
+* Cplus expressions::           C++ expressions
+* C Defaults::                  Default settings for C and C++
+@ifset MOD2
+* C Checks::                    C and C++ type and range checks
+@end ifset
+
+* Debugging C::                 @value{GDBN} and C
+* Debugging C plus plus::       @value{GDBN} features for C++
+@end menu
+@end ifclear
+
+@ifclear CONLY
+@cindex C and C++ operators
+@node C Operators, C Constants, , C
+@subsubsection C and C++ operators
+@end ifclear
+@ifset CONLY
+@cindex C operators
+@node C Operators, C Constants, C, C
+@section C operators
+@end ifset
+
+Operators must be defined on values of specific types.  For instance,
+@code{+} is defined on numbers, but not on structures.  Operators are
+often defined on groups of types.  
+
+@ifclear CONLY
+For the purposes of C and C++, the following definitions hold:
+@end ifclear
+
+@itemize @bullet
+@item
+@ifclear HPPA
+@emph{Integral types} include @code{int} with any of its storage-class
+specifiers; @code{char}; and @code{enum}.
+@end ifclear
+@ifset HPPA
+@emph{Integral types} include @code{int} with any of its storage-class
+specifiers; @code{char}; @code{enum}; and, for C++, @code{bool}.
+@end ifset
+
+@item
+@emph{Floating-point types} include @code{float} and @code{double}.
+
+@item
+@emph{Pointer types} include all types defined as @code{(@var{type}
+*)}.
+
+@item
+@emph{Scalar types} include all of the above.
+@end itemize
+
+@noindent
+The following operators are supported.  They are listed here
+in order of increasing precedence:
+
+@table @code
+@item ,
+The comma or sequencing operator.  Expressions in a comma-separated list
+are evaluated from left to right, with the result of the entire
+expression being the last expression evaluated.
+
+@item =
+Assignment.  The value of an assignment expression is the value
+assigned.  Defined on scalar types.
+
+@item @var{op}=
+Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
+and translated to @w{@code{@var{a} = @var{a op b}}}.
+@w{@code{@var{op}=}} and @code{=} have the same precendence.
+@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
+@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
+
+@item ?:
+The ternary operator.  @code{@var{a} ? @var{b} : @var{c}} can be thought
+of as:  if @var{a} then @var{b} else @var{c}.  @var{a} should be of an
+integral type.
+
+@item ||
+Logical @sc{or}.  Defined on integral types.
+
+@item &&
+Logical @sc{and}.  Defined on integral types.
+
+@item |
+Bitwise @sc{or}.  Defined on integral types.
+
+@item ^
+Bitwise exclusive-@sc{or}.  Defined on integral types.
+
+@item &
+Bitwise @sc{and}.  Defined on integral types.
+
+@item ==@r{, }!=
+Equality and inequality.  Defined on scalar types.  The value of these
+expressions is 0 for false and non-zero for true.
+
+@item <@r{, }>@r{, }<=@r{, }>=
+Less than, greater than, less than or equal, greater than or equal.
+Defined on scalar types.  The value of these expressions is 0 for false
+and non-zero for true.
+
+@item <<@r{, }>>
+left shift, and right shift.  Defined on integral types.
+
+@item @@
+The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+
+@item +@r{, }-
+Addition and subtraction.  Defined on integral types, floating-point types and
+pointer types.
+
+@item *@r{, }/@r{, }%
+Multiplication, division, and modulus.  Multiplication and division are
+defined on integral and floating-point types.  Modulus is defined on
+integral types.
+
+@item ++@r{, }--
+Increment and decrement.  When appearing before a variable, the
+operation is performed before the variable is used in an expression;
+when appearing after it, the variable's value is used before the
+operation takes place.
+
+@item *
+Pointer dereferencing.  Defined on pointer types.  Same precedence as
+@code{++}.
+
+@item &
+Address operator.  Defined on variables.  Same precedence as @code{++}.
+
+@ifclear CONLY
+For debugging C++, @value{GDBN} implements a use of @samp{&} beyond what is
+allowed in the C++ language itself: you can use @samp{&(&@var{ref})}
+(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
+where a C++ reference variable (declared with @samp{&@var{ref}}) is
+stored.
+@end ifclear
+
+@item -
+Negative.  Defined on integral and floating-point types.  Same
+precedence as @code{++}.
+
+@item !
+Logical negation.  Defined on integral types.  Same precedence as
+@code{++}.
+
+@item ~
+Bitwise complement operator.  Defined on integral types.  Same precedence as
+@code{++}.
+
+
+@item .@r{, }->
+Structure member, and pointer-to-structure member.  For convenience,
+@value{GDBN} regards the two as equivalent, choosing whether to dereference a
+pointer based on the stored type information.
+Defined on @code{struct} and @code{union} data.
+
+@ifset HPPA
+@item .*@r{, }->*
+Dereferences of pointers to members.
+@end ifset
+
+@item []
+Array indexing.  @code{@var{a}[@var{i}]} is defined as
+@code{*(@var{a}+@var{i})}.  Same precedence as @code{->}.
+
+@item ()
+Function parameter list.  Same precedence as @code{->}.
+
+@ifclear CONLY
+@item ::
+C++ scope resolution operator.  Defined on
+@code{struct}, @code{union}, and @code{class} types.
+@end ifclear
+
+@item ::
+Doubled colons
+@ifclear CONLY
+also
+@end ifclear
+represent the @value{GDBN} scope operator (@pxref{Expressions,
+,Expressions}).
+@ifclear CONLY
+Same precedence as @code{::}, above.
+@end ifclear
+@end table
+
+@ifset HPPA
+If an operator is redefined in the user code, @value{GDBN} usually
+attempts to invoke the redefined version instead of using the operator's
+predefined meaning.
+@end ifset
+
+@ifclear CONLY
+@menu
+* C Constants::             
+@end menu
+
+@ifset MOD2
+@node C Constants, Cplus expressions, C Operators, C
+@subsubsection C and C++ constants
+@end ifset
+@ifclear MOD2
+@node C Constants, Cplus expressions, C Operators, Support
+@subsubsection C and C++ constants
+@end ifclear
+
+@cindex C and C++ constants
+@value{GDBN} allows you to express the constants of C and C++ in the
+following ways:
+@end ifclear
+@ifset CONLY
+@cindex C constants
+@node C Constants, Debugging C, C Operators, C
+@section C constants
+
+@value{GDBN} allows you to express the constants of C in the
+following ways:
+@end ifset
+
+@itemize @bullet
+@item
+Integer constants are a sequence of digits.  Octal constants are
+specified by a leading @samp{0} (i.e. zero), and hexadecimal constants by
+a leading @samp{0x} or @samp{0X}.  Constants may also end with a letter
+@samp{l}, specifying that the constant should be treated as a
+@code{long} value.
+
+@item
+Floating point constants are a sequence of digits, followed by a decimal
+point, followed by a sequence of digits, and optionally followed by an
+exponent.  An exponent is of the form:
+@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
+sequence of digits.  The @samp{+} is optional for positive exponents.
+
+@item
+Enumerated constants consist of enumerated identifiers, or their
+integral equivalents.
+
+@item
+Character constants are a single character surrounded by single quotes
+(@code{'}), or a number---the ordinal value of the corresponding character
+(usually its @sc{ASCII} value).  Within quotes, the single character may
+be represented by a letter or by @dfn{escape sequences}, which are of
+the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
+of the character's ordinal value; or of the form @samp{\@var{x}}, where
+@samp{@var{x}} is a predefined special character---for example,
+@samp{\n} for newline.
+
+@item
+String constants are a sequence of character constants surrounded
+by double quotes (@code{"}).
+
+@item
+Pointer constants are an integral value.  You can also write pointers
+to constants using the C operator @samp{&}.
+
+@item
+Array constants are comma-separated lists surrounded by braces @samp{@{}
+and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
+integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
+and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
+@end itemize
+
+@ifclear CONLY
+@menu
+* Cplus expressions::           
+* C Defaults::                  
+@ifset MOD2
+* C Checks::                    
+@end ifset
+
+* Debugging C::                 
+@end menu
+
+@ifset MOD2
+@node Cplus expressions, C Defaults, C Constants, C
+@subsubsection C++ expressions
+@end ifset
+@ifclear MOD2
+@node Cplus expressions, C Defaults, C Constants, Support
+@subsubsection C++ expressions
+@end ifclear
+
+@cindex expressions in C++
+@value{GDBN} expression handling can interpret most C++ expressions.
+
+@ifclear HPPA
+@cindex C++ support, not in @sc{coff}
+@cindex @sc{coff} versus C++
+@cindex C++ and object formats
+@cindex object formats and C++
+@cindex a.out and C++
+@cindex @sc{ecoff} and C++
+@cindex @sc{xcoff} and C++
+@cindex @sc{elf}/stabs and C++
+@cindex @sc{elf}/@sc{dwarf} and C++
+@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
+@c periodically whether this has happened...
+@quotation
+@emph{Warning:} @value{GDBN} can only debug C++ code if you use the
+proper compiler.  Typically, C++ debugging depends on the use of
+additional debugging information in the symbol table, and thus requires
+special support.  In particular, if your compiler generates a.out, MIPS
+@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
+symbol table, these facilities are all available.  (With @sc{gnu} CC,
+you can use the @samp{-gstabs} option to request stabs debugging
+extensions explicitly.)  Where the object code format is standard
+@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C++
+support in @value{GDBN} does @emph{not} work.
+@end quotation
+@end ifclear
+
+@enumerate
+
+@cindex member functions
+@item
+Member function calls are allowed; you can use expressions like
+
+@example
+count = aml->GetOriginal(x, y)
+@end example
+
+@kindex this
+@cindex namespace in C++
+@item
+While a member function is active (in the selected stack frame), your
+expressions have the same namespace available as the member function;
+that is, @value{GDBN} allows implicit references to the class instance
+pointer @code{this} following the same rules as C++.
+
+@ifclear HPPA
+@cindex call overloaded functions
+@cindex type conversions in C++
+@item
+You can call overloaded functions; @value{GDBN} resolves the function
+call to the right definition, with one restriction---you must use
+arguments of the type required by the function that you want to call.
+@value{GDBN} does not perform conversions requiring constructors or
+user-defined type operators.
+@end ifclear
+@ifset HPPA
+@cindex call overloaded functions
+@cindex overloaded functions
+@cindex type conversions in C++
+@item
+You can call overloaded functions; @value{GDBN} resolves the function
+call to the right definition, with some restrictions.  GDB does not
+perform overload resolution involving user-defined type conversions,
+calls to constructors, or instantiations of templates that do not exist
+in the program.  It also cannot handle ellipsis argument lists or
+default arguments.
+
+It does perform integral conversions and promotions, floating-point
+promotions, arithmetic conversions, pointer conversions, conversions of
+class objects to base classes, and standard conversions such as those of
+functions or arrays to pointers; it requires an exact match on the
+number of function arguments.
+
+Overload resolution is always performed, unless you have specified
+@code{set overload-resolution off}.  @xref{Debugging C plus plus,
+,@value{GDBN} features for C++}.
+
+You must specify@code{set overload-resolution off} in order to use an
+explicit function signature to call an overloaded function, as in
+@smallexample
+p 'foo(char,int)'('x', 13)
+@end smallexample
+The @value{GDBN} command-completion facility can simplify this;
+@pxref{Completion, ,Command completion}.
+
+@end ifset
+
+@cindex reference declarations
+@item
+@value{GDBN} understands variables declared as C++ references; you can use 
+them in expressions just as you do in C++ source---they are automatically
+dereferenced.
+
+In the parameter list shown when @value{GDBN} displays a frame, the values of
+reference variables are not displayed (unlike other variables); this
+avoids clutter, since references are often used for large structures.
+The @emph{address} of a reference variable is always shown, unless
+you have specified @samp{set print address off}.
+
+@item
+@value{GDBN} supports the C++ name resolution operator @code{::}---your
+expressions can use it just as expressions in your program do.  Since
+one scope may be defined in another, you can use @code{::} repeatedly if
+necessary, for example in an expression like
+@samp{@var{scope1}::@var{scope2}::@var{name}}.  @value{GDBN} also allows
+resolving name scope by reference to source files, in both C and C++
+debugging (@pxref{Variables, ,Program variables}).
+@end enumerate
+
+@ifset HPPA
+In addition, @value{GDBN} supports calling virtual functions correctly,
+printing out virtual bases of objects, calling functions in a base
+subobject, casting objects, and invoking user-defined operators.
+@end ifset
+
+@ifset MOD2
+@node C Defaults, C Checks, Cplus expressions, C
+@subsubsection C and C++ defaults
+@end ifset
+@ifclear MOD2
+@node C Defaults, Debugging C, Cplus expressions, Support
+@subsubsection C and C++ defaults
+@end ifclear
+@cindex C and C++ defaults
+
+@ifclear HPPA
+If you allow @value{GDBN} to set type and range checking automatically, they
+both default to @code{off} whenever the working language changes to
+C or C++.  This happens regardless of whether you or @value{GDBN}
+selects the working language.
+@end ifclear
+
+If you allow @value{GDBN} to set the language automatically, it
+recognizes source files whose names end with @file{.c}, @file{.C}, or
+@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
+these files, it sets the working language to C or C++.
+@xref{Automatically, ,Having @value{GDBN} infer the source language},
+for further details.
+
+@ifset MOD2
+@c Type checking is (a) primarily motivated by Modula-2, and (b)
+@c unimplemented.  If (b) changes, it might make sense to let this node
+@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
+@node C Checks, Debugging C, C Defaults, C Constants
+@subsubsection C and C++ type and range checks
+@cindex C and C++ checks
+
+By default, when @value{GDBN} parses C or C++ expressions, type checking
+is not used.  However, if you turn type checking on, @value{GDBN}
+considers two variables type equivalent if:
+
+@itemize @bullet
+@item
+The two variables are structured and have the same structure, union, or
+enumerated tag.
+
+@item
+The two variables have the same type name, or types that have been
+declared equivalent through @code{typedef}.
+
+@ignore
+@c leaving this out because neither J Gilmore nor R Pesch understand it.
+@c FIXME--beers?
+@item
+The two @code{struct}, @code{union}, or @code{enum} variables are
+declared in the same declaration.  (Note: this may not be true for all C
+compilers.)
+@end ignore
+@end itemize
+
+Range checking, if turned on, is done on mathematical operations.  Array
+indices are not checked, since they are often used to index a pointer
+that is not itself an array.
+@end ifset
+@end ifclear
+
+@ifclear CONLY
+@ifset MOD2
+@node Debugging C, Debugging C plus plus, C Checks, C
+@subsubsection @value{GDBN} and C
+@end ifset
+@ifclear MOD2
+@node Debugging C, Debugging C plus plus, C Defaults, Support
+@subsubsection @value{GDBN} and C
+@end ifclear
+@end ifclear
+@ifset CONLY
+@node Debugging C,  , C Constants, C
+@section @value{GDBN} and C
+@end ifset
+
+The @code{set print union} and @code{show print union} commands apply to
+the @code{union} type.  When set to @samp{on}, any @code{union} that is
+inside a @code{struct}
+@ifclear CONLY
+or @code{class}
+@end ifclear
+is also printed.
+Otherwise, it appears as @samp{@{...@}}.
+
+The @code{@@} operator aids in the debugging of dynamic arrays, formed
+with pointers and a memory allocation function.  @xref{Expressions,
+,Expressions}.
+
+@ifclear CONLY
+@menu
+* Debugging C plus plus::       
+@end menu
+
+@ifset MOD2
+@node Debugging C plus plus,  , Debugging C, C
+@subsubsection @value{GDBN} features for C++
+@end ifset
+@ifclear MOD2
+@node Debugging C plus plus,  , Debugging C, Support
+@subsubsection @value{GDBN} features for C++
+@end ifclear
+
+@cindex commands for C++
+Some @value{GDBN} commands are particularly useful with C++, and some are
+designed specifically for use with C++.  Here is a summary:
+
+@table @code
+@cindex break in overloaded functions
+@item @r{breakpoint menus}
+When you want a breakpoint in a function whose name is overloaded,
+@value{GDBN} breakpoint menus help you specify which function definition
+you want.  @xref{Breakpoint Menus,,Breakpoint menus}.
+
+@cindex overloading in C++
+@item rbreak @var{regex}
+Setting breakpoints using regular expressions is helpful for setting
+breakpoints on overloaded functions that are not members of any special
+classes.
+@xref{Set Breaks, ,Setting breakpoints}.
+
+@cindex C++ exception handling
+@item catch throw
+@itemx catch catch
+Debug C++ exception handling using these commands.  @xref{Set
+Catchpoints, , Setting catchpoints}.
+
+@cindex inheritance
+@item ptype @var{typename}
+Print inheritance relationships as well as other information for type
+@var{typename}.
+@xref{Symbols, ,Examining the Symbol Table}.
+
+@cindex C++ symbol display
+@item set print demangle
+@itemx show print demangle
+@itemx set print asm-demangle
+@itemx show print asm-demangle
+Control whether C++ symbols display in their source form, both when
+displaying code as C++ source and when displaying disassemblies.
+@xref{Print Settings, ,Print settings}.
+
+@item set print object
+@itemx show print object
+Choose whether to print derived (actual) or declared types of objects.
+@xref{Print Settings, ,Print settings}.
+
+@item set print vtbl
+@itemx show print vtbl
+Control the format for printing virtual function tables.
+@xref{Print Settings, ,Print settings}.
+@ifset HPPA
+(The @code{vtbl} commands do not work on programs compiled with the HP
+ANSI C++ compiler (@code{aCC}).)
+
+@kindex set overload-resolution
+@cindex overloaded functions
+@item set overload-resolution on
+Enable overload resolution for C++ expression evaluation.  The default
+is on.  For overloaded functions, @value{GDBN} evaluates the arguments
+and searches for a function whose signature matches the argument types,
+using the standard C++ conversion rules (@pxref{Cplus expressions, ,C++
+expressions} for details).  If it cannot find a match, it emits a
+message.
+
+@item set overload-resolution off
+Disable overload resolution for C++ expression evaluation.  For
+overloaded functions that are not class member functions, @value{GDBN}
+chooses the first function of the specified name that it finds in the
+symbol table, whether or not its arguments are of the correct type.  For
+overloaded functions that are class member functions, @value{GDBN}
+searches for a function whose signature @emph{exactly} matches the
+argument types.
+@end ifset
+
+@item @r{Overloaded symbol names}
+You can specify a particular definition of an overloaded symbol, using
+the same notation that is used to declare such symbols in C++: type
+@code{@var{symbol}(@var{types})} rather than just @var{symbol}.  You can
+also use the @value{GDBN} command-line word completion facilities to list the
+available choices, or to finish the type list for you.
+@xref{Completion,, Command completion}, for details on how to do this.
+@end table
+@ifclear MOD2
+@c cancels "raisesections" under same conditions near bgn of chapter
+@lowersections
+@end ifclear
+
+@ifset MOD2
+@node Modula-2,  ,C , Support
+@subsection Modula-2
+@cindex Modula-2
+
+The extensions made to @value{GDBN} to support Modula-2 only support
+output from the @sc{gnu} Modula-2 compiler (which is currently being
+developed).  Other Modula-2 compilers are not currently supported, and
+attempting to debug executables produced by them is most likely
+to give an error as @value{GDBN} reads in the executable's symbol
+table.
+
+@cindex expressions in Modula-2
+@menu
+* M2 Operators::                Built-in operators
+* Built-In Func/Proc::          Built-in functions and procedures
+* M2 Constants::                Modula-2 constants
+* M2 Defaults::                 Default settings for Modula-2
+* Deviations::                  Deviations from standard Modula-2
+* M2 Checks::                   Modula-2 type and range checks
+* M2 Scope::                    The scope operators @code{::} and @code{.}
+* GDB/M2::                      @value{GDBN} and Modula-2
+@end menu
+
+@node M2 Operators, Built-In Func/Proc, Modula-2, Modula-2
+@subsubsection Operators
+@cindex Modula-2 operators
+
+Operators must be defined on values of specific types.  For instance,
+@code{+} is defined on numbers, but not on structures.  Operators are
+often defined on groups of types.  For the purposes of Modula-2, the
+following definitions hold:
+
+@itemize @bullet
+
+@item
+@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
+their subranges.
+
+@item
+@emph{Character types} consist of @code{CHAR} and its subranges.
+
+@item
+@emph{Floating-point types} consist of @code{REAL}.
+
+@item
+@emph{Pointer types} consist of anything declared as @code{POINTER TO
+@var{type}}.
+
+@item
+@emph{Scalar types} consist of all of the above.
+
+@item
+@emph{Set types} consist of @code{SET} and @code{BITSET} types.
+
+@item
+@emph{Boolean types} consist of @code{BOOLEAN}.
+@end itemize
+
+@noindent
+The following operators are supported, and appear in order of
+increasing precedence:
+
+@table @code
+@item ,
+Function argument or array index separator.
+
+@item :=
+Assignment.  The value of @var{var} @code{:=} @var{value} is
+@var{value}.
+
+@item <@r{, }>
+Less than, greater than on integral, floating-point, or enumerated
+types.
+
+@item <=@r{, }>=
+Less than, greater than, less than or equal to, greater than or equal to
+on integral, floating-point and enumerated types, or set inclusion on
+set types.  Same precedence as @code{<}.
+
+@item =@r{, }<>@r{, }#
+Equality and two ways of expressing inequality, valid on scalar types.
+Same precedence as @code{<}.  In @value{GDBN} scripts, only @code{<>} is
+available for inequality, since @code{#} conflicts with the script
+comment character.
+
+@item IN
+Set membership.  Defined on set types and the types of their members.
+Same precedence as @code{<}.
+
+@item OR
+Boolean disjunction.  Defined on boolean types.
+
+@item AND@r{, }&
+Boolean conjuction.  Defined on boolean types.
+
+@item @@
+The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
+
+@item +@r{, }-
+Addition and subtraction on integral and floating-point types, or union
+and difference on set types.
+
+@item *
+Multiplication on integral and floating-point types, or set intersection
+on set types.
+
+@item /
+Division on floating-point types, or symmetric set difference on set
+types.  Same precedence as @code{*}.
+
+@item DIV@r{, }MOD
+Integer division and remainder.  Defined on integral types.  Same
+precedence as @code{*}.
+
+@item -
+Negative. Defined on @code{INTEGER} and @code{REAL} data.
+
+@item ^
+Pointer dereferencing.  Defined on pointer types.
+
+@item NOT
+Boolean negation.  Defined on boolean types.  Same precedence as
+@code{^}.
+
+@item .
+@code{RECORD} field selector.  Defined on @code{RECORD} data.  Same
+precedence as @code{^}.
+
+@item []
+Array indexing.  Defined on @code{ARRAY} data.  Same precedence as @code{^}.
+
+@item ()
+Procedure argument list.  Defined on @code{PROCEDURE} objects.  Same precedence
+as @code{^}.
+
+@item ::@r{, }.
+@value{GDBN} and Modula-2 scope operators.
+@end table
+
+@quotation
+@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN}
+treats the use of the operator @code{IN}, or the use of operators
+@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
+@code{<=}, and @code{>=} on sets as an error.
+@end quotation
+
+@cindex Modula-2 built-ins
+@node Built-In Func/Proc, M2 Constants, M2 Operators, Modula-2
+@subsubsection Built-in functions and procedures
+
+Modula-2 also makes available several built-in procedures and functions.
+In describing these, the following metavariables are used:
+
+@table @var
+
+@item a
+represents an @code{ARRAY} variable.
+
+@item c
+represents a @code{CHAR} constant or variable.
+
+@item i
+represents a variable or constant of integral type.
+
+@item m
+represents an identifier that belongs to a set.  Generally used in the
+same function with the metavariable @var{s}.  The type of @var{s} should
+be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
+
+@item n
+represents a variable or constant of integral or floating-point type.
+
+@item r
+represents a variable or constant of floating-point type.
+
+@item t
+represents a type.
+
+@item v
+represents a variable.
+
+@item x
+represents a variable or constant of one of many types.  See the
+explanation of the function for details.
+@end table
+
+All Modula-2 built-in procedures also return a result, described below.
+
+@table @code
+@item ABS(@var{n})
+Returns the absolute value of @var{n}.
+
+@item CAP(@var{c})
+If @var{c} is a lower case letter, it returns its upper case
+equivalent, otherwise it returns its argument
+
+@item CHR(@var{i})
+Returns the character whose ordinal value is @var{i}.
+
+@item DEC(@var{v})
+Decrements the value in the variable @var{v}.  Returns the new value.
+
+@item DEC(@var{v},@var{i})
+Decrements the value in the variable @var{v} by @var{i}.  Returns the
+new value.
+
+@item EXCL(@var{m},@var{s})
+Removes the element @var{m} from the set @var{s}.  Returns the new
+set.
+
+@item FLOAT(@var{i})
+Returns the floating point equivalent of the integer @var{i}.
+
+@item HIGH(@var{a})
+Returns the index of the last member of @var{a}.
+
+@item INC(@var{v})
+Increments the value in the variable @var{v}.  Returns the new value.
+
+@item INC(@var{v},@var{i})
+Increments the value in the variable @var{v} by @var{i}.  Returns the
+new value.
+
+@item INCL(@var{m},@var{s})
+Adds the element @var{m} to the set @var{s} if it is not already
+there.  Returns the new set.
+
+@item MAX(@var{t})
+Returns the maximum value of the type @var{t}.
+
+@item MIN(@var{t})
+Returns the minimum value of the type @var{t}.
+
+@item ODD(@var{i})
+Returns boolean TRUE if @var{i} is an odd number.
+
+@item ORD(@var{x})
+Returns the ordinal value of its argument.  For example, the ordinal
+value of a character is its ASCII value (on machines supporting the
+ASCII character set).  @var{x} must be of an ordered type, which include
+integral, character and enumerated types.
+
+@item SIZE(@var{x})
+Returns the size of its argument.  @var{x} can be a variable or a type.
+
+@item TRUNC(@var{r})
+Returns the integral part of @var{r}.
+
+@item VAL(@var{t},@var{i})
+Returns the member of the type @var{t} whose ordinal value is @var{i}.
+@end table
+
+@quotation
+@emph{Warning:}  Sets and their operations are not yet supported, so
+@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
+an error.
+@end quotation
+
+@cindex Modula-2 constants
+@node M2 Constants, M2 Defaults, Built-In Func/Proc, Modula-2
+@subsubsection Constants
+
+@value{GDBN} allows you to express the constants of Modula-2 in the following
+ways:
+
+@itemize @bullet
+
+@item
+Integer constants are simply a sequence of digits.  When used in an
+expression, a constant is interpreted to be type-compatible with the
+rest of the expression.  Hexadecimal integers are specified by a
+trailing @samp{H}, and octal integers by a trailing @samp{B}.
+
+@item
+Floating point constants appear as a sequence of digits, followed by a
+decimal point and another sequence of digits.  An optional exponent can
+then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
+@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent.  All of the
+digits of the floating point constant must be valid decimal (base 10)
+digits.
+
+@item
+Character constants consist of a single character enclosed by a pair of
+like quotes, either single (@code{'}) or double (@code{"}).  They may
+also be expressed by their ordinal value (their ASCII value, usually)
+followed by a @samp{C}.
+
+@item
+String constants consist of a sequence of characters enclosed by a
+pair of like quotes, either single (@code{'}) or double (@code{"}).
+Escape sequences in the style of C are also allowed.  @xref{C
+Constants, ,C and C++ constants}, for a brief explanation of escape
+sequences.
+
+@item
+Enumerated constants consist of an enumerated identifier.
+
+@item
+Boolean constants consist of the identifiers @code{TRUE} and
+@code{FALSE}.
+
+@item
+Pointer constants consist of integral values only.
+
+@item
+Set constants are not yet supported.
+@end itemize
+
+@node M2 Defaults, Deviations, M2 Constants, Modula-2
+@subsubsection Modula-2 defaults
+@cindex Modula-2 defaults
+
+If type and range checking are set automatically by @value{GDBN}, they
+both default to @code{on} whenever the working language changes to
+Modula-2.  This happens regardless of whether you, or @value{GDBN},
+selected the working language.
+
+If you allow @value{GDBN} to set the language automatically, then entering
+code compiled from a file whose name ends with @file{.mod} sets the
+working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
+the language automatically}, for further details.
+
+@node Deviations, M2 Checks, M2 Defaults, Modula-2
+@subsubsection Deviations from standard Modula-2
+@cindex Modula-2, deviations from
+
+A few changes have been made to make Modula-2 programs easier to debug.
+This is done primarily via loosening its type strictness:
+
+@itemize @bullet
+@item
+Unlike in standard Modula-2, pointer constants can be formed by
+integers.  This allows you to modify pointer variables during
+debugging.  (In standard Modula-2, the actual address contained in a
+pointer variable is hidden from you; it can only be modified
+through direct assignment to another pointer variable or expression that
+returned a pointer.)
+
+@item
+C escape sequences can be used in strings and characters to represent
+non-printable characters.  @value{GDBN} prints out strings with these
+escape sequences embedded.  Single non-printable characters are
+printed using the @samp{CHR(@var{nnn})} format.
+
+@item
+The assignment operator (@code{:=}) returns the value of its right-hand
+argument.
+
+@item
+All built-in procedures both modify @emph{and} return their argument.
+@end itemize
+
+@node M2 Checks, M2 Scope, Deviations, Modula-2
+@subsubsection Modula-2 type and range checks
+@cindex Modula-2 checks
+
+@quotation
+@emph{Warning:} in this release, @value{GDBN} does not yet perform type or
+range checking.
+@end quotation
+@c FIXME remove warning when type/range checks added
+
+@value{GDBN} considers two Modula-2 variables type equivalent if:
+
+@itemize @bullet
+@item
+They are of types that have been declared equivalent via a @code{TYPE
+@var{t1} = @var{t2}} statement
+
+@item
+They have been declared on the same line.  (Note:  This is true of the
+@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
+@end itemize
+
+As long as type checking is enabled, any attempt to combine variables
+whose types are not equivalent is an error.
+
+Range checking is done on all mathematical operations, assignment, array
+index bounds, and all built-in functions and procedures.
+
+@node M2 Scope, GDB/M2, M2 Checks, Modula-2
+@subsubsection The scope operators @code{::} and @code{.}
+@cindex scope
+@kindex .
+@cindex colon, doubled as scope operator
+@ifinfo
+@kindex colon-colon
+@c Info cannot handle :: but TeX can.
+@end ifinfo
+@iftex
+@kindex ::
+@end iftex
+
+There are a few subtle differences between the Modula-2 scope operator
+(@code{.}) and the @value{GDBN} scope operator (@code{::}).  The two have
+similar syntax:
+
+@example
+
+@var{module} . @var{id}
+@var{scope} :: @var{id}
+@end example
+
+@noindent
+where @var{scope} is the name of a module or a procedure,
+@var{module} the name of a module, and @var{id} is any declared
+identifier within your program, except another module.
+
+Using the @code{::} operator makes @value{GDBN} search the scope
+specified by @var{scope} for the identifier @var{id}.  If it is not
+found in the specified scope, then @value{GDBN} searches all scopes
+enclosing the one specified by @var{scope}.
+
+Using the @code{.} operator makes @value{GDBN} search the current scope for
+the identifier specified by @var{id} that was imported from the
+definition module specified by @var{module}.  With this operator, it is
+an error if the identifier @var{id} was not imported from definition
+module @var{module}, or if @var{id} is not an identifier in
+@var{module}.
+
+@node GDB/M2,  , M2 Scope, Modula-2
+@subsubsection @value{GDBN} and Modula-2
+
+Some @value{GDBN} commands have little use when debugging Modula-2 programs.
+Five subcommands of @code{set print} and @code{show print} apply
+specifically to C and C++: @samp{vtbl}, @samp{demangle},
+@samp{asm-demangle}, @samp{object}, and @samp{union}.  The first four
+apply to C++, and the last to the C @code{union} type, which has no direct
+analogue in Modula-2.
+
+The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
+while using any language, is not useful with Modula-2.  Its
+intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
+created in Modula-2 as they can in C or C++.  However, because an
+address can be specified by an integral constant, the construct
+@samp{@{@var{type}@}@var{adrexp}} is still useful.  (@pxref{Expressions, ,Expressions})
+
+@cindex @code{#} in Modula-2
+In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
+interpreted as the beginning of a comment.  Use @code{<>} instead.
+@end ifset
+@end ifclear
+
+@node Symbols, Altering, Languages, Top
+@chapter Examining the Symbol Table
+
+The commands described in this section allow you to inquire about the
+symbols (names of variables, functions and types) defined in your
+program.  This information is inherent in the text of your program and
+does not change as your program executes.  @value{GDBN} finds it in your
+program's symbol table, in the file indicated when you started @value{GDBN}
+(@pxref{File Options, ,Choosing files}), or by one of the
+file-management commands (@pxref{Files, ,Commands to specify files}).
+
+@cindex symbol names
+@cindex names of symbols
+@cindex quoting names
+Occasionally, you may need to refer to symbols that contain unusual
+characters, which @value{GDBN} ordinarily treats as word delimiters.  The
+most frequent case is in referring to static variables in other
+source files (@pxref{Variables,,Program variables}).  File names
+are recorded in object files as debugging symbols, but @value{GDBN} would
+ordinarily parse a typical file name, like @file{foo.c}, as the three words
+@samp{foo} @samp{.} @samp{c}.  To allow @value{GDBN} to recognize
+@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
+
+@example
+p 'foo.c'::x
+@end example
+
+@noindent
+looks up the value of @code{x} in the scope of the file @file{foo.c}.
+
+@table @code
+@kindex info address
+@item info address @var{symbol}
+Describe where the data for @var{symbol} is stored.  For a register
+variable, this says which register it is kept in.  For a non-register
+local variable, this prints the stack-frame offset at which the variable
+is always stored.
+
+Note the contrast with @samp{print &@var{symbol}}, which does not work
+at all for a register variable, and for a stack local variable prints
+the exact address of the current instantiation of the variable.
+
+@kindex whatis
+@item whatis @var{exp}
+Print the data type of expression @var{exp}.  @var{exp} is not
+actually evaluated, and any side-effecting operations (such as
+assignments or function calls) inside it do not take place.
+@xref{Expressions, ,Expressions}.
+
+@item whatis
+Print the data type of @code{$}, the last value in the value history.
+
+@kindex ptype
+@item ptype @var{typename}
+Print a description of data type @var{typename}.  @var{typename} may be
+the name of a type, or for C code it may have the form
+@ifclear CONLY
+@samp{class @var{class-name}},
+@end ifclear
+@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
+@samp{enum @var{enum-tag}}.
+
+@item ptype @var{exp}
+@itemx ptype
+Print a description of the type of expression @var{exp}.  @code{ptype}
+differs from @code{whatis} by printing a detailed description, instead
+of just the name of the type.
+
+For example, for this variable declaration:
+
+@example
+struct complex @{double real; double imag;@} v;
+@end example
+
+@noindent
+the two commands give this output:
+
+@example
+@group
+(@value{GDBP}) whatis v
+type = struct complex
+(@value{GDBP}) ptype v
+type = struct complex @{
+    double real;
+    double imag;
+@}
+@end group
+@end example
+
+@noindent
+As with @code{whatis}, using @code{ptype} without an argument refers to
+the type of @code{$}, the last value in the value history.
+
+@kindex info types
+@item info types @var{regexp}
+@itemx info types
+Print a brief description of all types whose name matches @var{regexp}
+(or all types in your program, if you supply no argument).  Each
+complete typename is matched as though it were a complete line; thus,
+@samp{i type value} gives information on all types in your program whose
+name includes the string @code{value}, but @samp{i type ^value$} gives
+information only on types whose complete name is @code{value}.
+
+This command differs from @code{ptype} in two ways: first, like
+@code{whatis}, it does not print a detailed description; second, it
+lists all source files where a type is defined.
+
+@kindex info source
+@item info source
+Show the name of the current source file---that is, the source file for
+the function containing the current point of execution---and the language
+it was written in.
+
+@kindex info sources
+@item info sources
+Print the names of all source files in your program for which there is
+debugging information, organized into two lists: files whose symbols
+have already been read, and files whose symbols will be read when needed.
+
+@kindex info functions
+@item info functions
+Print the names and data types of all defined functions.
+
+@item info functions @var{regexp}
+Print the names and data types of all defined functions
+whose names contain a match for regular expression @var{regexp}.
+Thus, @samp{info fun step} finds all functions whose names
+include @code{step}; @samp{info fun ^step} finds those whose names
+start with @code{step}.
+
+@kindex info variables
+@item info variables
+Print the names and data types of all variables that are declared
+outside of functions (i.e., excluding local variables).
+
+@item info variables @var{regexp}
+Print the names and data types of all variables (except for local
+variables) whose names contain a match for regular expression
+@var{regexp}.
+
+@ignore
+This was never implemented.
+@kindex info methods
+@item info methods
+@itemx info methods @var{regexp}
+The @code{info methods} command permits the user to examine all defined
+methods within C++ program, or (with the @var{regexp} argument) a
+specific set of methods found in the various C++ classes.  Many
+C++ classes provide a large number of methods.  Thus, the output
+from the @code{ptype} command can be overwhelming and hard to use.  The
+@code{info-methods} command filters the methods, printing only those
+which match the regular-expression @var{regexp}.
+@end ignore
+
+@ifclear HPPA
+@cindex reloading symbols
+Some systems allow individual object files that make up your program to
+be replaced without stopping and restarting your program.
+@ifset VXWORKS
+For example, in VxWorks you can simply recompile a defective object file
+and keep on running.
+@end ifset
+If you are running on one of these systems, you can allow @value{GDBN} to
+reload the symbols for automatically relinked modules:
+
+@table @code
+@kindex set symbol-reloading
+@item set symbol-reloading on
+Replace symbol definitions for the corresponding source file when an
+object file with a particular name is seen again.
+
+@item set symbol-reloading off
+Do not replace symbol definitions when re-encountering object files of
+the same name.  This is the default state; if you are not running on a
+system that permits automatically relinking modules, you should leave
+@code{symbol-reloading} off, since otherwise @value{GDBN} may discard symbols
+when linking large programs, that may contain several modules (from
+different directories or libraries) with the same name.
+
+@kindex show symbol-reloading
+@item show symbol-reloading
+Show the current @code{on} or @code{off} setting.
+@end table
+@end ifclear
+
+@ifset HPPA
+@kindex set opaque-type-resolution
+@item set opaque-type-resolution on
+Tell @value{GDBN} to resolve opaque types.  An opaque type is a type
+declared as a pointer to a @code{struct}, @code{class}, or
+@code{union}---for example, @code{struct MyType *}---that is used in one
+source file although the full declaration of @code{struct MyType} is in
+another source file.  The default is on.
+
+A change in the setting of this subcommand will not take effect until
+the next time symbols for a file are loaded.
+
+@item set opaque-type-resolution off
+Tell @value{GDBN} not to resolve opaque types.  In this case, the type
+is printed as follows:
+@smallexample
+@{<no data fields>@}
+@end smallexample
+
+@kindex show opaque-type-resolution
+@item show opaque-type-resolution
+Show whether opaque types are resolved or not.
+@end ifset
+
+@kindex maint print symbols
+@cindex symbol dump
+@kindex maint print psymbols
+@cindex partial symbol dump
+@item maint print symbols @var{filename}
+@itemx maint print psymbols @var{filename}
+@itemx maint print msymbols @var{filename}
+Write a dump of debugging symbol data into the file @var{filename}.
+These commands are used to debug the @value{GDBN} symbol-reading code.  Only
+symbols with debugging data are included.  If you use @samp{maint print
+symbols}, @value{GDBN} includes all the symbols for which it has already
+collected full details: that is, @var{filename} reflects symbols for
+only those files whose symbols @value{GDBN} has read.  You can use the
+command @code{info sources} to find out which files these are.  If you
+use @samp{maint print psymbols} instead, the dump shows information about
+symbols that @value{GDBN} only knows partially---that is, symbols defined in
+files that @value{GDBN} has skimmed, but not yet read completely.  Finally,
+@samp{maint print msymbols} dumps just the minimal symbol information
+required for each object file from which @value{GDBN} has read some symbols.
+@xref{Files, ,Commands to specify files}, for a discussion of how
+@value{GDBN} reads symbols (in the description of @code{symbol-file}).
+@end table
+
+@node Altering, GDB Files, Symbols, Top
+@chapter Altering Execution
+
+Once you think you have found an error in your program, you might want to
+find out for certain whether correcting the apparent error would lead to
+correct results in the rest of the run.  You can find the answer by
+experiment, using the @value{GDBN} features for altering execution of the
+program.
+
+For example, you can store new values into variables or memory
+locations,
+@ifclear BARETARGET
+give your program a signal, restart it
+@end ifclear
+@ifset BARETARGET
+restart your program
+@end ifset
+at a different address, or even return prematurely from a function.
+
+@menu
+* Assignment::                  Assignment to variables
+* Jumping::                     Continuing at a different address
+@ifclear BARETARGET
+* Signaling::                   Giving your program a signal
+@end ifclear
+
+* Returning::                   Returning from a function
+* Calling::                     Calling your program's functions
+* Patching::                    Patching your program
+@end menu
+
+@node Assignment, Jumping, Altering, Altering
+@section Assignment to variables
+
+@cindex assignment
+@cindex setting variables
+To alter the value of a variable, evaluate an assignment expression.
+@xref{Expressions, ,Expressions}.  For example,
+
+@example
+print x=4
+@end example
+
+@noindent
+stores the value 4 into the variable @code{x}, and then prints the
+value of the assignment expression (which is 4).  
+@ifclear CONLY
+@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
+information on operators in supported languages.
+@end ifclear
+
+@kindex set variable
+@cindex variables, setting
+If you are not interested in seeing the value of the assignment, use the
+@code{set} command instead of the @code{print} command.  @code{set} is
+really the same as @code{print} except that the expression's value is
+not printed and is not put in the value history (@pxref{Value History,
+,Value history}).  The expression is evaluated only for its effects.
+
+@ifclear HPPA
+If the beginning of the argument string of the @code{set} command
+appears identical to a @code{set} subcommand, use the @code{set
+variable} command instead of just @code{set}.  This command is identical
+to @code{set} except for its lack of subcommands.  For example, if your
+program has a variable @code{width}, you get an error if you try to set
+a new value with just @samp{set width=13}, because @value{GDBN} has the
+command @code{set width}:
+
+@example
+(@value{GDBP}) whatis width
+type = double
+(@value{GDBP}) p width
+$4 = 13
+(@value{GDBP}) set width=47
+Invalid syntax in expression.
+@end example
+
+@noindent
+The invalid expression, of course, is @samp{=47}.  In
+order to actually set the program's variable @code{width}, use
+
+@example
+(@value{GDBP}) set var width=47
+@end example
+@end ifclear
+@ifset HPPA
+Because the @code{set} command has many subcommands that can conflict
+with the names of program variables, it is a good idea to use the
+@code{set variable} command instead of just @code{set}.  For example, if
+your program has a variable @code{g}, you run into problems if you try
+to set a new value with just @samp{set g=4}, because @value{GDBN} has
+the command @code{set gnutarget}, abbreviated @code{set g}:
+
+@example
+@group
+(@value{GDBP}) whatis g
+type = double
+(@value{GDBP}) p g
+$1 = 1
+(@value{GDBP}) set g=4
+(gdb) p g
+$2 = 1
+(@value{GDBP}) r
+The program being debugged has been started already.
+Start it from the beginning? (y or n) y
+Starting program: /home/smith/cc_progs/a.out
+"/home/smith/cc_progs/a.out": can't open to read symbols: Invalid bfd target.
+(@value{GDBP}) show g
+The current BFD target is "=4".
+@end group
+@end example
+
+@noindent
+The program variable @code{g} did not change, and you silently set the
+@code{gnutarget} to an invalid value.  In order to set the variable
+@code{g}, use
+
+@example
+(@value{GDBP}) set var g=4
+@end example
+@end ifset
+
+@value{GDBN} allows more implicit conversions in assignments than C; you can
+freely store an integer value into a pointer variable or vice versa,
+and you can convert any structure to any other structure that is the
+same length or shorter.
+@comment FIXME: how do structs align/pad in these conversions?
+@comment        /doc@cygnus.com 18dec1990
+
+To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
+construct to generate a value of specified type at a specified address
+(@pxref{Expressions, ,Expressions}).  For example, @code{@{int@}0x83040} refers
+to memory location @code{0x83040} as an integer (which implies a certain size
+and representation in memory), and
+
+@example
+set @{int@}0x83040 = 4
+@end example
+
+@noindent
+stores the value 4 into that memory location.
+
+@node Jumping, Signaling, Assignment, Altering
+@section Continuing at a different address
+
+Ordinarily, when you continue your program, you do so at the place where
+it stopped, with the @code{continue} command.  You can instead continue at
+an address of your own choosing, with the following commands:
+
+@table @code
+@kindex jump
+@item jump @var{linespec}
+Resume execution at line @var{linespec}.  Execution stops again
+immediately if there is a breakpoint there.  @xref{List, ,Printing
+source lines}, for a description of the different forms of
+@var{linespec}.  It is common practice to use the @code{tbreak} command
+in conjunction with @code{jump}.  @xref{Set Breaks, ,Setting
+breakpoints}.
+
+The @code{jump} command does not change the current stack frame, or
+the stack pointer, or the contents of any memory location or any
+register other than the program counter.  If line @var{linespec} is in
+a different function from the one currently executing, the results may
+be bizarre if the two functions expect different patterns of arguments or
+of local variables.  For this reason, the @code{jump} command requests
+confirmation if the specified line is not in the function currently
+executing.  However, even bizarre results are predictable if you are
+well acquainted with the machine-language code of your program.
+
+@item jump *@var{address}
+Resume execution at the instruction at address @var{address}.
+@end table
+
+@ifclear HPPA
+@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
+You can get much the same effect as the @code{jump} command by storing a
+new value into the register @code{$pc}.  The difference is that this
+does not start your program running; it only changes the address of where it
+@emph{will} run when you continue.  For example,
+
+@example
+set $pc = 0x485
+@end example
+
+@noindent
+makes the next @code{continue} command or stepping command execute at
+address @code{0x485}, rather than at the address where your program stopped.
+@xref{Continuing and Stepping, ,Continuing and stepping}.
+@end ifclear
+
+The most common occasion to use the @code{jump} command is to back
+up---perhaps with more breakpoints set---over a portion of a program
+that has already executed, in order to examine its execution in more
+detail.
+
+@ifclear BARETARGET
+@c @group
+@node Signaling, Returning, Jumping, Altering
+@section Giving your program a signal
+
+@table @code
+@kindex signal
+@item signal @var{signal}
+Resume execution where your program stopped, but immediately give it the
+signal @var{signal}.  @var{signal} can be the name or the number of a
+signal.  For example, on many systems @code{signal 2} and @code{signal
+SIGINT} are both ways of sending an interrupt signal.
+
+Alternatively, if @var{signal} is zero, continue execution without
+giving a signal.  This is useful when your program stopped on account of
+a signal and would ordinary see the signal when resumed with the
+@code{continue} command; @samp{signal 0} causes it to resume without a
+signal.
+
+@code{signal} does not repeat when you press @key{RET} a second time
+after executing the command.
+@end table
+@c @end group
+
+Invoking the @code{signal} command is not the same as invoking the
+@code{kill} utility from the shell.  Sending a signal with @code{kill}
+causes @value{GDBN} to decide what to do with the signal depending on
+the signal handling tables (@pxref{Signals}).  The @code{signal} command
+passes the signal directly to your program.
+
+@end ifclear
+
+@node Returning, Calling, Signaling, Altering
+@section Returning from a function
+
+@table @code
+@cindex returning from a function
+@kindex return
+@item return
+@itemx return @var{expression}
+You can cancel execution of a function call with the @code{return}
+command.  If you give an
+@var{expression} argument, its value is used as the function's return
+value.
+@end table
+
+When you use @code{return}, @value{GDBN} discards the selected stack frame
+(and all frames within it).  You can think of this as making the
+discarded frame return prematurely.  If you wish to specify a value to
+be returned, give that value as the argument to @code{return}.
+
+This pops the selected stack frame (@pxref{Selection, ,Selecting a
+frame}), and any other frames inside of it, leaving its caller as the
+innermost remaining frame.  That frame becomes selected.  The
+specified value is stored in the registers used for returning values
+of functions.
+
+The @code{return} command does not resume execution; it leaves the
+program stopped in the state that would exist if the function had just
+returned.  In contrast, the @code{finish} command (@pxref{Continuing
+and Stepping, ,Continuing and stepping}) resumes execution until the
+selected stack frame returns naturally.
+
+@node Calling, Patching, Returning, Altering
+@section Calling program functions
+
+@cindex calling functions
+@kindex call
+@table @code
+@item call @var{expr}
+Evaluate the expression @var{expr} without displaying @code{void}
+returned values.
+@end table
+
+You can use this variant of the @code{print} command if you want to
+execute a function from your program, but without cluttering the output
+with @code{void} returned values.  If the result is not void, it 
+is printed and saved in the value history. 
+
+@ifclear HPPA
+For the A29K, a user-controlled variable @code{call_scratch_address},
+specifies the location of a scratch area to be used when @value{GDBN}
+calls a function in the target.  This is necessary because the usual
+method of putting the scratch area on the stack does not work in systems
+that have separate instruction and data spaces.
+@end ifclear
+
+@node Patching,  , Calling, Altering
+@section Patching programs
+@cindex patching binaries
+@cindex writing into executables
+@ifclear BARETARGET
+@cindex writing into corefiles
+@end ifclear
+
+By default, @value{GDBN} opens the file containing your program's executable
+code
+@ifclear BARETARGET
+(or the corefile)
+@end ifclear
+read-only.  This prevents accidental alterations
+to machine code; but it also prevents you from intentionally patching
+your program's binary.
+
+If you'd like to be able to patch the binary, you can specify that
+explicitly with the @code{set write} command.  For example, you might
+want to turn on internal debugging flags, or even to make emergency
+repairs.
+
+@table @code
+@kindex set write
+@item set write on
+@itemx set write off
+If you specify @samp{set write on}, @value{GDBN} opens executable 
+@ifclear BARETARGET
+and core
+@end ifclear
+files for both reading and writing; if you specify @samp{set write
+off} (the default), @value{GDBN} opens them read-only.
+
+If you have already loaded a file, you must load it again (using the
+@code{exec-file}
+@ifclear BARETARGET
+or @code{core-file}
+@end ifclear
+command) after changing @code{set write}, for your new setting to take
+effect.
+
+@item show write
+@kindex show write
+Display whether executable files 
+@ifclear BARETARGET
+and core files 
+@end ifclear
+are opened for writing as well as reading.
+@end table
+
+@node GDB Files, Targets, Altering, Top
+@chapter @value{GDBN} Files
+
+@value{GDBN} needs to know the file name of the program to be debugged, both in
+order to read its symbol table and in order to start your program.  
+@ifclear BARETARGET
+To debug a core dump of a previous run, you must also tell @value{GDBN}
+the name of the core dump file.
+@end ifclear
+
+@menu
+* Files::                       Commands to specify files
+* Symbol Errors::               Errors reading symbol files
+@end menu
+
+@node Files, Symbol Errors, GDB Files, GDB Files
+@section Commands to specify files
+@cindex symbol table
+
+@ifclear BARETARGET
+@cindex core dump file
+You may want to specify executable and core dump file names.
+The usual way to do this is at start-up time, using the arguments to 
+@value{GDBN}'s start-up commands (@pxref{Invocation, ,
+Getting In and Out of @value{GDBN}}).
+@end ifclear
+@ifset BARETARGET
+The usual way to specify an executable file name is with
+the command argument given when you start @value{GDBN}, (@pxref{Invocation,
+,Getting In and Out of @value{GDBN}}.
+@end ifset
+
+Occasionally it is necessary to change to a different file during a
+@value{GDBN} session.  Or you may run @value{GDBN} and forget to specify
+a file you want to use.  In these situations the @value{GDBN} commands
+to specify new files are useful.
+
+@table @code
+@cindex executable file
+@kindex file
+@item file @var{filename}
+Use @var{filename} as the program to be debugged.  It is read for its
+symbols and for the contents of pure memory.  It is also the program
+executed when you use the @code{run} command.  If you do not specify a
+directory and the file is not found in the @value{GDBN} working directory, 
+@value{GDBN} uses the environment variable @code{PATH} as a list of 
+directories to search, just as the shell does when looking for a program 
+to run.  You can change the value of this variable, for both @value{GDBN} 
+and your program, using the @code{path} command.
+
+@ifclear HPPA
+On systems with memory-mapped files, an auxiliary file
+@file{@var{filename}.syms} may hold symbol table information for
+@var{filename}.  If so, @value{GDBN} maps in the symbol table from
+@file{@var{filename}.syms}, starting up more quickly.  See the
+descriptions of the file options @samp{-mapped} and @samp{-readnow}
+(available on the command line, and with the commands @code{file},
+@code{symbol-file}, or @code{add-symbol-file}, described below), 
+for more information.
+@end ifclear
+
+@item file
+@code{file} with no argument makes @value{GDBN} discard any information it
+has on both executable file and the symbol table.
+
+@kindex exec-file
+@item exec-file @r{[} @var{filename} @r{]}
+Specify that the program to be run (but not the symbol table) is found
+in @var{filename}.  @value{GDBN} searches the environment variable @code{PATH}
+if necessary to locate your program.  Omitting @var{filename} means to
+discard information on the executable file.
+
+@kindex symbol-file
+@item symbol-file @r{[} @var{filename} @r{]}
+Read symbol table information from file @var{filename}.  @code{PATH} is
+searched when necessary.  Use the @code{file} command to get both symbol
+table and program to run from the same file.
+
+@code{symbol-file} with no argument clears out @value{GDBN} information on your
+program's symbol table.
+
+The @code{symbol-file} command causes @value{GDBN} to forget the contents 
+of its convenience variables, the value history, and all breakpoints and
+auto-display expressions.  This is because they may contain pointers to
+the internal data recording symbols and data types, which are part of
+the old symbol table data being discarded inside @value{GDBN}.
+
+@code{symbol-file} does not repeat if you press @key{RET} again after
+executing it once.
+
+When @value{GDBN} is configured for a particular environment, it
+understands debugging information in whatever format is the standard
+generated for that environment; you may use either a @sc{gnu} compiler, or
+other compilers that adhere to the local conventions.
+@ifclear HPPA
+Best results are usually obtained from @sc{gnu} compilers; for example,
+using @code{@value{GCC}} you can generate debugging information for
+optimized code.
+@end ifclear
+
+For most kinds of object files, with the exception of old SVR3 systems
+using COFF, the @code{symbol-file} command does not normally read the
+symbol table in full right away.  Instead, it scans the symbol table
+quickly to find which source files and which symbols are present.  The
+details are read later, one source file at a time, as they are needed.
+
+The purpose of this two-stage reading strategy is to make @value{GDBN}
+start up faster.  For the most part, it is invisible except for
+occasional pauses while the symbol table details for a particular source
+file are being read.  (The @code{set verbose} command can turn these
+pauses into messages if desired.  @xref{Messages/Warnings, ,Optional
+warnings and messages}.)
+
+@ifclear HPPA
+We have not implemented the two-stage strategy for COFF yet.  When the
+symbol table is stored in COFF format, @code{symbol-file} reads the
+symbol table data in full right away.  Note that ``stabs-in-COFF''
+still does the two-stage strategy, since the debug info is actually
+in stabs format.
+
+@kindex readnow
+@cindex reading symbols immediately
+@cindex symbols, reading immediately
+@kindex mapped
+@cindex memory-mapped symbol file
+@cindex saving symbol table
+@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+You can override the @value{GDBN} two-stage strategy for reading symbol
+tables by using the @samp{-readnow} option with any of the commands that
+load symbol table information, if you want to be sure @value{GDBN} has the
+entire symbol table available.  
+@end ifclear
+
+@ifclear BARETARGET
+@ifclear HPPA
+If memory-mapped files are available on your system through the
+@code{mmap} system call, you can use another option, @samp{-mapped}, to
+cause @value{GDBN} to write the symbols for your program into a reusable
+file.  Future @value{GDBN} debugging sessions map in symbol information
+from this auxiliary symbol file (if the program has not changed), rather
+than spending time reading the symbol table from the executable
+program.  Using the @samp{-mapped} option has the same effect as
+starting @value{GDBN} with the @samp{-mapped} command-line option.
+
+You can use both options together, to make sure the auxiliary symbol
+file has all the symbol information for your program.
+
+The auxiliary symbol file for a program called @var{myprog} is called
+@samp{@var{myprog}.syms}.  Once this file exists (so long as it is newer
+than the corresponding executable), @value{GDBN} always attempts to use
+it when you debug @var{myprog}; no special options or commands are
+needed.
+
+The @file{.syms} file is specific to the host machine where you run
+@value{GDBN}.  It holds an exact image of the internal @value{GDBN}
+symbol table.  It cannot be shared across multiple host platforms.
+@end ifclear
+
+@c FIXME: for now no mention of directories, since this seems to be in
+@c flux.  13mar1992 status is that in theory GDB would look either in
+@c current dir or in same dir as myprog; but issues like competing
+@c GDB's, or clutter in system dirs, mean that in practice right now
+@c only current dir is used.  FFish says maybe a special GDB hierarchy
+@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
+@c files.
+
+@kindex core
+@kindex core-file
+@item core-file @r{[} @var{filename} @r{]}
+Specify the whereabouts of a core dump file to be used as the ``contents
+of memory''.  Traditionally, core files contain only some parts of the
+address space of the process that generated them; @value{GDBN} can access the
+executable file itself for other parts.
+
+@code{core-file} with no argument specifies that no core file is
+to be used.
+
+Note that the core file is ignored when your program is actually running
+under @value{GDBN}.  So, if you have been running your program and you wish to
+debug a core file instead, you must kill the subprocess in which the
+program is running.  To do this, use the @code{kill} command
+(@pxref{Kill Process, ,Killing the child process}).
+@end ifclear
+
+@ifclear BARETARGET
+@ifclear HPPA
+@kindex add-symbol-file
+@cindex dynamic linking
+@item add-symbol-file @var{filename} @var{address}
+@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+The @code{add-symbol-file} command reads additional symbol table information
+from the file @var{filename}.  You would use this command when @var{filename}
+has been dynamically loaded (by some other means) into the program that
+is running.  @var{address} should be the memory address at which the
+file has been loaded; @value{GDBN} cannot figure this out for itself.
+You can specify @var{address} as an expression.
+
+The symbol table of the file @var{filename} is added to the symbol table
+originally read with the @code{symbol-file} command.  You can use the
+@code{add-symbol-file} command any number of times; the new symbol data thus
+read keeps adding to the old.  To discard all old symbol data instead,
+use the @code{symbol-file} command.
+
+@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+
+You can use the @samp{-mapped} and @samp{-readnow} options just as with
+the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
+table information for @var{filename}.
+
+@kindex add-shared-symbol-file
+@item add-shared-symbol-file
+The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
+operating system for the Motorola 88k.  @value{GDBN} automatically looks for 
+shared libraries, however if @value{GDBN} does not find yours, you can run 
+@code{add-shared-symbol-file}.  It takes no arguments.
+@end ifclear
+@end ifclear
+
+@ifclear HPPA
+@kindex section
+@item section
+The @code{section} command changes the base address of section SECTION of 
+the exec file to ADDR.  This can be used if the exec file does not contain 
+section addresses, (such as in the a.out format), or when the addresses 
+specified in the file itself are wrong.  Each section must be changed 
+separately.  The ``info files'' command lists all the sections and their 
+addresses.
+@end ifclear
+
+@kindex info files
+@kindex info target
+@item info files
+@itemx info target
+@code{info files} and @code{info target} are synonymous; both print
+the current target (@pxref{Targets, ,Specifying a Debugging Target}),
+including the
+@ifclear BARETARGET
+names of the executable and core dump files
+@end ifclear
+@ifset BARETARGET
+name of the executable file
+@end ifset
+currently in use by @value{GDBN}, and the files from which symbols were
+loaded.  The command @code{help target} lists all possible targets
+rather than current ones.
+@end table
+
+All file-specifying commands allow both absolute and relative file names
+as arguments.  @value{GDBN} always converts the file name to an absolute file
+name and remembers it that way.
+
+@ifclear BARETARGET
+@cindex shared libraries
+@ifclear HPPA
+@c added HP-UX -- Kim (HP writer)
+@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
+libraries.
+@end ifclear
+@ifset HPPA
+@value{GDBN} supports HP-UX shared libraries.
+@end ifset
+@value{GDBN} automatically loads symbol definitions from shared libraries
+when you use the @code{run} command, or when you examine a core file.
+(Before you issue the @code{run} command, @value{GDBN} does not understand
+references to a function in a shared library, however---unless you are
+debugging a core file).
+@ifset HPPA
+If the program loads a library explicitly, @value{GDBN} automatically
+loads the symbols at the time of the @code{shl_load} call.
+@end ifset
+@c FIXME: some @value{GDBN} release may permit some refs to undef
+@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
+@c FIXME...lib; check this from time to time when updating manual
+
+@table @code
+@kindex info sharedlibrary
+@kindex info share
+@item info share
+@itemx info sharedlibrary
+Print the names of the shared libraries which are currently loaded.
+
+@kindex sharedlibrary
+@kindex share
+@item sharedlibrary @var{regex}
+@itemx share @var{regex}
+
+Load shared object library symbols for files matching a
+Unix regular expression.
+As with files loaded automatically, it only loads shared libraries
+required by your program for a core file or after typing @code{run}.  If
+@var{regex} is omitted all shared libraries required by your program are
+loaded.
+@end table
+
+@ifset HPPA
+@value{GDBN} detects the loading of a shared library and automatically
+reads in symbols from the newly loaded library, up to a threshold that
+is initially set but that you can modify if you wish.
+
+Beyond that threshold, symbols from shared libraries must be explicitly
+loaded.  To load these symbols, use the command @code{sharedlibrary}
+@var{filename}.  The base address of the shared library is determined
+automatically by @value{GDBN} and need not be specified.
+
+To display or set the threshold, use the commands:
+
+@table @code
+@kindex set auto-solib-add
+@item set auto-solib-add @var{threshold}
+Set the autoloading size threshold, in megabytes.  If @var{threshold} is
+nonzero, symbols from all shared object libraries will be loaded
+automatically when the inferior begins execution or when the dynamic
+linker informs @value{GDBN} that a new library has been loaded, until
+the symbol table of the program and libraries exceeds this threshold.
+Otherwise, symbols must be loaded manually, using the
+@code{sharedlibrary} command.  The default threshold is 100 megabytes.
+
+@kindex show auto-solib-add
+@item show auto-solib-add
+Display the current autoloading size threshold, in megabytes.
+@end table
+@end ifset
+
+@end ifclear
+
+@node Symbol Errors,  , Files, GDB Files
+@section Errors reading symbol files
+
+While reading a symbol file, @value{GDBN} occasionally encounters problems,
+such as symbol types it does not recognize, or known bugs in compiler
+output.  By default, @value{GDBN} does not notify you of such problems, since
+they are relatively common and primarily of interest to people
+debugging compilers.  If you are interested in seeing information
+about ill-constructed symbol tables, you can either ask @value{GDBN} to print
+only one message about each such type of problem, no matter how many
+times the problem occurs; or you can ask @value{GDBN} to print more messages,
+to see how many times the problems occur, with the @code{set
+complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
+messages}).
+
+The messages currently printed, and their meanings, include:
+
+@table @code
+@item inner block not inside outer block in @var{symbol}
+
+The symbol information shows where symbol scopes begin and end
+(such as at the start of a function or a block of statements).  This
+error indicates that an inner scope block is not fully contained
+in its outer scope blocks.
+
+@value{GDBN} circumvents the problem by treating the inner block as if it had
+the same scope as the outer block.  In the error message, @var{symbol}
+may be shown as ``@code{(don't know)}'' if the outer block is not a
+function.
+
+@item block at @var{address} out of order
+
+The symbol information for symbol scope blocks should occur in
+order of increasing addresses.  This error indicates that it does not
+do so.
+
+@value{GDBN} does not circumvent this problem, and has trouble
+locating symbols in the source file whose symbols it is reading.  (You
+can often determine what source file is affected by specifying
+@code{set verbose on}.  @xref{Messages/Warnings, ,Optional warnings and
+messages}.)
+
+@item bad block start address patched
+
+The symbol information for a symbol scope block has a start address
+smaller than the address of the preceding source line.  This is known
+to occur in the SunOS 4.1.1 (and earlier) C compiler.
+
+@value{GDBN} circumvents the problem by treating the symbol scope block as
+starting on the previous source line.
+
+@item bad string table offset in symbol @var{n}
+
+@cindex foo
+Symbol number @var{n} contains a pointer into the string table which is
+larger than the size of the string table.
+
+@value{GDBN} circumvents the problem by considering the symbol to have the
+name @code{foo}, which may cause other problems if many symbols end up
+with this name.
+
+@item unknown symbol type @code{0x@var{nn}}
+
+The symbol information contains new data types that @value{GDBN} does not yet
+know how to read.  @code{0x@var{nn}} is the symbol type of the misunderstood
+information, in hexadecimal.
+
+@value{GDBN} circumvents the error by ignoring this symbol information.  This
+usually allows you to debug your program, though certain symbols
+are not accessible.  If you encounter such a problem and feel like
+debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint on
+@code{complain}, then go up to the function @code{read_dbx_symtab} and
+examine @code{*bufp} to see the symbol.
+
+@item stub type has NULL name
+@value{GDBN} could not find the full definition for
+@ifclear CONLY
+a struct or class.
+@end ifclear
+@ifset CONLY
+a struct.
+@end ifset
+
+@ifclear CONLY
+@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
+
+The symbol information for a C++ member function is missing some
+information that recent versions of the compiler should have output
+for it.
+@end ifclear
+
+@item info mismatch between compiler and debugger
+
+@value{GDBN} could not parse a type specification output by the compiler.
+@end table
+
+@node Targets, Controlling GDB, GDB Files, Top
+@chapter Specifying a Debugging Target
+@cindex debugging target
+@kindex target
+
+A @dfn{target} is the execution environment occupied by your program.
+@ifclear HPPA
+@ifclear BARETARGET
+Often, @value{GDBN} runs in the same host environment as your program; in
+that case, the debugging target is specified as a side effect when you
+use the @code{file} or @code{core} commands.  When you need more
+flexibility---for example, running @value{GDBN} on a physically separate
+host, or controlling a standalone system over a serial port or a
+realtime system over a TCP/IP connection---you 
+@end ifclear
+@end ifclear
+@ifset HPPA
+On HP-UX systems, @value{GDBN} has been configured to support debugging
+of processes running on the PA-RISC architecture.  This means that the
+only possible targets are:
+
+@itemize @bullet
+@item
+An executable that has been compiled and linked to run on HP-UX
+
+@item
+A live HP-UX process, either started by @value{GDBN} (with the
+@code{run} command) or started outside of @value{GDBN} and attached to
+(with the @code{attach} command)
+
+@item
+A core file generated by an HP-UX process that previously aborted
+execution
+@end itemize
+
+@value{GDBN} on HP-UX has not been configured to support remote
+debugging, or to support programs running on other platforms. You
+@end ifset
+@ifset BARETARGET
+You
+@end ifset
+can use the @code{target} command to specify one of the target types
+configured for @value{GDBN} (@pxref{Target Commands, ,Commands for managing
+targets}).
+
+@menu
+* Active Targets::              Active targets
+* Target Commands::             Commands for managing targets
+@ifset REMOTESTUB
+* Byte Order::                  Choosing target byte order
+* Remote::                      Remote debugging
+@end ifset
+
+@end menu
+
+@node Active Targets, Target Commands, Targets, Targets
+@section Active targets
+@cindex stacking targets
+@cindex active targets
+@cindex multiple targets
+
+@ifclear BARETARGET
+There are three classes of targets: processes, core files, and
+executable files.  @value{GDBN} can work concurrently on up to three active
+targets, one in each class.  This allows you to (for example) start a
+process and inspect its activity without abandoning your work on a core
+file.
+
+For example, if you execute @samp{gdb a.out}, then the executable file
+@code{a.out} is the only active target.  If you designate a core file as
+well---presumably from a prior run that crashed and coredumped---then
+@value{GDBN} has two active targets and uses them in tandem, looking
+first in the corefile target, then in the executable file, to satisfy
+requests for memory addresses.  (Typically, these two classes of target
+are complementary, since core files contain only a program's
+read-write memory---variables and so on---plus machine status, while
+executable files contain only the program text and initialized data.)
+@end ifclear
+
+When you type @code{run}, your executable file becomes an active process
+target as well.  When a process target is active, all @value{GDBN} commands
+requesting memory addresses refer to that target; addresses in an 
+@ifclear BARETARGET
+active core file or 
+@end ifclear
+executable file target are obscured while the process
+target is active.
+
+@ifset BARETARGET
+Use the @code{exec-file} command to select a
+new executable target (@pxref{Files, ,Commands to specify
+files}).
+@end ifset
+@ifclear BARETARGET
+Use the @code{core-file} and @code{exec-file} commands to select a
+new core file or executable target (@pxref{Files, ,Commands to specify
+files}).  To specify as a target a process that is already running, use
+the @code{attach} command (@pxref{Attach, ,Debugging an
+already-running process}).
+@end ifclear
+
+@node Target Commands, Byte Order, Active Targets, Targets
+@section Commands for managing targets
+
+@table @code
+@item target @var{type} @var{parameters}
+Connects the @value{GDBN} host environment to a target
+@ifset BARETARGET
+machine.
+@end ifset
+@ifclear BARETARGET
+machine or process.  A target is typically a protocol for talking to
+debugging facilities.  You use the argument @var{type} to specify the
+type or protocol of the target machine.
+
+Further @var{parameters} are interpreted by the target protocol, but
+typically include things like device names or host names to connect
+with, process numbers, and baud rates.
+@end ifclear
+
+The @code{target} command does not repeat if you press @key{RET} again
+after executing the command.
+
+@kindex help target
+@item help target
+Displays the names of all targets available.  To display targets
+currently selected, use either @code{info target} or @code{info files}
+(@pxref{Files, ,Commands to specify files}).
+
+@item help target @var{name}
+Describe a particular target, including any parameters necessary to
+select it.
+
+@kindex set gnutarget
+@item set gnutarget @var{args}
+@value{GDBN} uses its own library BFD to read your files.  @value{GDBN} 
+knows whether it is reading an @dfn{executable},
+a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format 
+with the @code{set gnutarget} command.  Unlike most @code{target} commands, 
+with @code{gnutarget} the @code{target} refers to a program, not a machine.
+
+@emph{Warning:} To specify a file format with @code{set gnutarget},
+you must know the actual BFD name.
+
+@noindent @xref{Files, , Commands to specify files}.
+
+@kindex show gnutarget  
+@item show gnutarget
+Use the @code{show gnutarget} command to display what file format
+@code{gnutarget} is set to read.  If you have not set @code{gnutarget},
+@value{GDBN} will determine the file format for each file automatically,
+and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
+@end table
+
+@ifclear HPPA
+Here are some common targets (available, or not, depending on the GDB
+configuration):
+@end ifclear
+@ifset HPPA
+These are the valid targets on HP-UX systems:
+@end ifset
+
+@table @code
+@kindex target exec
+@item target exec @var{program}
+An executable file.  @samp{target exec @var{program}} is the same as
+@samp{exec-file @var{program}}.
+
+@ifclear BARETARGET
+@kindex target core
+@item target core @var{filename}
+A core dump file.  @samp{target core @var{filename}} is the same as
+@samp{core-file @var{filename}}.
+@end ifclear
+
+@kindex target remote
+@item target remote @var{dev}
+Remote serial target in GDB-specific protocol.  The argument @var{dev}
+specifies what serial device to use for the connection (e.g.
+@file{/dev/ttya}). @xref{Remote, ,Remote debugging}.  @code{target remote}
+now supports the @code{load} command.  This is only useful if you have
+some other way of getting the stub to the target system, and you can put
+it somewhere in memory where it won't get clobbered by the download.
+
+@ifclear HPPA
+@kindex target sim
+@item target sim
+CPU simulator.  @xref{Simulator,,Simulated CPU Target}.
+@end ifclear
+@end table
+
+The following targets are all CPU-specific, and only available for
+specific configurations.
+@c should organize by CPU
+
+@table @code
+
+@kindex target abug
+@item target abug @var{dev}
+ABug ROM monitor for M68K.
+
+@kindex target adapt
+@item target adapt @var{dev}
+Adapt monitor for A29K.
+
+@kindex target amd-eb
+@item target amd-eb @var{dev} @var{speed} @var{PROG}
+@cindex AMD EB29K
+Remote PC-resident AMD EB29K board, attached over serial lines.
+@var{dev} is the serial device, as for @code{target remote};
+@var{speed} allows you to specify the linespeed; and @var{PROG} is the
+name of the program to be debugged, as it appears to DOS on the PC.
+@xref{EB29K Remote, ,The EBMON protocol for AMD29K}.
+
+@kindex target array
+@item target array @var{dev}
+Array Tech LSI33K RAID controller board.
+
+@kindex target bug
+@item target bug @var{dev}
+BUG monitor, running on a MVME187 (m88k) board.
+
+@kindex target cpu32bug
+@item target cpu32bug @var{dev}
+CPU32BUG monitor, running on a CPU32 (M68K) board.
+
+@kindex target dbug
+@item target dbug @var{dev}
+dBUG ROM monitor for Motorola ColdFire.
+
+@kindex target ddb
+@item target ddb @var{dev}
+NEC's DDB monitor for Mips Vr4300.
+
+@kindex target dink32
+@item target dink32 @var{dev}
+DINK32 ROM monitor for PowerPC.
+
+@kindex target e7000
+@item target e7000 @var{dev}
+E7000 emulator for Hitachi H8 and SH.
+
+@kindex target es1800
+@item target es1800 @var{dev}
+ES-1800 emulator for M68K.
+
+@kindex target est
+@item target est @var{dev}
+EST-300 ICE monitor, running on a CPU32 (M68K) board.
+
+@kindex target hms
+@item target hms @var{dev}
+A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host.
+@ifclear H8EXCLUSIVE
+Use special commands @code{device} and @code{speed} to control the serial
+line and the communications speed used.
+@xref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}.
+
+@kindex target lsi
+@item target lsi @var{dev}
+LSI ROM monitor for Mips.
+
+@kindex target m32r
+@item target m32r @var{dev}
+Mitsubishi M32R/D ROM monitor.
+
+@kindex target mips
+@item target mips @var{dev}
+IDT/SIM ROM monitor for Mips.
+
+@kindex target mon960
+@item target mon960 @var{dev}
+MON960 monitor for Intel i960.
+
+@kindex target nindy
+@item target nindy @var{devicename}
+An Intel 960 board controlled by a Nindy Monitor.  @var{devicename} is
+the name of the serial device to use for the connection, e.g.
+@file{/dev/ttya}.  @xref{i960-Nindy Remote, ,@value{GDBN} with a remote i960 (Nindy)}.
+
+@kindex target nrom
+@item target nrom @var{dev}
+NetROM ROM emulator.  This target only supports downloading.
+
+@kindex target op50n
+@item target op50n @var{dev}
+OP50N monitor, running on an OKI HPPA board.
+
+@kindex target pmon
+@item target pmon @var{dev}
+PMON ROM monitor for Mips.
+
+@kindex target ppcbug
+@item target ppcbug @var{dev}
+@kindex target ppcbug1
+@item target ppcbug1 @var{dev}
+PPCBUG ROM monitor for PowerPC.
+
+@kindex target r3900
+@item target r3900 @var{dev}
+Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
+
+@kindex target rdi
+@item target rdi @var{dev}
+ARM Angel monitor, via RDI library interface.
+ 
+@kindex target rdp
+@item target rdp @var{dev}
+ARM Demon monitor.
+
+@kindex target rom68k
+@item target rom68k @var{dev}
+ROM 68K monitor, running on an M68K IDP board.
+
+@kindex target rombug
+@item target rombug @var{dev}
+ROMBUG ROM monitor for OS/9000.
+
+@kindex target sds
+@item target sds @var{dev}
+SDS monitor, running on a PowerPC board (such as Motorola's ADS).
+
+@kindex target sparclite
+@item target sparclite @var{dev}
+Fujitsu sparclite boards, used only for the purpose of loading.  
+You must use an additional command to debug the program. 
+For example: target remote @var{dev} using @value{GDBN} standard 
+remote protocol.
+
+@kindex target sh3
+@kindex target sh3e
+@item target sh3 @var{dev}
+@item target sh3e @var{dev}
+Hitachi SH-3 and SH-3E target systems.
+
+@kindex target st2000
+@item target st2000 @var{dev} @var{speed}
+A Tandem ST2000 phone switch, running Tandem's STDBUG protocol.  @var{dev}
+is the name of the device attached to the ST2000 serial line;
+@var{speed} is the communication line speed.  The arguments are not used
+if @value{GDBN} is configured to connect to the ST2000 using TCP or Telnet.
+@xref{ST2000 Remote,,@value{GDBN} with a Tandem ST2000}.
+
+@kindex target udi
+@item target udi @var{keyword}
+Remote AMD29K target, using the AMD UDI protocol.  The @var{keyword}
+argument specifies which 29K board or simulator to use.  @xref{UDI29K
+Remote,,The UDI protocol for AMD29K}.
+
+@kindex target vxworks
+@item target vxworks @var{machinename}
+A VxWorks system, attached via TCP/IP.  The argument @var{machinename}
+is the target system's machine name or IP address.
+@xref{VxWorks Remote, ,@value{GDBN} and VxWorks}.
+
+@kindex target w89k
+@item target w89k @var{dev}
+W89K monitor, running on a Winbond HPPA board.
+
+@end ifclear
+@end table
+
+@ifset GENERIC
+Different targets are available on different configurations of @value{GDBN}; 
+your configuration may have more or fewer targets.
+@end ifset
+
+Many remote targets require you to download the executable's code
+once you've successfully established a connection.
+
+@table @code
+
+@kindex load @var{filename}
+@item load @var{filename}
+@ifset GENERIC
+Depending on what remote debugging facilities are configured into
+@value{GDBN}, the @code{load} command may be available.  Where it exists, it
+is meant to make @var{filename} (an executable) available for debugging
+on the remote system---by downloading, or dynamic linking, for example.
+@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
+the @code{add-symbol-file} command.
+
+If your @value{GDBN} does not have a @code{load} command, attempting to
+execute it gets the error message ``@code{You can't do that when your
+target is @dots{}}''
+@end ifset
+
+The file is loaded at whatever address is specified in the executable.
+For some object file formats, you can specify the load address when you
+link the program; for other formats, like a.out, the object file format
+specifies a fixed address.
+@c FIXME! This would be a good place for an xref to the GNU linker doc.
+
+@ifset VXWORKS
+On VxWorks, @code{load} links @var{filename} dynamically on the
+current target system as well as adding its symbols in @value{GDBN}.
+@end ifset
+
+@ifset I960
+@cindex download to Nindy-960
+With the Nindy interface to an Intel 960 board, @code{load}
+downloads @var{filename} to the 960 as well as adding its symbols in
+@value{GDBN}.
+@end ifset
+
+@ifset H8
+@cindex download to H8/300 or H8/500
+@cindex H8/300 or H8/500 download
+@cindex download to Hitachi SH
+@cindex Hitachi SH download
+When you select remote debugging to a Hitachi SH, H8/300, or H8/500 board
+(@pxref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}),
+the @code{load} command downloads your program to the Hitachi board and also
+opens it as the current executable target for @value{GDBN} on your host
+(like the @code{file} command).
+@end ifset
+
+@code{load} does not repeat if you press @key{RET} again after using it.
+@end table
+
+@ifset REMOTESTUB
+@node Byte Order, Remote, Target Commands, Targets
+@section Choosing target byte order
+@cindex choosing target byte order
+@cindex target byte order
+@kindex set endian big
+@kindex set endian little
+@kindex set endian auto
+@kindex show endian
+
+Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
+offer the ability to run either big-endian or little-endian byte
+orders.  Usually the executable or symbol will include a bit to
+designate the endian-ness, and you will not need to worry about
+which to use.  However, you may still find it useful to adjust
+GDB's idea of processor endian-ness manually.
+
+@table @code
+@kindex set endian big
+@item set endian big
+Instruct @value{GDBN} to assume the target is big-endian.
+
+@kindex set endian little
+@item set endian little
+Instruct @value{GDBN} to assume the target is little-endian.
+
+@kindex set endian auto
+@item set endian auto
+Instruct @value{GDBN} to use the byte order associated with the
+executable.
+
+@item show endian
+Display @value{GDBN}'s current idea of the target byte order.
+
+@end table
+
+Note that these commands merely adjust interpretation of symbolic
+data on the host, and that they have absolutely no effect on the
+target system.
+
+@node Remote,  , Byte Order, Targets
+@section Remote debugging
+@cindex remote debugging
+
+If you are trying to debug a program running on a machine that cannot run
+@value{GDBN} in the usual way, it is often useful to use remote debugging.  
+For example, you might use remote debugging on an operating system kernel, 
+or on a small system which does not have a general purpose operating system
+powerful enough to run a full-featured debugger.
+
+Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
+to make this work with particular debugging targets.  In addition,
+@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, 
+but not specific to any particular target system) which you can use if you
+write the remote stubs---the code that runs on the remote system to
+communicate with @value{GDBN}.
+
+Other remote targets may be available in your
+configuration of @value{GDBN}; use @code{help target} to list them.
+@end ifset
+
+@ifset GENERIC
+@c Text on starting up GDB in various specific cases; it goes up front
+@c in manuals configured for any of those particular situations, here
+@c otherwise.
+@menu
+@ifset REMOTESTUB
+* Remote Serial::               @value{GDBN} remote serial protocol
+@end ifset
+@ifset I960
+* i960-Nindy Remote::		@value{GDBN} with a remote i960 (Nindy)
+@end ifset
+@ifset AMD29K
+* UDI29K Remote::               The UDI protocol for AMD29K
+* EB29K Remote::		The EBMON protocol for AMD29K
+@end ifset
+@ifset VXWORKS
+* VxWorks Remote::		@value{GDBN} and VxWorks
+@end ifset
+@ifset ST2000
+* ST2000 Remote::               @value{GDBN} with a Tandem ST2000
+@end ifset
+@ifset H8
+* Hitachi Remote::              @value{GDBN} and Hitachi Microprocessors
+@end ifset
+@ifset MIPS
+* MIPS Remote::			@value{GDBN} and MIPS boards
+@end ifset
+@ifset SPARCLET
+* Sparclet Remote::             @value{GDBN} and Sparclet boards
+@end ifset
+@ifset SIMS
+* Simulator::                   Simulated CPU target
+@end ifset
+@end menu
+
+@include remote.texi
+@end ifset
+
+@node Controlling GDB
+@chapter Controlling @value{GDBN}
+
+You can alter the way @value{GDBN} interacts with you by using
+the @code{set} command.  For commands controlling how @value{GDBN} displays
+data, @pxref{Print Settings, ,Print settings}; other settings are described 
+here.
+
+@menu
+* Prompt::                      Prompt
+* Editing::                     Command editing
+* History::                     Command history
+* Screen Size::                 Screen size
+* Numbers::                     Numbers
+* Messages/Warnings::           Optional warnings and messages
+@end menu
+
+@node Prompt, Editing, Controlling GDB, Controlling GDB
+@section Prompt
+
+@cindex prompt
+
+@value{GDBN} indicates its readiness to read a command by printing a string
+called the @dfn{prompt}.  This string is normally @samp{(@value{GDBP})}.  You
+can change the prompt string with the @code{set prompt} command.  For
+instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
+the prompt in one of the @value{GDBN} sessions so that you can always tell 
+which one you are talking to.
+
+@emph{Note:}  @code{set prompt} no longer adds a space for you after the
+prompt you set.  This allows you to set a prompt which ends in a space
+or a prompt that does not.
+
+@table @code
+@kindex set prompt
+@item set prompt @var{newprompt}
+Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
+
+@kindex show prompt
+@item show prompt
+Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
+@end table
+
+@node Editing, History, Prompt, Controlling GDB
+@section Command editing
+@cindex readline
+@cindex command line editing
+
+@value{GDBN} reads its input commands via the @dfn{readline} interface.  This
+@sc{gnu} library provides consistent behavior for programs which provide a
+command line interface to the user.  Advantages are @sc{gnu} Emacs-style
+or @dfn{vi}-style inline editing of commands, @code{csh}-like history
+substitution, and a storage and recall of command history across
+debugging sessions.
+
+You may control the behavior of command line editing in @value{GDBN} with the
+command @code{set}.
+
+@table @code
+@kindex set editing
+@cindex editing
+@item set editing
+@itemx set editing on
+Enable command line editing (enabled by default).
+
+@item set editing off
+Disable command line editing.
+
+@kindex show editing
+@item show editing
+Show whether command line editing is enabled.
+@end table
+
+@node History, Screen Size, Editing, Controlling GDB
+@section Command history
+
+@value{GDBN} can keep track of the commands you type during your
+debugging sessions, so that you can be certain of precisely what
+happened.  Use these commands to manage the @value{GDBN} command
+history facility.
+
+@table @code
+@cindex history substitution
+@cindex history file
+@kindex set history filename
+@kindex GDBHISTFILE
+@item set history filename @var{fname}
+Set the name of the @value{GDBN} command history file to @var{fname}.
+This is the file where @value{GDBN} reads an initial command history
+list, and where it writes the command history from this session when it
+exits.  You can access this list through history expansion or through
+the history command editing characters listed below.  This file defaults
+to the value of the environment variable @code{GDBHISTFILE}, or to
+@file{./.gdb_history} if this variable is not set.
+
+@cindex history save
+@kindex set history save
+@item set history save
+@itemx set history save on
+Record command history in a file, whose name may be specified with the
+@code{set history filename} command.  By default, this option is disabled.
+
+@item set history save off
+Stop recording command history in a file.
+
+@cindex history size
+@kindex set history size
+@item set history size @var{size}
+Set the number of commands which @value{GDBN} keeps in its history list.
+This defaults to the value of the environment variable
+@code{HISTSIZE}, or to 256 if this variable is not set.
+@end table
+
+@cindex history expansion
+History expansion assigns special meaning to the character @kbd{!}.
+@ifset have-readline-appendices
+@xref{Event Designators}.
+@end ifset
+
+Since @kbd{!} is also the logical not operator in C, history expansion
+is off by default. If you decide to enable history expansion with the
+@code{set history expansion on} command, you may sometimes need to
+follow @kbd{!} (when it is used as logical not, in an expression) with
+a space or a tab to prevent it from being expanded.  The readline
+history facilities do not attempt substitution on the strings
+@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
+
+The commands to control history expansion are:
+
+@table @code
+@kindex set history expansion
+@item set history expansion on
+@itemx set history expansion
+Enable history expansion.  History expansion is off by default.
+
+@item set history expansion off
+Disable history expansion.
+
+The readline code comes with more complete documentation of
+editing and history expansion features.  Users unfamiliar with @sc{gnu} Emacs
+or @code{vi} may wish to read it.
+@ifset have-readline-appendices
+@xref{Command Line Editing}.
+@end ifset
+
+@c @group
+@kindex show history
+@item show history
+@itemx show history filename
+@itemx show history save
+@itemx show history size
+@itemx show history expansion
+These commands display the state of the @value{GDBN} history parameters.
+@code{show history} by itself displays all four states.
+@c @end group
+@end table
+
+@table @code
+@kindex show commands
+@item show commands
+Display the last ten commands in the command history.
+
+@item show commands @var{n}
+Print ten commands centered on command number @var{n}.
+
+@item show commands +
+Print ten commands just after the commands last printed.
+@end table
+
+@node Screen Size, Numbers, History, Controlling GDB
+@section Screen size
+@cindex size of screen
+@cindex pauses in output
+
+Certain commands to @value{GDBN} may produce large amounts of
+information output to the screen.  To help you read all of it,
+@value{GDBN} pauses and asks you for input at the end of each page of
+output.  Type @key{RET} when you want to continue the output, or @kbd{q}
+to discard the remaining output.  Also, the screen width setting
+determines when to wrap lines of output.  Depending on what is being
+printed, @value{GDBN} tries to break the line at a readable place,
+rather than simply letting it overflow onto the following line.
+
+Normally @value{GDBN} knows the size of the screen from the termcap data base
+together with the value of the @code{TERM} environment variable and the
+@code{stty rows} and @code{stty cols} settings. If this is not correct,
+you can override it with the @code{set height} and @code{set
+width} commands:
+
+@table @code
+@kindex set height
+@kindex set width
+@kindex show width
+@kindex show height
+@item set height @var{lpp}
+@itemx show height
+@itemx set width @var{cpl}
+@itemx show width
+These @code{set} commands specify a screen height of @var{lpp} lines and
+a screen width of @var{cpl} characters.  The associated @code{show}
+commands display the current settings.
+
+If you specify a height of zero lines, @value{GDBN} does not pause during 
+output no matter how long the output is.  This is useful if output is to a 
+file or to an editor buffer.
+
+Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
+from wrapping its output.
+@end table
+
+@node Numbers, Messages/Warnings, Screen Size, Controlling GDB
+@section Numbers
+@cindex number representation
+@cindex entering numbers
+
+You can always enter numbers in octal, decimal, or hexadecimal in @value{GDBN} by
+the usual conventions: octal numbers begin with @samp{0}, decimal
+numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}.
+Numbers that begin with none of these are, by default, entered in base
+10; likewise, the default display for numbers---when no particular
+format is specified---is base 10.  You can change the default base for
+both input and output with the @code{set radix} command.
+
+@table @code
+@kindex set input-radix
+@item set input-radix @var{base}
+Set the default base for numeric input.  Supported choices
+for @var{base} are decimal 8, 10, or 16.  @var{base} must itself be
+specified either unambiguously or using the current default radix; for
+example, any of
+
+@smallexample
+set radix 012
+set radix 10.
+set radix 0xa
+@end smallexample
+
+@noindent
+sets the base to decimal.  On the other hand, @samp{set radix 10}
+leaves the radix unchanged no matter what it was.
+
+@kindex set output-radix
+@item set output-radix @var{base}
+Set the default base for numeric display.  Supported choices
+for @var{base} are decimal 8, 10, or 16.  @var{base} must itself be
+specified either unambiguously or using the current default radix.
+
+@kindex show input-radix
+@item show input-radix
+Display the current default base for numeric input.
+
+@kindex show output-radix
+@item show output-radix
+Display the current default base for numeric display.
+@end table
+
+@node Messages/Warnings,  , Numbers, Controlling GDB
+@section Optional warnings and messages
+
+By default, @value{GDBN} is silent about its inner workings.  If you are running
+on a slow machine, you may want to use the @code{set verbose} command.
+This makes @value{GDBN} tell you when it does a lengthy internal operation, so
+you will not think it has crashed.
+
+Currently, the messages controlled by @code{set verbose} are those
+which announce that the symbol table for a source file is being read;
+see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
+
+@table @code
+@kindex set verbose
+@item set verbose on
+Enables @value{GDBN} output of certain informational messages.
+
+@item set verbose off
+Disables @value{GDBN} output of certain informational messages.
+
+@kindex show verbose
+@item show verbose
+Displays whether @code{set verbose} is on or off.
+@end table
+
+By default, if @value{GDBN} encounters bugs in the symbol table of an object
+file, it is silent; but if you are debugging a compiler, you may find
+this information useful (@pxref{Symbol Errors, ,Errors reading symbol files}).
+
+@table @code
+@kindex set complaints
+@item set complaints @var{limit}
+Permits @value{GDBN} to output @var{limit} complaints about each type of unusual
+symbols before becoming silent about the problem.  Set @var{limit} to
+zero to suppress all complaints; set it to a large number to prevent
+complaints from being suppressed.
+
+@kindex show complaints
+@item show complaints
+Displays how many symbol complaints @value{GDBN} is permitted to produce.
+@end table
+
+By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
+lot of stupid questions to confirm certain commands.  For example, if
+you try to run a program which is already running:
+
+@example
+(@value{GDBP}) run
+The program being debugged has been started already.
+Start it from the beginning? (y or n)
+@end example
+
+If you are willing to unflinchingly face the consequences of your own
+commands, you can disable this ``feature'':
+
+@table @code
+@kindex set confirm
+@cindex flinching
+@cindex confirmation
+@cindex stupid questions
+@item set confirm off
+Disables confirmation requests.
+
+@item set confirm on
+Enables confirmation requests (the default).
+
+@kindex show confirm
+@item show confirm
+Displays state of confirmation requests.
+@end table
+
+@node Sequences, Emacs, Controlling GDB, Top
+@chapter Canned Sequences of Commands
+
+Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
+command lists}), @value{GDBN} provides two ways to store sequences of commands
+for execution as a unit: user-defined commands and command files.
+
+@menu
+* Define::                      User-defined commands
+* Hooks::                       User-defined command hooks
+* Command Files::               Command files
+* Output::                      Commands for controlled output
+@end menu
+
+@node Define, Hooks, Sequences, Sequences
+@section User-defined commands
+
+@cindex user-defined command
+A @dfn{user-defined command} is a sequence of @value{GDBN} commands to which 
+you assign a new name as a command.  This is done with the @code{define}
+command.  User commands may accept up to 10 arguments separated by whitespace.
+Arguments are accessed within the user command via @var{$arg0@dots{}$arg9}.
+A trivial example:
+
+@smallexample
+define adder
+  print $arg0 + $arg1 + $arg2
+@end smallexample
+
+@noindent To execute the command use:
+
+@smallexample
+adder 1 2 3
+@end smallexample
+
+@noindent This defines the command @code{adder}, which prints the sum of
+its three arguments.  Note the arguments are text substitutions, so they may 
+reference variables, use complex expressions, or even perform inferior
+functions calls.
+
+@table @code
+@kindex define
+@item define @var{commandname}
+Define a command named @var{commandname}.  If there is already a command
+by that name, you are asked to confirm that you want to redefine it.
+
+The definition of the command is made up of other @value{GDBN} command lines,
+which are given following the @code{define} command.  The end of these
+commands is marked by a line containing @code{end}.
+
+@kindex if
+@kindex else
+@item if
+Takes a single argument, which is an expression to evaluate.
+It is followed by a series of commands that are executed
+only if the expression is true (nonzero).
+There can then optionally be a line @code{else}, followed
+by a series of commands that are only executed if the expression
+was false.  The end of the list is marked by a line containing @code{end}.
+
+@kindex while
+@item while
+The syntax is similar to @code{if}: the command takes a single argument,
+which is an expression to evaluate, and must be followed by the commands to
+execute, one per line, terminated by an @code{end}.
+The commands are executed repeatedly as long as the expression
+evaluates to true.
+
+@kindex document
+@item document @var{commandname}
+Document the user-defined command @var{commandname}, so that it can be
+accessed by @code{help}.  The command @var{commandname} must already be 
+defined.  This command reads lines of documentation just as @code{define} 
+reads the lines of the command definition, ending with @code{end}.  
+After the @code{document} command is finished, @code{help} on command 
+@var{commandname} displays the documentation you have written.
+
+You may use the @code{document} command again to change the
+documentation of a command.  Redefining the command with @code{define}
+does not change the documentation.
+
+@kindex help user-defined
+@item help user-defined
+List all user-defined commands, with the first line of the documentation
+(if any) for each.
+
+@kindex show user
+@item show user
+@itemx show user @var{commandname}
+Display the @value{GDBN} commands used to define @var{commandname} (but not its
+documentation).  If no @var{commandname} is given, display the
+definitions for all user-defined commands.
+@end table
+
+When user-defined commands are executed, the
+commands of the definition are not printed.  An error in any command
+stops execution of the user-defined command.
+
+If used interactively, commands that would ask for confirmation proceed
+without asking when used inside a user-defined command.  Many @value{GDBN} 
+commands that normally print messages to say what they are doing omit the 
+messages when used in a user-defined command.
+
+@node Hooks, Command Files, Define, Sequences
+@section User-defined command hooks
+@cindex command files
+
+You may define @emph{hooks}, which are a special kind of user-defined
+command.  Whenever you run the command @samp{foo}, if the user-defined
+command @samp{hook-foo} exists, it is executed (with no arguments)
+before that command.
+
+In addition, a pseudo-command, @samp{stop} exists.  Defining
+(@samp{hook-stop}) makes the associated commands execute every time
+execution stops in your program: before breakpoint commands are run,
+displays are printed, or the stack frame is printed.
+
+@ifclear BARETARGET
+For example, to ignore @code{SIGALRM} signals while
+single-stepping, but treat them normally during normal execution,
+you could define:
+
+@example
+define hook-stop
+handle SIGALRM nopass
+end
+
+define hook-run
+handle SIGALRM pass
+end
+
+define hook-continue
+handle SIGLARM pass
+end
+@end example
+@end ifclear
+
+You can define a hook for any single-word command in @value{GDBN}, but
+not for command aliases; you should define a hook for the basic command
+name, e.g.  @code{backtrace} rather than @code{bt}.
+@c FIXME!  So how does Joe User discover whether a command is an alias
+@c or not?
+If an error occurs during the execution of your hook, execution of
+@value{GDBN} commands stops and @value{GDBN} issues a prompt
+(before the command that you actually typed had a chance to run).
+
+If you try to define a hook which does not match any known command, you
+get a warning from the @code{define} command.
+
+@node Command Files, Output, Hooks, Sequences
+@section Command files
+
+@cindex command files
+A command file for @value{GDBN} is a file of lines that are @value{GDBN} 
+commands.  Comments (lines starting with @kbd{#}) may also be included.  
+An empty line in a command file does nothing; it does not mean to repeat 
+the last command, as it would from the terminal.
+
+@cindex init file
+@cindex @file{.gdbinit}
+When you start @value{GDBN}, it automatically executes commands from its
+@dfn{init files}.  These are files named @file{.gdbinit} on Unix, or
+@file{gdb.ini} on DOS/Windows.  @value{GDBN} reads the init file (if
+any) in your home directory, then processes command line options and
+operands, and then reads the init file (if any) in the current working
+directory.  This is so the init file in your home directory can set
+options (such as @code{set complaints}) which affect the processing of
+the command line options and operands.  The init files are not executed
+if you use the @samp{-nx} option; @pxref{Mode Options, ,Choosing modes}.
+
+@ifset GENERIC
+@cindex init file name
+On some configurations of @value{GDBN}, the init file is known by a
+different name (these are typically environments where a specialized
+form of @value{GDBN} may need to coexist with other forms, hence a
+different name for the specialized version's init file).  These are the
+environments with special init file names:
+
+@kindex .vxgdbinit
+@itemize @bullet
+@item
+VxWorks (Wind River Systems real-time OS): @samp{.vxgdbinit}
+
+@kindex .os68gdbinit
+@item
+OS68K (Enea Data Systems real-time OS): @samp{.os68gdbinit}
+
+@kindex .esgdbinit
+@item
+ES-1800 (Ericsson Telecom AB M68000 emulator): @samp{.esgdbinit}
+@end itemize
+@end ifset
+
+You can also request the execution of a command file with the
+@code{source} command:
+
+@table @code
+@kindex source
+@item source @var{filename}
+Execute the command file @var{filename}.
+@end table
+
+The lines in a command file are executed sequentially.  They are not
+printed as they are executed.  An error in any command terminates execution
+of the command file.
+
+Commands that would ask for confirmation if used interactively proceed
+without asking when used in a command file.  Many @value{GDBN} commands that
+normally print messages to say what they are doing omit the messages
+when called from command files.
+
+@node Output,  , Command Files, Sequences
+@section Commands for controlled output
+
+During the execution of a command file or a user-defined command, normal
+@value{GDBN} output is suppressed; the only output that appears is what is
+explicitly printed by the commands in the definition.  This section
+describes three commands useful for generating exactly the output you
+want.
+
+@table @code
+@kindex echo
+@item echo @var{text}
+@c I do not consider backslash-space a standard C escape sequence
+@c because it is not in ANSI.
+Print @var{text}.  Nonprinting characters can be included in
+@var{text} using C escape sequences, such as @samp{\n} to print a
+newline.  @strong{No newline is printed unless you specify one.}
+In addition to the standard C escape sequences, a backslash followed
+by a space stands for a space.  This is useful for displaying a
+string with spaces at the beginning or the end, since leading and
+trailing spaces are otherwise trimmed from all arguments.  
+To print @samp{@w{ }and foo =@w{ }}, use the command
+@samp{echo \@w{ }and foo = \@w{ }}.
+
+A backslash at the end of @var{text} can be used, as in C, to continue
+the command onto subsequent lines.  For example,
+
+@example
+echo This is some text\n\
+which is continued\n\
+onto several lines.\n
+@end example
+
+produces the same output as
+
+@example
+echo This is some text\n
+echo which is continued\n
+echo onto several lines.\n
+@end example
+
+@kindex output
+@item output @var{expression}
+Print the value of @var{expression} and nothing but that value: no
+newlines, no @samp{$@var{nn} = }.  The value is not entered in the
+value history either.  @xref{Expressions, ,Expressions}, for more information 
+on expressions.
+
+@item output/@var{fmt} @var{expression}
+Print the value of @var{expression} in format @var{fmt}.  You can use
+the same formats as for @code{print}.  @xref{Output Formats,,Output
+formats}, for more information.
+
+@kindex printf
+@item printf @var{string}, @var{expressions}@dots{}
+Print the values of the @var{expressions} under the control of
+@var{string}.  The @var{expressions} are separated by commas and may be
+either numbers or pointers.  Their values are printed as specified by
+@var{string}, exactly as if your program were to execute the C
+subroutine
+
+@example
+printf (@var{string}, @var{expressions}@dots{});
+@end example
+
+For example, you can print two values in hex like this:
+
+@smallexample
+printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
+@end smallexample
+
+The only backslash-escape sequences that you can use in the format
+string are the simple ones that consist of backslash followed by a
+letter.
+@end table
+
+@ifclear DOSHOST
+@node Emacs, GDB Bugs, Sequences, Top
+@chapter Using @value{GDBN} under @sc{gnu} Emacs
+
+@cindex Emacs
+@cindex @sc{gnu} Emacs
+A special interface allows you to use @sc{gnu} Emacs to view (and
+edit) the source files for the program you are debugging with
+@value{GDBN}.
+
+To use this interface, use the command @kbd{M-x gdb} in Emacs.  Give the
+executable file you want to debug as an argument.  This command starts
+@value{GDBN} as a subprocess of Emacs, with input and output through a newly
+created Emacs buffer.
+@ifset HPPA
+(Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
+@end ifset
+
+Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
+things:
+
+@itemize @bullet
+@item
+All ``terminal'' input and output goes through the Emacs buffer.
+@end itemize
+
+This applies both to @value{GDBN} commands and their output, and to the input
+and output done by the program you are debugging.
+
+This is useful because it means that you can copy the text of previous
+commands and input them again; you can even use parts of the output
+in this way.
+
+All the facilities of Emacs' Shell mode are available for interacting
+with your program.  In particular, you can send signals the usual
+way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
+stop.
+
+@itemize @bullet
+@item
+@value{GDBN} displays source code through Emacs.
+@end itemize
+
+Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
+source file for that frame and puts an arrow (@samp{=>}) at the
+left margin of the current line.  Emacs uses a separate buffer for
+source display, and splits the screen to show both your @value{GDBN} session
+and the source.
+
+Explicit @value{GDBN} @code{list} or search commands still produce output as
+usual, but you probably have no reason to use them from Emacs.
+
+@quotation
+@emph{Warning:} If the directory where your program resides is not your
+current directory, it can be easy to confuse Emacs about the location of
+the source files, in which case the auxiliary display buffer does not
+appear to show your source.  @value{GDBN} can find programs by searching your
+environment's @code{PATH} variable, so the @value{GDBN} input and output
+session proceeds normally; but Emacs does not get enough information
+back from @value{GDBN} to locate the source files in this situation.  To
+avoid this problem, either start @value{GDBN} mode from the directory where
+your program resides, or specify an absolute file name when prompted for the
+@kbd{M-x gdb} argument.
+
+A similar confusion can result if you use the @value{GDBN} @code{file} command to
+switch to debugging a program in some other location, from an existing
+@value{GDBN} buffer in Emacs.
+@end quotation
+
+By default, @kbd{M-x gdb} calls the program called @file{gdb}.  If
+you need to call @value{GDBN} by a different name (for example, if you keep
+several configurations around, with different names) you can set the
+Emacs variable @code{gdb-command-name}; for example,
+
+@example
+(setq gdb-command-name "mygdb")
+@end example
+
+@noindent
+(preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or
+in your @file{.emacs} file) makes Emacs call the program named
+``@code{mygdb}'' instead.
+
+In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
+addition to the standard Shell mode commands:
+
+@table @kbd
+@item C-h m
+Describe the features of Emacs' @value{GDBN} Mode.
+
+@item M-s
+Execute to another source line, like the @value{GDBN} @code{step} command; also
+update the display window to show the current file and location.
+
+@item M-n
+Execute to next source line in this function, skipping all function
+calls, like the @value{GDBN} @code{next} command.  Then update the display window
+to show the current file and location.
+
+@item M-i
+Execute one instruction, like the @value{GDBN} @code{stepi} command; update
+display window accordingly.
+
+@item M-x gdb-nexti
+Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
+display window accordingly.
+
+@item C-c C-f
+Execute until exit from the selected stack frame, like the @value{GDBN}
+@code{finish} command.
+
+@item M-c
+Continue execution of your program, like the @value{GDBN} @code{continue}
+command.
+
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
+
+@item M-u
+Go up the number of frames indicated by the numeric argument
+(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
+like the @value{GDBN} @code{up} command.
+
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
+
+@item M-d
+Go down the number of frames indicated by the numeric argument, like the
+@value{GDBN} @code{down} command.
+
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
+
+@item C-x &
+Read the number where the cursor is positioned, and insert it at the end
+of the @value{GDBN} I/O buffer.  For example, if you wish to disassemble code
+around an address that was displayed earlier, type @kbd{disassemble};
+then move the cursor to the address display, and pick up the
+argument for @code{disassemble} by typing @kbd{C-x &}.
+
+You can customize this further by defining elements of the list
+@code{gdb-print-command}; once it is defined, you can format or
+otherwise process numbers picked up by @kbd{C-x &} before they are
+inserted.  A numeric argument to @kbd{C-x &} indicates that you
+wish special formatting, and also acts as an index to pick an element of the
+list.  If the list element is a string, the number to be inserted is
+formatted using the Emacs function @code{format}; otherwise the number
+is passed as an argument to the corresponding list element.
+@end table
+
+In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
+tells @value{GDBN} to set a breakpoint on the source line point is on.
+
+If you accidentally delete the source-display buffer, an easy way to get
+it back is to type the command @code{f} in the @value{GDBN} buffer, to
+request a frame display; when you run under Emacs, this recreates
+the source buffer if necessary to show you the context of the current
+frame.
+
+The source files displayed in Emacs are in ordinary Emacs buffers
+which are visiting the source files in the usual way.  You can edit
+the files with these buffers if you wish; but keep in mind that @value{GDBN}
+communicates with Emacs in terms of line numbers.  If you add or
+delete lines from the text, the line numbers that @value{GDBN} knows cease
+to correspond properly with the code.
+
+@c The following dropped because Epoch is nonstandard.  Reactivate
+@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
+@ignore
+@kindex Emacs Epoch environment
+@kindex Epoch
+@kindex inspect
+
+Version 18 of @sc{gnu} Emacs has a built-in window system 
+called the @code{epoch}
+environment.  Users of this environment can use a new command,
+@code{inspect} which performs identically to @code{print} except that
+each value is printed in its own window.
+@end ignore
+@end ifclear
+
+@node GDB Bugs
+@c links whacked to pacify makeinfo
+@c , Command Line Editing, Emacs, Top
+@chapter Reporting Bugs in @value{GDBN}
+@cindex bugs in @value{GDBN}
+@cindex reporting bugs in @value{GDBN}
+
+Your bug reports play an essential role in making @value{GDBN} reliable.
+
+Reporting a bug may help you by bringing a solution to your problem, or it
+may not.  But in any case the principal function of a bug report is to help
+the entire community by making the next version of @value{GDBN} work better.  Bug
+reports are your contribution to the maintenance of @value{GDBN}.
+
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
+
+@menu
+* Bug Criteria::                Have you found a bug?
+* Bug Reporting::               How to report bugs
+@end menu
+
+@node Bug Criteria, Bug Reporting, GDB Bugs, GDB Bugs
+@section Have you found a bug?
+@cindex bug criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@itemize @bullet
+@cindex fatal signal
+@cindex debugger crash
+@cindex crash of debugger
+@item
+If the debugger gets a fatal signal, for any input whatever, that is a
+@value{GDBN} bug.  Reliable debuggers never crash.
+
+@cindex error on valid input
+@item
+If @value{GDBN} produces an error message for valid input, that is a
+bug.  (Note that if you're cross debugging, the problem may also be
+somewhere in the connection to the target.)
+
+@cindex invalid input
+@item
+If @value{GDBN} does not produce an error message for invalid input,
+that is a bug.  However, you should note that your idea of
+``invalid input'' might be our idea of ``an extension'' or ``support
+for traditional practice''.
+
+@item
+If you are an experienced user of debugging tools, your suggestions
+for improvement of @value{GDBN} are welcome in any case.
+@end itemize
+
+@node Bug Reporting,  , Bug Criteria, GDB Bugs
+@section How to report bugs
+@cindex bug reports
+@cindex @value{GDBN} bugs, reporting
+
+@ifclear HPPA
+A number of companies and individuals offer support for @sc{gnu} products.
+If you obtained @value{GDBN} from a support organization, we recommend you
+contact that organization first.
+
+You can find contact information for many support companies and
+individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
+distribution.
+@c should add a web page ref...
+
+In any event, we also recommend that you send bug reports for
+@value{GDBN} to this addresses:
+
+@example
+bug-gdb@@prep.ai.mit.edu
+@end example
+
+@strong{Do not send bug reports to @samp{info-gdb}, or to
+@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
+not want to receive bug reports.  Those that do have arranged to receive
+@samp{bug-gdb}.
+
+The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
+serves as a repeater.  The mailing list and the newsgroup carry exactly
+the same messages.  Often people think of posting bug reports to the
+newsgroup instead of mailing them.  This appears to work, but it has one
+problem which can be crucial: a newsgroup posting often lacks a mail
+path back to the sender.  Thus, if we need to ask for more information,
+we may be unable to reach you.  For this reason, it is better to send
+bug reports to the mailing list.
+
+As a last resort, send bug reports on paper to:
+
+@example
+@sc{gnu} Debugger Bugs
+Free Software Foundation Inc.
+59 Temple Place - Suite 330
+Boston, MA 02111-1307
+USA
+@end example
+@end ifclear
+
+@ifset HPPA
+If you obtained HP GDB as part of your HP ANSI C or HP ANSI C++ compiler
+kit, report problems to your HP Support Representative.
+
+If you obtained HP GDB from the Hewlett-Packard Web site, report
+problems by electronic mail to @code{wdb-www@@ch.hp.com}.
+@end ifset
+
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}.  If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the
+problem and assume that some details do not matter.  Thus, you might
+assume that the name of the variable you use in an example does not matter.
+Well, probably it does not, but one cannot be sure.  Perhaps the bug is a
+stray memory reference which happens to fetch from the location where that
+name is stored in memory; perhaps, if the name were different, the contents
+of that location would fool the debugger into doing the right thing despite
+the bug.  Play it safe and give a specific, complete example.  That is the
+easiest thing for you to do, and the most helpful.
+
+Keep in mind that the purpose of a bug report is to enable us to fix the
+bug.  It may be that the bug has been reported previously, but neither
+you nor we can know that unless your bug report is complete and
+self-contained.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?''  Those bug reports are useless, and we urge everyone to
+@emph{refuse to respond to them} except to chide the sender to report
+bugs properly.
+
+To enable us to fix the bug, you should include all these things:
+
+@itemize @bullet
+@item
+The version of @value{GDBN}.  @value{GDBN} announces it if you start
+with no arguments; you can also print it at any time using @code{show
+version}.
+
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of @value{GDBN}.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@ifclear HPPA
+@item
+What compiler (and its version) was used to compile @value{GDBN}---e.g.
+``@value{GCC}--2.8.1''.
+@end ifclear
+
+@item
+What compiler (and its version) was used to compile the program you are
+debugging---e.g.  ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
+C Compiler''.  For GCC, you can say @code{gcc --version} to get this
+information; for other compilers, see the documentation for those
+compilers.
+
+@item
+The command arguments you gave the compiler to compile your example and
+observe the bug.  For example, did you use @samp{-O}?  To guarantee
+you will not omit something important, list them all.  A copy of the
+Makefile (or the output from make) is sufficient.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
+
+@item
+A complete input script, and all necessary source files, that will
+reproduce the bug.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect.  For example, ``It gets a fatal signal.''
+
+Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
+will certainly notice it.  But if the bug is incorrect output, we might
+not notice unless it is glaringly wrong.  You might as well not give us
+a chance to make a mistake.
+
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly.  Suppose something strange is going on, such as, your
+copy of @value{GDBN} is out of synch, or you have encountered a bug in
+the C library on your system.  (This has happened!)  Your copy might
+crash and ours would not.  If you told us to expect a crash, then when
+ours fails to crash, we would know that the bug was not happening for
+us.  If you had not told us to expect a crash, then we would not be able
+to draw any conclusion from our observations.
+
+@ifclear HPPA
+@item
+If you wish to suggest changes to the @value{GDBN} source, send us context
+diffs.  If you even discuss something in the @value{GDBN} source, refer to
+it by context, not by line number.
+
+The line numbers in our development sources will not match those in your
+sources.  Your line numbers would convey no useful information to us.
+@end ifclear
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
+
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us.  Errors in the
+output will be easier to spot, running under the debugger will take
+less time, and so on.
+
+However, simplification is not vital; if you do not want to do this,
+report the bug anyway and send us the entire test case you used.
+
+@item
+A patch for the bug.
+
+A patch for the bug does help us if it is a good one.  But do not omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need.  We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
+
+Sometimes with a program as complicated as @value{GDBN} it is very hard to
+construct an example that will make the program follow a certain path
+through the code.  If you do not send us the example, we will not be able
+to construct one, so we will not be able to verify that the bug is fixed.
+
+And if we cannot understand what bug you are trying to fix, or why your
+patch should be an improvement, we will not install it.  A test case will
+help us to understand.
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong.  Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
+
+@c The readline documentation is distributed with the readline code 
+@c and consists of the two following files:
+@c     rluser.texinfo
+@c     inc-hist.texi
+@c Use -I with makeinfo to point to the appropriate directory,
+@c environment var TEXINPUTS with TeX.
+@include rluser.texinfo
+@include inc-hist.texi
+
+
+@ifclear PRECONFIGURED
+@ifclear HPPA
+@node Formatting Documentation
+@c links whacked to pacify makeinfo
+@c , Installing GDB, Renamed Commands, Top
+@appendix Formatting Documentation
+
+@cindex @value{GDBN} reference card
+@cindex reference card
+The @value{GDBN} 4 release includes an already-formatted reference card, ready
+for printing with PostScript or Ghostscript, in the @file{gdb}
+subdirectory of the main source directory@footnote{In
+@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
+release.}.  If you can use PostScript or Ghostscript with your printer,
+you can print the reference card immediately with @file{refcard.ps}.
+
+The release also includes the source for the reference card.  You
+can format it, using @TeX{}, by typing:
+
+@example
+make refcard.dvi
+@end example
+
+The @value{GDBN} reference card is designed to print in @dfn{landscape} 
+mode on US ``letter'' size paper; 
+that is, on a sheet 11 inches wide by 8.5 inches
+high.  You will need to specify this form of printing as an option to
+your @sc{dvi} output program.
+
+@cindex documentation
+
+All the documentation for @value{GDBN} comes as part of the machine-readable
+distribution.  The documentation is written in Texinfo format, which is
+a documentation system that uses a single source file to produce both
+on-line information and a printed manual.  You can use one of the Info
+formatting commands to create the on-line version of the documentation
+and @TeX{} (or @code{texi2roff}) to typeset the printed version.
+
+@value{GDBN} includes an already formatted copy of the on-line Info
+version of this manual in the @file{gdb} subdirectory.  The main Info
+file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
+subordinate files matching @samp{gdb.info*} in the same directory.  If
+necessary, you can print out these files, or read them with any editor;
+but they are easier to read using the @code{info} subsystem in @sc{gnu}
+Emacs or the standalone @code{info} program, available as part of the
+@sc{gnu} Texinfo distribution.
+
+If you want to format these Info files yourself, you need one of the
+Info formatting programs, such as @code{texinfo-format-buffer} or
+@code{makeinfo}.
+
+If you have @code{makeinfo} installed, and are in the top level
+@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
+version @value{GDBVN}), you can make the Info file by typing:
+
+@example
+cd gdb
+make gdb.info
+@end example
+
+If you want to typeset and print copies of this manual, you need @TeX{},
+a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
+Texinfo definitions file.
+
+@TeX{} is a typesetting program; it does not print files directly, but
+produces output files called @sc{dvi} files.  To print a typeset
+document, you need a program to print @sc{dvi} files.  If your system
+has @TeX{} installed, chances are it has such a program.  The precise
+command to use depends on your system; @kbd{lpr -d} is common; another
+(for PostScript devices) is @kbd{dvips}.  The @sc{dvi} print command may
+require a file name without any extension or a @samp{.dvi} extension.
+
+@TeX{} also requires a macro definitions file called
+@file{texinfo.tex}.  This file tells @TeX{} how to typeset a document
+written in Texinfo format.  On its own, @TeX{} cannot either read or
+typeset a Texinfo file.  @file{texinfo.tex} is distributed with GDB
+and is located in the @file{gdb-@var{version-number}/texinfo}
+directory.
+
+If you have @TeX{} and a @sc{dvi} printer program installed, you can
+typeset and print this manual.  First switch to the the @file{gdb}
+subdirectory of the main source directory (for example, to
+@file{gdb-@value{GDBVN}/gdb}) and type:
+
+@example
+make gdb.dvi
+@end example
+
+Then give @file{gdb.dvi} to your @sc{dvi} printing program.
+@end ifclear
+
+@node Installing GDB, Index, Using History Interactively, Top
+@appendix Installing @value{GDBN}
+@cindex configuring @value{GDBN}
+@cindex installation
+
+@ifset HPPA
+If you obtain @value{GDBN} (HP WDB 0.75) as part of your HP ANSI C or
+HP ANSI C++ Developer's Kit at HP-UX Release 11.0, you do not have to
+take any special action to build or install @value{GDBN}.
+
+If you obtain @value{GDBN} (HP WDB 0.75) from an HP web site, you may
+download either a @code{swinstall}-able package or a source tree, or
+both.
+
+Most customers will want to install the @value{GDBN} binary that is part
+of the @code{swinstall}-able package.  To do so, use a command of the
+form
+
+@smallexample
+/usr/sbin/swinstall -s @var{package-name} WDB
+@end smallexample
+
+Alternatively, it is possible to build @value{GDBN} from the source
+distribution.  Sophisticated customers who want to modify the debugger
+sources to tailor @value{GDBN} to their their needs may wish to do this.
+The source distribution consists of a @code{tar}'ed source tree rooted
+at @file{gdb-4.16/...}.  The instructions that follow describe how to
+build a @file{gdb} executable from this source tree.  HP believes that
+these instructions apply to the WDB source tree that it distributes.
+However, HP does not explicitly support building a @file{gdb} for any
+non-HP platform from the WDB source tree.  It may work, but HP has not
+tested it for any platforms other than those described in the WDB 0.75
+Release Notes.
+@end ifset
+
+@value{GDBN} comes with a @code{configure} script that automates the process
+of preparing @value{GDBN} for installation; you can then use @code{make} to
+build the @code{gdb} program.
+@iftex
+@c irrelevant in info file; it's as current as the code it lives with.
+@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
+look at the @file{README} file in the sources; we may have improved the
+installation procedures since publishing this manual.}
+@end iftex
+
+The @value{GDBN} distribution includes all the source code you need for 
+@value{GDBN} in a single directory, whose name is usually composed by 
+appending the version number to @samp{gdb}.
+
+For example, the @value{GDBN} version @value{GDBVN} distribution is in the
+@file{gdb-@value{GDBVN}} directory.  That directory contains:
+
+@table @code
+@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
+script for configuring @value{GDBN} and all its supporting libraries
+
+@item gdb-@value{GDBVN}/gdb
+the source specific to @value{GDBN} itself
+
+@item gdb-@value{GDBVN}/bfd
+source for the Binary File Descriptor library
+
+@item gdb-@value{GDBVN}/include
+@sc{gnu} include files
+
+@item gdb-@value{GDBVN}/libiberty
+source for the @samp{-liberty} free software library
+
+@item gdb-@value{GDBVN}/opcodes
+source for the library of opcode tables and disassemblers
+
+@item gdb-@value{GDBVN}/readline
+source for the @sc{gnu} command-line interface
+
+@item gdb-@value{GDBVN}/glob
+source for the @sc{gnu} filename pattern-matching subroutine
+
+@item gdb-@value{GDBVN}/mmalloc
+source for the @sc{gnu} memory-mapped malloc package
+@end table
+
+The simplest way to configure and build @value{GDBN} is to run @code{configure}
+from the @file{gdb-@var{version-number}} source directory, which in
+this example is the @file{gdb-@value{GDBVN}} directory.
+
+First switch to the @file{gdb-@var{version-number}} source directory
+if you are not already in it; then run @code{configure}.  Pass the
+identifier for the platform on which @value{GDBN} will run as an
+argument.
+
+For example:
+
+@example
+cd gdb-@value{GDBVN}
+./configure @var{host}
+make
+@end example
+
+@noindent
+where @var{host} is an identifier such as @samp{sun4} or
+@samp{decstation}, that identifies the platform where @value{GDBN} will run.
+(You can often leave off @var{host}; @code{configure} tries to guess the
+correct value by examining your system.)
+
+Running @samp{configure @var{host}} and then running @code{make} builds the
+@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
+libraries, then @code{gdb} itself.  The configured source files, and the
+binaries, are left in the corresponding source directories.
+
+@need 750
+@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
+system does not recognize this automatically when you run a different
+shell, you may need to run @code{sh} on it explicitly:
+
+@example
+sh configure @var{host}
+@end example
+
+If you run @code{configure} from a directory that contains source
+directories for multiple libraries or programs, such as the
+@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
+creates configuration files for every directory level underneath (unless
+you tell it not to, with the @samp{--norecursion} option).
+
+You can run the @code{configure} script from any of the
+subordinate directories in the @value{GDBN} distribution if you only want to
+configure that subdirectory, but be sure to specify a path to it.
+
+For example, with version @value{GDBVN}, type the following to configure only
+the @code{bfd} subdirectory:
+
+@example
+@group
+cd gdb-@value{GDBVN}/bfd
+../configure @var{host}
+@end group
+@end example
+
+You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
+However, you should make sure that the shell on your path (named by
+the @samp{SHELL} environment variable) is publicly readable.  Remember
+that @value{GDBN} uses the shell to start your program---some systems refuse to
+let @value{GDBN} debug child processes whose programs are not readable.
+
+@menu
+* Separate Objdir::             Compiling @value{GDBN} in another directory
+* Config Names::                Specifying names for hosts and targets
+* Configure Options::           Summary of options for configure
+@end menu
+
+@node Separate Objdir, Config Names, Installing GDB, Installing GDB
+@section Compiling @value{GDBN} in another directory
+
+If you want to run @value{GDBN} versions for several host or target machines,
+you need a different @code{gdb} compiled for each combination of
+host and target.  @code{configure} is designed to make this easy by
+allowing you to generate each configuration in a separate subdirectory,
+rather than in the source directory.  If your @code{make} program
+handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
+@code{make} in each of these directories builds the @code{gdb}
+program specified there.
+
+To build @code{gdb} in a separate directory, run @code{configure}
+with the @samp{--srcdir} option to specify where to find the source.
+(You also need to specify a path to find @code{configure}
+itself from your working directory.  If the path to @code{configure}
+would be the same as the argument to @samp{--srcdir}, you can leave out
+the @samp{--srcdir} option; it is assumed.)
+
+For example, with version @value{GDBVN}, you can build @value{GDBN} in a 
+separate directory for a Sun 4 like this:
+
+@example
+@group
+cd gdb-@value{GDBVN}
+mkdir ../gdb-sun4
+cd ../gdb-sun4
+../gdb-@value{GDBVN}/configure sun4
+make
+@end group
+@end example
+
+When @code{configure} builds a configuration using a remote source
+directory, it creates a tree for the binaries with the same structure
+(and using the same names) as the tree under the source directory.  In
+the example, you'd find the Sun 4 library @file{libiberty.a} in the
+directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
+@file{gdb-sun4/gdb}.
+
+One popular reason to build several @value{GDBN} configurations in separate
+directories is to configure @value{GDBN} for cross-compiling (where 
+@value{GDBN} runs on one machine---the @dfn{host}---while debugging 
+programs that run on another machine---the @dfn{target}).  
+You specify a cross-debugging target by
+giving the @samp{--target=@var{target}} option to @code{configure}.
+
+When you run @code{make} to build a program or library, you must run
+it in a configured directory---whatever directory you were in when you
+called @code{configure} (or one of its subdirectories).
+
+The @code{Makefile} that @code{configure} generates in each source
+directory also runs recursively.  If you type @code{make} in a source
+directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
+directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
+will build all the required libraries, and then build GDB.
+
+When you have multiple hosts or targets configured in separate
+directories, you can run @code{make} on them in parallel (for example,
+if they are NFS-mounted on each of the hosts); they will not interfere
+with each other.
+
+@node Config Names, Configure Options, Separate Objdir, Installing GDB
+@section Specifying names for hosts and targets
+
+The specifications used for hosts and targets in the @code{configure}
+script are based on a three-part naming scheme, but some short predefined
+aliases are also supported.  The full naming scheme encodes three pieces
+of information in the following pattern:
+
+@example
+@var{architecture}-@var{vendor}-@var{os}
+@end example
+
+For example, you can use the alias @code{sun4} as a @var{host} argument,
+or as the value for @var{target} in a @code{--target=@var{target}}
+option.  The equivalent full name is @samp{sparc-sun-sunos4}.
+
+The @code{configure} script accompanying @value{GDBN} does not provide
+any query facility to list all supported host and target names or
+aliases.  @code{configure} calls the Bourne shell script
+@code{config.sub} to map abbreviations to full names; you can read the
+script, if you wish, or you can use it to test your guesses on
+abbreviations---for example:
+
+@smallexample
+% sh config.sub i386-linux
+i386-pc-linux-gnu
+% sh config.sub alpha-linux
+alpha-unknown-linux-gnu
+% sh config.sub hp9k700
+hppa1.1-hp-hpux
+% sh config.sub sun4
+sparc-sun-sunos4.1.1
+% sh config.sub sun3
+m68k-sun-sunos4.1.1
+% sh config.sub i986v
+Invalid configuration `i986v': machine `i986v' not recognized
+@end smallexample
+
+@noindent
+@code{config.sub} is also distributed in the @value{GDBN} source
+directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
+
+@node Configure Options,  , Config Names, Installing GDB
+@section @code{configure} options
+
+Here is a summary of the @code{configure} options and arguments that
+are most often useful for building @value{GDBN}.  @code{configure} also has
+several other options not listed here.  @inforef{What Configure
+Does,,configure.info}, for a full explanation of @code{configure}.
+
+@example
+configure @r{[}--help@r{]}
+          @r{[}--prefix=@var{dir}@r{]}
+          @r{[}--exec-prefix=@var{dir}@r{]}
+          @r{[}--srcdir=@var{dirname}@r{]}
+          @r{[}--norecursion@r{]} @r{[}--rm@r{]}
+          @r{[}--target=@var{target}@r{]}
+          @var{host}
+@end example
+
+@noindent
+You may introduce options with a single @samp{-} rather than
+@samp{--} if you prefer; but you may abbreviate option names if you use
+@samp{--}.
+
+@table @code
+@item --help
+Display a quick summary of how to invoke @code{configure}.
+
+@item --prefix=@var{dir}
+Configure the source to install programs and files under directory
+@file{@var{dir}}.
+
+@item --exec-prefix=@var{dir}
+Configure the source to install programs under directory
+@file{@var{dir}}.
+
+@c avoid splitting the warning from the explanation:
+@need 2000
+@item --srcdir=@var{dirname}
+@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
+@code{make} that implements the @code{VPATH} feature.}@*
+Use this option to make configurations in directories separate from the
+@value{GDBN} source directories.  Among other things, you can use this to
+build (or maintain) several configurations simultaneously, in separate
+directories.  @code{configure} writes configuration specific files in
+the current directory, but arranges for them to use the source in the
+directory @var{dirname}.  @code{configure} creates directories under
+the working directory in parallel to the source directories below
+@var{dirname}.
+
+@item --norecursion
+Configure only the directory level where @code{configure} is executed; do not
+propagate configuration to subdirectories.
+
+@item --target=@var{target}
+Configure @value{GDBN} for cross-debugging programs running on the specified
+@var{target}.  Without this option, @value{GDBN} is configured to debug
+programs that run on the same machine (@var{host}) as @value{GDBN} itself.
+
+There is no convenient way to generate a list of all available targets.
+
+@item @var{host} @dots{}
+Configure @value{GDBN} to run on the specified @var{host}.
+
+There is no convenient way to generate a list of all available hosts.
+@end table
+
+There are many other options available as well, but they are generally
+needed for special purposes only.
+@end ifclear
+
+ 
+@node Index,  , Installing GDB, Top
+@unnumbered Index
+
+@printindex cp
+
+@tex
+% I think something like @colophon should be in texinfo.  In the
+% meantime:
+\long\def\colophon{\hbox to0pt{}\vfill
+\centerline{The body of this manual is set in}
+\centerline{\fontname\tenrm,}
+\centerline{with headings in {\bf\fontname\tenbf}}
+\centerline{and examples in {\tt\fontname\tentt}.}
+\centerline{{\it\fontname\tenit\/},}
+\centerline{{\bf\fontname\tenbf}, and}
+\centerline{{\sl\fontname\tensl\/}}
+\centerline{are used for emphasis.}\vfill}
+\page\colophon
+% Blame: doc@cygnus.com, 1991.
+@end tex
+
+@contents
+@bye
diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
new file mode 100644
index 0000000000..99f081dcda
--- /dev/null
+++ b/gdb/doc/gdbint.texinfo
@@ -0,0 +1,2711 @@
+\input texinfo
+@setfilename gdbint.info
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Gdb-Internals: (gdbint).	The GNU debugger's internals.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@ifinfo
+This file documents the internals of the GNU debugger GDB.
+
+Copyright 1990-1999 Free Software Foundation, Inc.
+Contributed by Cygnus Solutions.  Written by John Gilmore.
+Second Edition by Stan Shebs.
+
+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.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy or distribute modified versions of this
+manual under the terms of the GPL (for which purpose this text may be
+regarded as a program in the language TeX).
+@end ifinfo
+
+@setchapternewpage off
+@settitle GDB Internals
+
+@titlepage
+@title{GDB Internals}
+@subtitle{A guide to the internals of the GNU debugger}
+@author John Gilmore
+@author Cygnus Solutions
+@author Second Edition:
+@author Stan Shebs
+@author Cygnus Solutions
+@page
+@tex
+\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
+\xdef\manvers{\$Revision$}  % For use in headers, footers too
+{\parskip=0pt
+\hfill Cygnus Solutions\par
+\hfill \manvers\par
+\hfill \TeX{}info \texinfoversion\par
+}
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1990-1999 Free Software Foundation, Inc.
+
+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.
+
+@end titlepage
+
+@node Top
+@c Perhaps this should be the title of the document (but only for info,
+@c not for TeX).  Existing GNU manuals seem inconsistent on this point.
+@top Scope of this Document
+
+This document documents the internals of the GNU debugger, GDB.  It
+includes description of GDB's key algorithms and operations, as well
+as the mechanisms that adapt GDB to specific hosts and targets.
+
+@menu
+* Requirements::
+* Overall Structure::
+* Algorithms::
+* User Interface::
+* Symbol Handling::
+* Language Support::
+* Host Definition::
+* Target Architecture Definition::
+* Target Vector Definition::
+* Native Debugging::
+* Support Libraries::
+* Coding::
+* Porting GDB::
+* Hints::
+@end menu
+
+@node Requirements
+
+@chapter Requirements
+
+Before diving into the internals, you should understand the formal
+requirements and other expectations for GDB.  Although some of these may
+seem obvious, there have been proposals for GDB that have run counter to
+these requirements.
+
+First of all, GDB is a debugger.  It's not designed to be a front panel
+for embedded systems.  It's not a text editor.  It's not a shell.  It's
+not a programming environment.
+
+GDB is an interactive tool.  Although a batch mode is available, GDB's
+primary role is to interact with a human programmer.
+
+GDB should be responsive to the user.  A programmer hot on the trail of
+a nasty bug, and operating under a looming deadline, is going to be very
+impatient of everything, including the response time to debugger
+commands.
+
+GDB should be relatively permissive, such as for expressions.  While the
+compiler should be picky (or have the option to be made picky), since
+source code lives for a long time usually, the programmer doing
+debugging shouldn't be spending time figuring out to mollify the
+debugger.
+
+GDB will be called upon to deal with really large programs.  Executable
+sizes of 50 to 100 megabytes occur regularly, and we've heard reports of
+programs approaching 1 gigabyte in size.
+
+GDB should be able to run everywhere.  No other debugger is available
+for even half as many configurations as GDB supports.
+
+
+@node Overall Structure
+
+@chapter Overall Structure
+
+GDB consists of three major subsystems: user interface, symbol handling
+(the ``symbol side''), and target system handling (the ``target side'').
+
+Ther user interface consists of several actual interfaces, plus
+supporting code.
+
+The symbol side consists of object file readers, debugging info
+interpreters, symbol table management, source language expression
+parsing, type and value printing.
+
+The target side consists of execution control, stack frame analysis, and
+physical target manipulation.
+
+The target side/symbol side division is not formal, and there are a
+number of exceptions.  For instance, core file support involves symbolic
+elements (the basic core file reader is in BFD) and target elements (it
+supplies the contents of memory and the values of registers).  Instead,
+this division is useful for understanding how the minor subsystems
+should fit together.
+
+@section The Symbol Side
+
+The symbolic side of GDB can be thought of as ``everything you can do in
+GDB without having a live program running''.  For instance, you can look
+at the types of variables, and evaluate many kinds of expressions.
+
+@section The Target Side
+
+The target side of GDB is the ``bits and bytes manipulator''.  Although
+it may make reference to symbolic info here and there, most of the
+target side will run with only a stripped executable available -- or
+even no executable at all, in remote debugging cases.
+
+Operations such as disassembly, stack frame crawls, and register
+display, are able to work with no symbolic info at all.  In some cases,
+such as disassembly, GDB will use symbolic info to present addresses
+relative to symbols rather than as raw numbers, but it will work either
+way.
+
+@section Configurations
+
+@dfn{Host} refers to attributes of the system where GDB runs.
+@dfn{Target} refers to the system where the program being debugged
+executes.  In most cases they are the same machine, in which case a
+third type of @dfn{Native} attributes come into play.
+
+Defines and include files needed to build on the host are host support.
+Examples are tty support, system defined types, host byte order, host
+float format.
+
+Defines and information needed to handle the target format are target
+dependent.  Examples are the stack frame format, instruction set,
+breakpoint instruction, registers, and how to set up and tear down the stack
+to call a function.
+
+Information that is only needed when the host and target are the same,
+is native dependent.  One example is Unix child process support; if the
+host and target are not the same, doing a fork to start the target
+process is a bad idea.  The various macros needed for finding the
+registers in the @code{upage}, running @code{ptrace}, and such are all
+in the native-dependent files.
+
+Another example of native-dependent code is support for features that
+are really part of the target environment, but which require
+@code{#include} files that are only available on the host system.  Core
+file handling and @code{setjmp} handling are two common cases.
+
+When you want to make GDB work ``native'' on a particular machine, you
+have to include all three kinds of information.
+
+
+@node Algorithms
+
+@chapter Algorithms
+
+GDB uses a number of debugging-specific algorithms.  They are often not
+very complicated, but get lost in the thicket of special cases and
+real-world issues.  This chapter describes the basic algorithms and
+mentions some of the specific target definitions that they use.
+
+@section Frames
+
+A frame is a construct that GDB uses to keep track of calling and called
+functions.
+
+@code{FRAME_FP} in the machine description has no meaning to the
+machine-independent part of GDB, except that it is used when setting up
+a new frame from scratch, as follows:
+
+@example
+      create_new_frame (read_register (FP_REGNUM), read_pc ()));
+@end example
+
+Other than that, all the meaning imparted to @code{FP_REGNUM} is
+imparted by the machine-dependent code.  So, @code{FP_REGNUM} can have
+any value that is convenient for the code that creates new frames.
+(@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is
+defined; that is where you should use the @code{FP_REGNUM} value, if
+your frames are nonstandard.)
+
+Given a GDB frame, define @code{FRAME_CHAIN} to determine the address of
+the calling function's frame.  This will be used to create a new GDB
+frame struct, and then @code{INIT_EXTRA_FRAME_INFO} and
+@code{INIT_FRAME_PC} will be called for the new frame.
+
+@section Breakpoint Handling
+
+In general, a breakpoint is a user-designated location in the program
+where the user wants to regain control if program execution ever reaches
+that location.
+
+There are two main ways to implement breakpoints; either as ``hardware''
+breakpoints or as ``software'' breakpoints.
+
+Hardware breakpoints are sometimes available as a builtin debugging
+features with some chips.  Typically these work by having dedicated
+register into which the breakpoint address may be stored.  If the PC
+ever matches a value in a breakpoint registers, the CPU raises an
+exception and reports it to GDB.  Another possibility is when an
+emulator is in use; many emulators include circuitry that watches the
+address lines coming out from the processor, and force it to stop if the
+address matches a breakpoint's address.  A third possibility is that the
+target already has the ability to do breakpoints somehow; for instance,
+a ROM monitor may do its own software breakpoints.  So although these
+are not literally ``hardware breakpoints'', from GDB's point of view
+they work the same; GDB need not do nothing more than set the breakpoint
+and wait for something to happen.
+
+Since they depend on hardware resources, hardware breakpoints may be
+limited in number; when the user asks for more, GDB will start trying to
+set software breakpoints.
+
+Software breakpoints require GDB to do somewhat more work.  The basic
+theory is that GDB will replace a program instruction a trap, illegal
+divide, or some other instruction that will cause an exception, and then
+when it's encountered, GDB will take the exception and stop the program.
+When the user says to continue, GDB will restore the original
+instruction, single-step, re-insert the trap, and continue on.
+
+Since it literally overwrites the program being tested, the program area
+must be writeable, so this technique won't work on programs in ROM.  It
+can also distort the behavior of programs that examine themselves,
+although the situation would be highly unusual.
+
+Also, the software breakpoint instruction should be the smallest size of
+instruction, so it doesn't overwrite an instruction that might be a jump
+target, and cause disaster when the program jumps into the middle of the
+breakpoint instruction.  (Strictly speaking, the breakpoint must be no
+larger than the smallest interval between instructions that may be jump
+targets; perhaps there is an architecture where only even-numbered
+instructions may jumped to.)  Note that it's possible for an instruction
+set not to have any instructions usable for a software breakpoint,
+although in practice only the ARC has failed to define such an
+instruction.
+
+The basic definition of the software breakpoint is the macro
+@code{BREAKPOINT}.
+
+Basic breakpoint object handling is in @file{breakpoint.c}.  However,
+much of the interesting breakpoint action is in @file{infrun.c}.
+
+@section Single Stepping
+
+@section Signal Handling
+
+@section Thread Handling
+
+@section Inferior Function Calls
+
+@section Longjmp Support
+
+GDB has support for figuring out that the target is doing a
+@code{longjmp} and for stopping at the target of the jump, if we are
+stepping.  This is done with a few specialized internal breakpoints,
+which are visible in the @code{maint info breakpoint} command.
+
+To make this work, you need to define a macro called
+@code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf}
+structure and extract the longjmp target address.  Since @code{jmp_buf}
+is target specific, you will need to define it in the appropriate
+@file{tm-@var{xyz}.h} file.  Look in @file{tm-sun4os4.h} and
+@file{sparc-tdep.c} for examples of how to do this.
+
+@node User Interface
+
+@chapter User Interface
+
+GDB has several user interfaces.  Although the command-line interface
+is the most common and most familiar, there are others.
+
+@section Command Interpreter
+
+The command interpreter in GDB is fairly simple.  It is designed to
+allow for the set of commands to be augmented dynamically, and also
+has a recursive subcommand capability, where the first argument to
+a command may itself direct a lookup on a different command list.
+
+For instance, the @code{set} command just starts a lookup on the
+@code{setlist} command list, while @code{set thread} recurses
+to the @code{set_thread_cmd_list}.
+
+To add commands in general, use @code{add_cmd}.  @code{add_com} adds to
+the main command list, and should be used for those commands.  The usual
+place to add commands is in the @code{_initialize_@var{xyz}} routines at the
+ends of most source files.
+
+@section Console Printing
+
+@section TUI
+
+@section libgdb
+
+@code{libgdb} was an abortive project of years ago.  The theory was to
+provide an API to GDB's functionality.
+
+@node Symbol Handling
+
+@chapter Symbol Handling
+
+Symbols are a key part of GDB's operation.  Symbols include variables,
+functions, and types.
+
+@section Symbol Reading
+
+GDB reads symbols from ``symbol files''.  The usual symbol file is the
+file containing the program which GDB is debugging.  GDB can be directed
+to use a different file for symbols (with the @code{symbol-file}
+command), and it can also read more symbols via the ``add-file'' and
+``load'' commands, or while reading symbols from shared libraries.
+
+Symbol files are initially opened by code in @file{symfile.c} using the
+BFD library.  BFD identifies the type of the file by examining its
+header.  @code{symfile_init} then uses this identification to locate a
+set of symbol-reading functions.
+
+Symbol reading modules identify themselves to GDB by calling
+@code{add_symtab_fns} during their module initialization.  The argument
+to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
+name (or name prefix) of the symbol format, the length of the prefix,
+and pointers to four functions.  These functions are called at various
+times to process symbol-files whose identification matches the specified
+prefix.
+
+The functions supplied by each module are:
+
+@table @code
+@item @var{xyz}_symfile_init(struct sym_fns *sf)
+
+Called from @code{symbol_file_add} when we are about to read a new
+symbol file.  This function should clean up any internal state (possibly
+resulting from half-read previous files, for example) and prepare to
+read a new symbol file. Note that the symbol file which we are reading
+might be a new "main" symbol file, or might be a secondary symbol file
+whose symbols are being added to the existing symbol table.
+
+The argument to @code{@var{xyz}_symfile_init} is a newly allocated
+@code{struct sym_fns} whose @code{bfd} field contains the BFD for the
+new symbol file being read.  Its @code{private} field has been zeroed,
+and can be modified as desired.  Typically, a struct of private
+information will be @code{malloc}'d, and a pointer to it will be placed
+in the @code{private} field.
+
+There is no result from @code{@var{xyz}_symfile_init}, but it can call
+@code{error} if it detects an unavoidable problem.
+
+@item @var{xyz}_new_init()
+
+Called from @code{symbol_file_add} when discarding existing symbols.
+This function need only handle the symbol-reading module's internal
+state; the symbol table data structures visible to the rest of GDB will
+be discarded by @code{symbol_file_add}.  It has no arguments and no
+result.  It may be called after @code{@var{xyz}_symfile_init}, if a new
+symbol table is being read, or may be called alone if all symbols are
+simply being discarded.
+
+@item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
+
+Called from @code{symbol_file_add} to actually read the symbols from a
+symbol-file into a set of psymtabs or symtabs.
+
+@code{sf} points to the struct sym_fns originally passed to
+@code{@var{xyz}_sym_init} for possible initialization.  @code{addr} is
+the offset between the file's specified start address and its true
+address in memory.  @code{mainline} is 1 if this is the main symbol
+table being read, and 0 if a secondary symbol file (e.g. shared library
+or dynamically loaded file) is being read.@refill
+@end table
+
+In addition, if a symbol-reading module creates psymtabs when
+@var{xyz}_symfile_read is called, these psymtabs will contain a pointer
+to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
+from any point in the GDB symbol-handling code.
+
+@table @code
+@item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)
+
+Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB macro) if
+the psymtab has not already been read in and had its @code{pst->symtab}
+pointer set.  The argument is the psymtab to be fleshed-out into a
+symtab.  Upon return, pst->readin should have been set to 1, and
+pst->symtab should contain a pointer to the new corresponding symtab, or
+zero if there were no symbols in that part of the symbol file.
+@end table
+
+@section Partial Symbol Tables
+
+GDB has three types of symbol tables.
+
+@itemize @bullet
+
+@item full symbol tables (symtabs).  These contain the main information
+about symbols and addresses.
+
+@item partial symbol tables (psymtabs).  These contain enough
+information to know when to read the corresponding part of the full
+symbol table.
+
+@item minimal symbol tables (msymtabs).  These contain information
+gleaned from non-debugging symbols.
+
+@end itemize
+
+This section describes partial symbol tables.
+
+A psymtab is constructed by doing a very quick pass over an executable
+file's debugging information.  Small amounts of information are
+extracted -- enough to identify which parts of the symbol table will
+need to be re-read and fully digested later, when the user needs the
+information.  The speed of this pass causes GDB to start up very
+quickly.  Later, as the detailed rereading occurs, it occurs in small
+pieces, at various times, and the delay therefrom is mostly invisible to
+the user.
+@c (@xref{Symbol Reading}.)
+
+The symbols that show up in a file's psymtab should be, roughly, those
+visible to the debugger's user when the program is not running code from
+that file.  These include external symbols and types, static symbols and
+types, and enum values declared at file scope.
+
+The psymtab also contains the range of instruction addresses that the
+full symbol table would represent.
+
+The idea is that there are only two ways for the user (or much of the
+code in the debugger) to reference a symbol:
+
+@itemize @bullet
+
+@item by its address
+(e.g. execution stops at some address which is inside a function in this
+file).  The address will be noticed to be in the range of this psymtab,
+and the full symtab will be read in.  @code{find_pc_function},
+@code{find_pc_line}, and other @code{find_pc_@dots{}} functions handle
+this.
+
+@item by its name
+(e.g. the user asks to print a variable, or set a breakpoint on a
+function).  Global names and file-scope names will be found in the
+psymtab, which will cause the symtab to be pulled in.  Local names will
+have to be qualified by a global name, or a file-scope name, in which
+case we will have already read in the symtab as we evaluated the
+qualifier.  Or, a local symbol can be referenced when we are "in" a
+local scope, in which case the first case applies.  @code{lookup_symbol}
+does most of the work here.
+
+@end itemize
+
+The only reason that psymtabs exist is to cause a symtab to be read in
+at the right moment.  Any symbol that can be elided from a psymtab,
+while still causing that to happen, should not appear in it.  Since
+psymtabs don't have the idea of scope, you can't put local symbols in
+them anyway.  Psymtabs don't have the idea of the type of a symbol,
+either, so types need not appear, unless they will be referenced by
+name.
+
+It is a bug for GDB to behave one way when only a psymtab has been read,
+and another way if the corresponding symtab has been read in.  Such bugs
+are typically caused by a psymtab that does not contain all the visible
+symbols, or which has the wrong instruction address ranges.
+
+The psymtab for a particular section of a symbol-file (objfile) could be
+thrown away after the symtab has been read in.  The symtab should always
+be searched before the psymtab, so the psymtab will never be used (in a
+bug-free environment).  Currently, psymtabs are allocated on an obstack,
+and all the psymbols themselves are allocated in a pair of large arrays
+on an obstack, so there is little to be gained by trying to free them
+unless you want to do a lot more work.
+
+@section Types
+
+Fundamental Types (e.g., FT_VOID, FT_BOOLEAN).
+
+These are the fundamental types that GDB uses internally.  Fundamental
+types from the various debugging formats (stabs, ELF, etc) are mapped
+into one of these.  They are basically a union of all fundamental types
+that gdb knows about for all the languages that GDB knows about.
+
+Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY).
+
+Each time GDB builds an internal type, it marks it with one of these
+types.  The type may be a fundamental type, such as TYPE_CODE_INT, or a
+derived type, such as TYPE_CODE_PTR which is a pointer to another type.
+Typically, several FT_* types map to one TYPE_CODE_* type, and are
+distinguished by other members of the type struct, such as whether the
+type is signed or unsigned, and how many bits it uses.
+
+Builtin Types (e.g., builtin_type_void, builtin_type_char).
+
+These are instances of type structs that roughly correspond to
+fundamental types and are created as global types for GDB to use for
+various ugly historical reasons.  We eventually want to eliminate these.
+Note for example that builtin_type_int initialized in gdbtypes.c is
+basically the same as a TYPE_CODE_INT type that is initialized in
+c-lang.c for an FT_INTEGER fundamental type.  The difference is that the
+builtin_type is not associated with any particular objfile, and only one
+instance exists, while c-lang.c builds as many TYPE_CODE_INT types as
+needed, with each one associated with some particular objfile.
+
+@section Object File Formats
+
+@subsection a.out
+
+The @file{a.out} format is the original file format for Unix.  It
+consists of three sections: text, data, and bss, which are for program
+code, initialized data, and uninitialized data, respectively.
+
+The @file{a.out} format is so simple that it doesn't have any reserved
+place for debugging information.  (Hey, the original Unix hackers used
+@file{adb}, which is a machine-language debugger.)  The only debugging
+format for @file{a.out} is stabs, which is encoded as a set of normal
+symbols with distinctive attributes.
+
+The basic @file{a.out} reader is in @file{dbxread.c}.
+
+@subsection COFF
+
+The COFF format was introduced with System V Release 3 (SVR3) Unix.
+COFF files may have multiple sections, each prefixed by a header.  The
+number of sections is limited.
+
+The COFF specification includes support for debugging.  Although this
+was a step forward, the debugging information was woefully limited.  For
+instance, it was not possible to represent code that came from an
+included file.
+
+The COFF reader is in @file{coffread.c}.
+
+@subsection ECOFF
+
+ECOFF is an extended COFF originally introduced for Mips and Alpha
+workstations.
+
+The basic ECOFF reader is in @file{mipsread.c}.
+
+@subsection XCOFF
+
+The IBM RS/6000 running AIX uses an object file format called XCOFF.
+The COFF sections, symbols, and line numbers are used, but debugging
+symbols are dbx-style stabs whose strings are located in the
+@samp{.debug} section (rather than the string table).  For more
+information, see @xref{Top,,,stabs,The Stabs Debugging Format}.
+
+The shared library scheme has a clean interface for figuring out what
+shared libraries are in use, but the catch is that everything which
+refers to addresses (symbol tables and breakpoints at least) needs to be
+relocated for both shared libraries and the main executable.  At least
+using the standard mechanism this can only be done once the program has
+been run (or the core file has been read).
+
+@subsection PE
+
+Windows 95 and NT use the PE (Portable Executable) format for their
+executables.  PE is basically COFF with additional headers.
+
+While BFD includes special PE support, GDB needs only the basic
+COFF reader.
+
+@subsection ELF
+
+The ELF format came with System V Release 4 (SVR4) Unix.  ELF is similar
+to COFF in being organized into a number of sections, but it removes
+many of COFF's limitations.
+
+The basic ELF reader is in @file{elfread.c}.
+
+@subsection SOM
+
+SOM is HP's object file and debug format (not to be confused with IBM's
+SOM, which is a cross-language ABI).
+
+The SOM reader is in @file{hpread.c}.
+
+@subsection Other File Formats
+
+Other file formats that have been supported by GDB include Netware
+Loadable Modules (@file{nlmread.c}.
+
+@section Debugging File Formats
+
+This section describes characteristics of debugging information that
+are independent of the object file format.
+
+@subsection stabs
+
+@code{stabs} started out as special symbols within the @code{a.out}
+format.  Since then, it has been encapsulated into other file
+formats, such as COFF and ELF.
+
+While @file{dbxread.c} does some of the basic stab processing,
+including for encapsulated versions, @file{stabsread.c} does
+the real work.
+
+@subsection COFF
+
+The basic COFF definition includes debugging information.  The level
+of support is minimal and non-extensible, and is not often used.
+
+@subsection Mips debug (Third Eye)
+
+ECOFF includes a definition of a special debug format.
+
+The file @file{mdebugread.c} implements reading for this format.
+
+@subsection DWARF 1
+
+DWARF 1 is a debugging format that was originally designed to be
+used with ELF in SVR4 systems.
+
+@c CHILL_PRODUCER
+@c GCC_PRODUCER
+@c GPLUS_PRODUCER
+@c LCC_PRODUCER
+@c If defined, these are the producer strings in a DWARF 1 file.  All of
+@c these have reasonable defaults already.
+
+The DWARF 1 reader is in @file{dwarfread.c}.
+
+@subsection DWARF 2
+
+DWARF 2 is an improved but incompatible version of DWARF 1.
+
+The DWARF 2 reader is in @file{dwarf2read.c}.
+
+@subsection SOM
+
+Like COFF, the SOM definition includes debugging information.
+
+@section Adding a New Symbol Reader to GDB
+
+If you are using an existing object file format (a.out, COFF, ELF, etc),
+there is probably little to be done.
+
+If you need to add a new object file format, you must first add it to
+BFD.  This is beyond the scope of this document.
+
+You must then arrange for the BFD code to provide access to the
+debugging symbols.  Generally GDB will have to call swapping routines
+from BFD and a few other BFD internal routines to locate the debugging
+information.  As much as possible, GDB should not depend on the BFD
+internal data structures.
+
+For some targets (e.g., COFF), there is a special transfer vector used
+to call swapping routines, since the external data structures on various
+platforms have different sizes and layouts.  Specialized routines that
+will only ever be implemented by one object file format may be called
+directly.  This interface should be described in a file
+@file{bfd/libxyz.h}, which is included by GDB.
+
+
+@node Language Support
+
+@chapter Language Support
+
+GDB's language support is mainly driven by the symbol reader, although
+it is possible for the user to set the source language manually.
+
+GDB chooses the source language by looking at the extension of the file
+recorded in the debug info; @code{.c} means C, @code{.f} means Fortran,
+etc.  It may also use a special-purpose language identifier if the debug
+format supports it, such as DWARF.
+
+@section Adding a Source Language to GDB
+
+To add other languages to GDB's expression parser, follow the following
+steps:
+
+@table @emph
+@item Create the expression parser.
+
+This should reside in a file @file{@var{lang}-exp.y}.  Routines for
+building parsed expressions into a @samp{union exp_element} list are in
+@file{parse.c}.
+
+Since we can't depend upon everyone having Bison, and YACC produces
+parsers that define a bunch of global names, the following lines
+@emph{must} be included at the top of the YACC parser, to prevent the
+various parsers from defining the same global names:
+
+@example
+#define yyparse 	@var{lang}_parse
+#define yylex 	@var{lang}_lex
+#define yyerror 	@var{lang}_error
+#define yylval 	@var{lang}_lval
+#define yychar 	@var{lang}_char
+#define yydebug 	@var{lang}_debug
+#define yypact  	@var{lang}_pact 
+#define yyr1		@var{lang}_r1   
+#define yyr2		@var{lang}_r2   
+#define yydef		@var{lang}_def  
+#define yychk		@var{lang}_chk  
+#define yypgo		@var{lang}_pgo  
+#define yyact  	@var{lang}_act  
+#define yyexca  	@var{lang}_exca
+#define yyerrflag  	@var{lang}_errflag
+#define yynerrs  	@var{lang}_nerrs
+@end example
+
+At the bottom of your parser, define a @code{struct language_defn} and
+initialize it with the right values for your language.  Define an
+@code{initialize_@var{lang}} routine and have it call
+@samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB
+that your language exists.  You'll need some other supporting variables
+and functions, which will be used via pointers from your
+@code{@var{lang}_language_defn}.  See the declaration of @code{struct
+language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
+for more information.
+
+@item Add any evaluation routines, if necessary
+
+If you need new opcodes (that represent the operations of the language),
+add them to the enumerated type in @file{expression.h}.  Add support
+code for these operations in @code{eval.c:evaluate_subexp()}.  Add cases
+for new opcodes in two functions from @file{parse.c}:
+@code{prefixify_subexp()} and @code{length_of_subexp()}.  These compute
+the number of @code{exp_element}s that a given operation takes up.
+
+@item Update some existing code
+
+Add an enumerated identifier for your language to the enumerated type
+@code{enum language} in @file{defs.h}.
+
+Update the routines in @file{language.c} so your language is included.
+These routines include type predicates and such, which (in some cases)
+are language dependent.  If your language does not appear in the switch
+statement, an error is reported.
+
+Also included in @file{language.c} is the code that updates the variable
+@code{current_language}, and the routines that translate the
+@code{language_@var{lang}} enumerated identifier into a printable
+string.
+
+Update the function @code{_initialize_language} to include your
+language.  This function picks the default language upon startup, so is
+dependent upon which languages that GDB is built for.
+
+Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
+code so that the language of each symtab (source file) is set properly.
+This is used to determine the language to use at each stack frame level.
+Currently, the language is set based upon the extension of the source
+file.  If the language can be better inferred from the symbol
+information, please set the language of the symtab in the symbol-reading
+code.
+
+Add helper code to @code{expprint.c:print_subexp()} to handle any new
+expression opcodes you have added to @file{expression.h}.  Also, add the
+printed representations of your operators to @code{op_print_tab}.
+
+@item Add a place of call
+
+Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
+@code{parse.c:parse_exp_1()}.
+
+@item Use macros to trim code
+
+The user has the option of building GDB for some or all of the
+languages.  If the user decides to build GDB for the language
+@var{lang}, then every file dependent on @file{language.h} will have the
+macro @code{_LANG_@var{lang}} defined in it.  Use @code{#ifdef}s to
+leave out large routines that the user won't need if he or she is not
+using your language.
+
+Note that you do not need to do this in your YACC parser, since if GDB
+is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
+compiled form of your parser) is not linked into GDB at all.
+
+See the file @file{configure.in} for how GDB is configured for different
+languages.
+
+@item Edit @file{Makefile.in}
+
+Add dependencies in @file{Makefile.in}.  Make sure you update the macro
+variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
+not get linked in, or, worse yet, it may not get @code{tar}red into the
+distribution!
+
+@end table
+
+
+@node Host Definition
+
+@chapter Host Definition
+
+With the advent of autoconf, it's rarely necessary to have host
+definition machinery anymore.
+
+@section Adding a New Host
+
+Most of GDB's host configuration support happens via autoconf.  It
+should be rare to need new host-specific definitions.  GDB still uses
+the host-specific definitions and files listed below, but these mostly
+exist for historical reasons, and should eventually disappear.
+
+Several files control GDB's configuration for host systems:
+
+@table @file
+
+@item gdb/config/@var{arch}/@var{xyz}.mh
+Specifies Makefile fragments needed when hosting on machine @var{xyz}.
+In particular, this lists the required machine-dependent object files,
+by defining @samp{XDEPFILES=@dots{}}.  Also specifies the header file
+which describes host @var{xyz}, by defining @code{XM_FILE=
+xm-@var{xyz}.h}.  You can also define @code{CC}, @code{SYSV_DEFINE},
+@code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS},
+etc.; see @file{Makefile.in}.
+
+@item gdb/config/@var{arch}/xm-@var{xyz}.h
+(@file{xm.h} is a link to this file, created by configure).  Contains C
+macro definitions describing the host system environment, such as byte
+order, host C compiler and library.
+
+@item gdb/@var{xyz}-xdep.c
+Contains any miscellaneous C code required for this machine as a host.
+On most machines it doesn't exist at all.  If it does exist, put
+@file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in
+@file{gdb/config/@var{arch}/@var{xyz}.mh}.
+
+@end table
+
+@subheading Generic Host Support Files
+
+There are some ``generic'' versions of routines that can be used by
+various systems.  These can be customized in various ways by macros
+defined in your @file{xm-@var{xyz}.h} file.  If these routines work for
+the @var{xyz} host, you can just include the generic file's name (with
+@samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
+
+Otherwise, if your machine needs custom support routines, you will need
+to write routines that perform the same functions as the generic file.
+Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
+into @code{XDEPFILES}.
+
+@table @file
+
+@item ser-unix.c
+This contains serial line support for Unix systems.  This is always
+included, via the makefile variable @code{SER_HARDWIRE}; override this
+variable in the @file{.mh} file to avoid it.
+
+@item ser-go32.c
+This contains serial line support for 32-bit programs running under DOS,
+using the GO32 execution environment.
+
+@item ser-tcp.c
+This contains generic TCP support using sockets.
+
+@end table
+
+@section Host Conditionals
+
+When GDB is configured and compiled, various macros are defined or left
+undefined, to control compilation based on the attributes of the host
+system.  These macros and their meanings (or if the meaning is not
+documented here, then one of the source files where they are used is
+indicated) are:
+
+@table @code
+
+@item GDBINIT_FILENAME
+The default name of GDB's initialization file (normally @file{.gdbinit}).
+
+@item MEM_FNS_DECLARED
+Your host config file defines this if it includes declarations of
+@code{memcpy} and @code{memset}.  Define this to avoid conflicts between
+the native include files and the declarations in @file{defs.h}.
+
+@item NO_SYS_FILE
+Define this if your system does not have a @code{<sys/file.h>}.
+
+@item SIGWINCH_HANDLER
+If your host defines @code{SIGWINCH}, you can define this to be the name
+of a function to be called if @code{SIGWINCH} is received.
+
+@item SIGWINCH_HANDLER_BODY
+Define this to expand into code that will define the function named by
+the expansion of @code{SIGWINCH_HANDLER}.
+
+@item ALIGN_STACK_ON_STARTUP
+Define this if your system is of a sort that will crash in
+@code{tgetent} if the stack happens not to be longword-aligned when
+@code{main} is called.  This is a rare situation, but is known to occur
+on several different types of systems.
+
+@item CRLF_SOURCE_FILES
+Define this if host files use @code{\r\n} rather than @code{\n} as a
+line terminator.  This will cause source file listings to omit @code{\r}
+characters when printing and it will allow \r\n line endings of files
+which are "sourced" by gdb.  It must be possible to open files in binary
+mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
+
+@item DEFAULT_PROMPT
+The default value of the prompt string (normally @code{"(gdb) "}).
+
+@item DEV_TTY
+The name of the generic TTY device, defaults to @code{"/dev/tty"}.
+
+@item FCLOSE_PROVIDED
+Define this if the system declares @code{fclose} in the headers included
+in @code{defs.h}.  This isn't needed unless your compiler is unusually
+anal.
+
+@item FOPEN_RB
+Define this if binary files are opened the same way as text files.
+
+@item GETENV_PROVIDED
+Define this if the system declares @code{getenv} in its headers included
+in @code{defs.h}. This isn't needed unless your compiler is unusually
+anal.
+
+@item HAVE_MMAP
+In some cases, use the system call @code{mmap} for reading symbol
+tables.  For some machines this allows for sharing and quick updates.
+
+@item HAVE_SIGSETMASK
+Define this if the host system has job control, but does not define
+@code{sigsetmask()}.  Currently, this is only true of the RS/6000.
+
+@item HAVE_TERMIO
+Define this if the host system has @code{termio.h}.
+
+@item HOST_BYTE_ORDER
+The ordering of bytes in the host.  This must be defined to be either
+@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.
+
+@item INT_MAX
+@item INT_MIN
+@item LONG_MAX
+@item UINT_MAX
+@item ULONG_MAX
+Values for host-side constants.
+
+@item ISATTY
+Substitute for isatty, if not available.
+
+@item LONGEST
+This is the longest integer type available on the host.  If not defined,
+it will default to @code{long long} or @code{long}, depending on
+@code{CC_HAS_LONG_LONG}.
+
+@item CC_HAS_LONG_LONG
+Define this if the host C compiler supports ``long long''.  This is set
+by the configure script.
+
+@item PRINTF_HAS_LONG_LONG
+Define this if the host can handle printing of long long integers via
+the printf format directive ``ll''. This is set by the configure script.
+
+@item HAVE_LONG_DOUBLE
+Define this if the host C compiler supports ``long double''.  This is
+set by the configure script.
+
+@item PRINTF_HAS_LONG_DOUBLE
+Define this if the host can handle printing of long double float-point
+numbers via the printf format directive ``Lg''. This is set by the
+configure script.
+
+@item SCANF_HAS_LONG_DOUBLE
+Define this if the host can handle the parsing of long double
+float-point numbers via the scanf format directive directive
+``Lg''. This is set by the configure script.
+
+@item LSEEK_NOT_LINEAR
+Define this if @code{lseek (n)} does not necessarily move to byte number
+@code{n} in the file.  This is only used when reading source files.  It
+is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
+
+@item L_SET
+This macro is used as the argument to lseek (or, most commonly,
+bfd_seek).  FIXME, should be replaced by SEEK_SET instead, which is the
+POSIX equivalent.
+
+@item MAINTENANCE_CMDS
+If the value of this is 1, then a number of optional maintenance
+commands are compiled in.
+
+@item MALLOC_INCOMPATIBLE
+Define this if the system's prototype for @code{malloc} differs from the
+@sc{ANSI} definition.
+
+@item MMAP_BASE_ADDRESS
+When using HAVE_MMAP, the first mapping should go at this address.
+
+@item MMAP_INCREMENT
+when using HAVE_MMAP, this is the increment between mappings.
+
+@item NEED_POSIX_SETPGID
+Define this to use the POSIX version of @code{setpgid} to determine
+whether job control is available.
+
+@item NORETURN
+If defined, this should be one or more tokens, such as @code{volatile},
+that can be used in both the declaration and definition of functions to
+indicate that they never return.  The default is already set correctly
+if compiling with GCC.  This will almost never need to be defined.
+
+@item ATTR_NORETURN
+If defined, this should be one or more tokens, such as
+@code{__attribute__ ((noreturn))}, that can be used in the declarations
+of functions to indicate that they never return.  The default is already
+set correctly if compiling with GCC.  This will almost never need to be
+defined.
+
+@item USE_MMALLOC
+GDB will use the @code{mmalloc} library for memory allocation for symbol
+reading if this symbol is defined.  Be careful defining it since there
+are systems on which @code{mmalloc} does not work for some reason.  One
+example is the DECstation, where its RPC library can't cope with our
+redefinition of @code{malloc} to call @code{mmalloc}.  When defining
+@code{USE_MMALLOC}, you will also have to set @code{MMALLOC} in the
+Makefile, to point to the mmalloc library.  This define is set when you
+configure with --with-mmalloc.
+
+@item NO_MMCHECK
+Define this if you are using @code{mmalloc}, but don't want the overhead
+of checking the heap with @code{mmcheck}.  Note that on some systems,
+the C runtime makes calls to malloc prior to calling @code{main}, and if
+@code{free} is ever called with these pointers after calling
+@code{mmcheck} to enable checking, a memory corruption abort is certain
+to occur.  These systems can still use mmalloc, but must define
+NO_MMCHECK.
+
+@item MMCHECK_FORCE
+Define this to 1 if the C runtime allocates memory prior to
+@code{mmcheck} being called, but that memory is never freed so we don't
+have to worry about it triggering a memory corruption abort.  The
+default is 0, which means that @code{mmcheck} will only install the heap
+checking functions if there has not yet been any memory allocation
+calls, and if it fails to install the functions, gdb will issue a
+warning.  This is currently defined if you configure using
+--with-mmalloc.
+
+@item NO_SIGINTERRUPT
+Define this to indicate that siginterrupt() is not available.
+
+@item R_OK
+Define if this is not in a system .h file.
+
+@item SEEK_CUR
+@item SEEK_SET
+Define these to appropriate value for the system lseek(), if not already
+defined.
+
+@item STOP_SIGNAL
+This is the signal for stopping GDB.  Defaults to SIGTSTP.  (Only
+redefined for the Convex.)
+
+@item USE_O_NOCTTY
+Define this if the interior's tty should be opened with the O_NOCTTY
+flag.  (FIXME: This should be a native-only flag, but @file{inflow.c} is
+always linked in.)
+
+@item USG
+Means that System V (prior to SVR4) include files are in use.  (FIXME:
+This symbol is abused in @file{infrun.c}, @file{regex.c},
+@file{remote-nindy.c}, and @file{utils.c} for other things, at the
+moment.)
+
+@item lint
+Define this to help placate lint in some situations.
+
+@item volatile
+Define this to override the defaults of @code{__volatile__} or
+@code{/**/}.
+
+@end table
+
+
+@node Target Architecture Definition
+
+@chapter Target Architecture Definition
+
+GDB's target architecture defines what sort of machine-language programs
+GDB can work with, and how it works with them.
+
+At present, the target architecture definition consists of a number of C
+macros.
+
+@section Registers and Memory
+
+GDB's model of the target machine is rather simple.  GDB assumes the
+machine includes a bank of registers and a block of memory.  Each
+register may have a different size.
+
+GDB does not have a magical way to match up with the compiler's idea of
+which registers are which; however, it is critical that they do match up
+accurately.  The only way to make this work is to get accurate
+information about the order that the compiler uses, and to reflect that
+in the @code{REGISTER_NAME} and related macros.
+
+GDB can handle big-endian, little-endian, and bi-endian architectures.
+
+@section Frame Interpretation
+
+@section Inferior Call Setup
+
+@section Compiler Characteristics
+
+@section Target Conditionals
+
+This section describes the macros that you can use to define the target
+machine.
+
+@table @code
+
+@item ADDITIONAL_OPTIONS
+@item ADDITIONAL_OPTION_CASES
+@item ADDITIONAL_OPTION_HANDLER
+@item ADDITIONAL_OPTION_HELP
+These are a set of macros that allow the addition of additional command
+line options to GDB.  They are currently used only for the unsupported
+i960 Nindy target, and should not be used in any other configuration.
+
+@item ADDR_BITS_REMOVE (addr)
+If a raw machine address includes any bits that are not really part of
+the address, then define this macro to expand into an expression that
+zeros those bits in @var{addr}.  For example, the two low-order bits of
+a Motorola 88K address may be used by some kernels for their own
+purposes, since addresses must always be 4-byte aligned, and so are of
+no use for addressing.  Those bits should be filtered out with an
+expression such as @code{((addr) & ~3)}.
+
+@item BEFORE_MAIN_LOOP_HOOK
+Define this to expand into any code that you want to execute before the
+main loop starts.  Although this is not, strictly speaking, a target
+conditional, that is how it is currently being used.  Note that if a
+configuration were to define it one way for a host and a different way
+for the target, GDB will probably not compile, let alone run correctly.
+This is currently used only for the unsupported i960 Nindy target, and
+should not be used in any other configuration.
+
+@item BELIEVE_PCC_PROMOTION
+Define if the compiler promotes a short or char parameter to an int, but
+still reports the parameter as its original type, rather than the
+promoted type.
+
+@item BELIEVE_PCC_PROMOTION_TYPE
+Define this if GDB should believe the type of a short argument when
+compiled by pcc, but look within a full int space to get its value.
+Only defined for Sun-3 at present.
+
+@item BITS_BIG_ENDIAN
+Define this if the numbering of bits in the targets does *not* match the
+endianness of the target byte order.  A value of 1 means that the bits
+are numbered in a big-endian order, 0 means little-endian.
+
+@item BREAKPOINT
+This is the character array initializer for the bit pattern to put into
+memory where a breakpoint is set.  Although it's common to use a trap
+instruction for a breakpoint, it's not required; for instance, the bit
+pattern could be an invalid instruction.  The breakpoint must be no
+longer than the shortest instruction of the architecture.
+
+@item BIG_BREAKPOINT
+@item LITTLE_BREAKPOINT
+Similar to BREAKPOINT, but used for bi-endian targets.
+
+@item REMOTE_BREAKPOINT
+@item LITTLE_REMOTE_BREAKPOINT
+@item BIG_REMOTE_BREAKPOINT
+Similar to BREAKPOINT, but used for remote targets.
+
+@item BREAKPOINT_FROM_PC (pcptr, lenptr)
+
+Use the program counter to determine the contents and size of a
+breakpoint instruction.  It returns a pointer to a string of bytes that
+encode a breakpoint instruction, stores the length of the string to
+*lenptr, and adjusts pc (if necessary) to point to the actual memory
+location where the breakpoint should be inserted.
+
+Although it is common to use a trap instruction for a breakpoint, it's
+not required; for instance, the bit pattern could be an invalid
+instruction.  The breakpoint must be no longer than the shortest
+instruction of the architecture.
+
+Replaces all the other BREAKPOINTs.
+
+@item CALL_DUMMY
+valops.c
+@item CALL_DUMMY_LOCATION
+inferior.h
+@item CALL_DUMMY_STACK_ADJUST
+valops.c
+
+@item CANNOT_FETCH_REGISTER (regno)
+A C expression that should be nonzero if @var{regno} cannot be fetched
+from an inferior process.  This is only relevant if
+@code{FETCH_INFERIOR_REGISTERS} is not defined.
+
+@item CANNOT_STORE_REGISTER (regno)
+A C expression that should be nonzero if @var{regno} should not be
+written to the target.  This is often the case for program counters,
+status words, and other special registers.  If this is not defined, GDB
+will assume that all registers may be written.
+
+@item DO_DEFERRED_STORES
+@item CLEAR_DEFERRED_STORES
+Define this to execute any deferred stores of registers into the inferior,
+and to cancel any deferred stores.
+
+Currently only implemented correctly for native Sparc configurations?
+
+@item CPLUS_MARKER
+Define this to expand into the character that G++ uses to distinguish
+compiler-generated identifiers from programmer-specified identifiers.
+By default, this expands into @code{'$'}.  Most System V targets should
+define this to @code{'.'}.
+
+@item DBX_PARM_SYMBOL_CLASS
+Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol
+information.  In the i960, parameters can be stored as locals or as
+args, depending on the type of the debug record.
+
+@item DECR_PC_AFTER_BREAK
+Define this to be the amount by which to decrement the PC after the
+program encounters a breakpoint.  This is often the number of bytes in
+BREAKPOINT, though not always.  For most targets this value will be 0.
+
+@item DECR_PC_AFTER_HW_BREAK
+Similarly, for hardware breakpoints.
+
+@item DISABLE_UNSETTABLE_BREAK addr
+If defined, this should evaluate to 1 if @var{addr} is in a shared
+library in which breakpoints cannot be set and so should be disabled.
+
+@item DO_REGISTERS_INFO
+If defined, use this to print the value of a register or all registers.
+
+@item END_OF_TEXT_DEFAULT
+This is an expression that should designate the end of the text section
+(? FIXME ?)
+
+@item EXTRACT_RETURN_VALUE(type,regbuf,valbuf)
+Define this to extract a function's return value of type @var{type} from
+the raw register state @var{regbuf} and copy that, in virtual format,
+into @var{valbuf}.
+ 
+@item EXTRACT_STRUCT_VALUE_ADDRESS(regbuf)
+Define this to extract from an array @var{regbuf} containing the (raw)
+register state, the address in which a function should return its
+structure value, as a CORE_ADDR (or an expression that can be used as
+one).
+
+@item FLOAT_INFO
+If defined, then the `info float' command will print information about
+the processor's floating point unit.
+
+@item FP_REGNUM
+The number of the frame pointer register.
+
+@item FRAMELESS_FUNCTION_INVOCATION(fi, frameless)
+Define this to set the variable @var{frameless} to 1 if the function
+invocation represented by @var{fi} does not have a stack frame
+associated with it.  Otherwise set it to 0.
+
+@item FRAME_ARGS_ADDRESS_CORRECT
+stack.c
+
+@item FRAME_CHAIN(frame)
+Given @var{frame}, return a pointer to the calling frame.
+
+@item FRAME_CHAIN_COMBINE(chain,frame)
+Define this to take the frame chain pointer and the frame's nominal
+address and produce the nominal address of the caller's frame.
+Presently only defined for HP PA.
+
+@item FRAME_CHAIN_VALID(chain,thisframe)
+
+Define this to be an expression that returns zero if the given frame is
+an outermost frame, with no caller, and nonzero otherwise.  Three common
+definitions are available. @code{default_frame_chain_valid} (the
+default) is nonzero if the chain pointer is nonzero and given frame's PC
+is not inside the startup file (such as @file{crt0.o}).
+@code{alternate_frame_chain_valid} is nonzero if the chain pointer is
+nonzero and the given frame's PC is not in @code{main()} or a known
+entry point function (such as @code{_start()}).
+
+@item FRAME_INIT_SAVED_REGS(frame)
+See @file{frame.h}.  Determines the address of all registers in the
+current stack frame storing each in @code{frame->saved_regs}.  Space for
+@code{frame->saved_regs} shall be allocated by
+@code{FRAME_INIT_SAVED_REGS} using either
+@code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
+
+@var{FRAME_FIND_SAVED_REGS} and @var{EXTRA_FRAME_INFO} are deprecated.
+
+@item FRAME_NUM_ARGS (val, fi)
+For the frame described by @var{fi}, set @var{val} to the number of arguments
+that are being passed.
+
+@item FRAME_SAVED_PC(frame)
+Given @var{frame}, return the pc saved there.  That is, the return
+address.
+
+@item FUNCTION_EPILOGUE_SIZE
+For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
+function end symbol is 0.  For such targets, you must define
+@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
+function's epilogue.
+
+@item GCC_COMPILED_FLAG_SYMBOL
+@item GCC2_COMPILED_FLAG_SYMBOL
+If defined, these are the names of the symbols that GDB will look for to
+detect that GCC compiled the file.  The default symbols are
+@code{gcc_compiled.} and @code{gcc2_compiled.}, respectively. (Currently
+only defined for the Delta 68.)
+
+@item GDB_TARGET_IS_HPPA
+This determines whether horrible kludge code in dbxread.c and
+partial-stab.h is used to mangle multiple-symbol-table files from
+HPPA's.  This should all be ripped out, and a scheme like elfread.c
+used.
+
+@item GDB_TARGET_IS_MACH386
+@item GDB_TARGET_IS_SUN3
+@item GDB_TARGET_IS_SUN386
+Kludges that should go away.
+
+@item GET_LONGJMP_TARGET
+For most machines, this is a target-dependent parameter.  On the
+DECstation and the Iris, this is a native-dependent parameter, since
+<setjmp.h> is needed to define it.
+
+This macro determines the target PC address that longjmp() will jump to,
+assuming that we have just stopped at a longjmp breakpoint.  It takes a
+CORE_ADDR * as argument, and stores the target PC value through this
+pointer.  It examines the current state of the machine as needed.
+
+@item GET_SAVED_REGISTER
+Define this if you need to supply your own definition for the function
+@code{get_saved_register}.  Currently this is only done for the a29k.
+
+@item HAVE_REGISTER_WINDOWS
+Define this if the target has register windows.
+@item REGISTER_IN_WINDOW_P (regnum)
+Define this to be an expression that is 1 if the given register is in
+the window.
+
+@item IBM6000_TARGET
+Shows that we are configured for an IBM RS/6000 target.  This
+conditional should be eliminated (FIXME) and replaced by
+feature-specific macros.  It was introduced in haste and we are
+repenting at leisure.
+
+@item IEEE_FLOAT
+Define this if the target system uses IEEE-format floating point numbers.
+
+@item INIT_EXTRA_FRAME_INFO (fromleaf, frame)
+If additional information about the frame is required this should be
+stored in @code{frame->extra_info}.  Space for @code{frame->extra_info}
+is allocated using @code{frame_obstack_alloc}.
+
+@item INIT_FRAME_PC (fromleaf, prev)
+This is a C statement that sets the pc of the frame pointed to by
+@var{prev}.  [By default...]
+
+@item INNER_THAN (lhs,rhs)
+Returns non-zero if stack address @var{lhs} is inner than (nearer to the
+stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if
+the target's stack grows downward in memory, or @code{lhs > rsh} if the
+stack grows upward.
+
+@item IN_SIGTRAMP (pc, name)
+Define this to return true if the given @var{pc} and/or @var{name}
+indicates that the current function is a sigtramp.
+
+@item SIGTRAMP_START (pc)
+@item SIGTRAMP_END (pc)
+Define these to be the start and end address of the sigtramp for the
+given @var{pc}.  On machines where the address is just a compile time
+constant, the macro expansion will typically just ignore the supplied
+@var{pc}.
+
+@item IN_SOLIB_CALL_TRAMPOLINE pc name
+Define this to evaluate to nonzero if the program is stopped in the
+trampoline that connects to a shared library.
+
+@item IN_SOLIB_RETURN_TRAMPOLINE pc name
+Define this to evaluate to nonzero if the program is stopped in the
+trampoline that returns from a shared library.
+
+@item IS_TRAPPED_INTERNALVAR (name)
+This is an ugly hook to allow the specification of special actions that
+should occur as a side-effect of setting the value of a variable
+internal to GDB.  Currently only used by the h8500.  Note that this
+could be either a host or target conditional.
+
+@item NEED_TEXT_START_END
+Define this if GDB should determine the start and end addresses of the
+text section.  (Seems dubious.)
+
+@item NO_HIF_SUPPORT
+(Specific to the a29k.)
+
+@item SOFTWARE_SINGLE_STEP_P
+Define this as 1 if the target does not have a hardware single-step
+mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
+
+@item SOFTWARE_SINGLE_STEP(signal,insert_breapoints_p)
+A function that inserts or removes (dependant on
+@var{insert_breapoints_p}) breakpoints at each possible destinations of
+the next instruction. See @code{sparc-tdep.c} and @code{rs6000-tdep.c}
+for examples.
+
+@item PCC_SOL_BROKEN
+(Used only in the Convex target.)
+
+@item PC_IN_CALL_DUMMY
+inferior.h
+
+@item PC_LOAD_SEGMENT
+If defined, print information about the load segment for the program
+counter.  (Defined only for the RS/6000.)
+
+@item PC_REGNUM
+If the program counter is kept in a register, then define this macro to
+be the number of that register.  This need be defined only if
+@code{TARGET_WRITE_PC} is not defined.
+
+@item NPC_REGNUM
+The number of the ``next program counter'' register, if defined.
+
+@item NNPC_REGNUM
+The number of the ``next next program counter'' register, if defined.
+Currently, this is only defined for the Motorola 88K.
+
+@item PRINT_REGISTER_HOOK (regno)
+If defined, this must be a function that prints the contents of the
+given register to standard output.
+
+@item PRINT_TYPELESS_INTEGER
+This is an obscure substitute for @code{print_longest} that seems to
+have been defined for the Convex target.
+
+@item PROCESS_LINENUMBER_HOOK
+A hook defined for XCOFF reading.
+
+@item PROLOGUE_FIRSTLINE_OVERLAP
+(Only used in unsupported Convex configuration.)
+
+@item PS_REGNUM
+If defined, this is the number of the processor status register.  (This
+definition is only used in generic code when parsing "$ps".)
+
+@item POP_FRAME
+Used in @samp{call_function_by_hand} to remove an artificial stack
+frame.
+
+@item PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr)
+Define this to push arguments onto the stack for inferior function call.
+
+@item PUSH_DUMMY_FRAME
+Used in @samp{call_function_by_hand} to create an artificial stack frame.
+
+@item REGISTER_BYTES
+The total amount of space needed to store GDB's copy of the machine's
+register state.
+
+@item REGISTER_NAME(i)
+Return the name of register @var{i} as a string.  May return @var{NULL}
+or @var{NUL} to indicate that register @var{i} is not valid.
+
+@item REG_STRUCT_HAS_ADDR (gcc_p, type)
+Define this to return 1 if the given type will be passed by pointer
+rather than directly.
+
+@item SDB_REG_TO_REGNUM
+Define this to convert sdb register numbers into GDB regnums.  If not
+defined, no conversion will be done.
+
+@item SHIFT_INST_REGS
+(Only used for m88k targets.)
+
+@item SKIP_PROLOGUE (pc)
+A C statement that advances the @var{pc} across any function entry
+prologue instructions so as to reach ``real'' code.
+
+@item SKIP_PROLOGUE_FRAMELESS_P
+A C statement that should behave similarly, but that can stop as soon as
+the function is known to have a frame.  If not defined,
+@code{SKIP_PROLOGUE} will be used instead.
+
+@item SKIP_TRAMPOLINE_CODE (pc)
+If the target machine has trampoline code that sits between callers and
+the functions being called, then define this macro to return a new PC
+that is at the start of the real function.
+
+@item SP_REGNUM
+Define this to be the number of the register that serves as the stack
+pointer.
+
+@item STAB_REG_TO_REGNUM
+Define this to convert stab register numbers (as gotten from `r'
+declarations) into GDB regnums.  If not defined, no conversion will be
+done.
+
+@item STACK_ALIGN (addr)
+Define this to adjust the address to the alignment required for the
+processor's stack.
+
+@item STEP_SKIPS_DELAY (addr)
+Define this to return true if the address is of an instruction with a
+delay slot.  If a breakpoint has been placed in the instruction's delay
+slot, GDB will single-step over that instruction before resuming
+normally.  Currently only defined for the Mips.
+
+@item STORE_RETURN_VALUE (type, valbuf)
+A C expression that stores a function return value of type @var{type},
+where @var{valbuf} is the address of the value to be stored.
+
+@item SUN_FIXED_LBRAC_BUG
+(Used only for Sun-3 and Sun-4 targets.)
+
+@item SYMBOL_RELOADING_DEFAULT
+The default value of the `symbol-reloading' variable.  (Never defined in
+current sources.)
+
+@item TARGET_BYTE_ORDER_DEFAULT
+The ordering of bytes in the target.  This must be either
+@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.  This macro replaces
+@var{TARGET_BYTE_ORDER} which is deprecated.
+
+@item TARGET_BYTE_ORDER_SELECTABLE_P
+Non-zero if the target has both @code{BIG_ENDIAN} and
+@code{LITTLE_ENDIAN} variants.  This macro replaces
+@var{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
+
+@item TARGET_CHAR_BIT
+Number of bits in a char; defaults to 8.
+
+@item TARGET_COMPLEX_BIT
+Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
+
+@item TARGET_DOUBLE_BIT
+Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}.
+
+@item TARGET_DOUBLE_COMPLEX_BIT
+Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}.
+
+@item TARGET_FLOAT_BIT
+Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}.
+
+@item TARGET_INT_BIT
+Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}.
+
+@item TARGET_LONG_BIT
+Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}.
+
+@item TARGET_LONG_DOUBLE_BIT
+Number of bits in a long double float;
+defaults to @code{2 * TARGET_DOUBLE_BIT}.
+
+@item TARGET_LONG_LONG_BIT
+Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}.
+
+@item TARGET_PTR_BIT
+Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}.
+
+@item TARGET_SHORT_BIT
+Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}.
+
+@item TARGET_READ_PC
+@item TARGET_WRITE_PC (val, pid)
+@item TARGET_READ_SP
+@item TARGET_WRITE_SP
+@item TARGET_READ_FP
+@item TARGET_WRITE_FP
+These change the behavior of @code{read_pc}, @code{write_pc},
+@code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}.
+For most targets, these may be left undefined.  GDB will call the read
+and write register functions with the relevant @code{_REGNUM} argument.
+
+These macros are useful when a target keeps one of these registers in a
+hard to get at place; for example, part in a segment register and part
+in an ordinary register.
+
+@item TARGET_VIRTUAL_FRAME_POINTER(pc,regp,offsetp)
+Returns a @code{(register, offset)} pair representing the virtual 
+frame pointer in use at the code address @code{"pc"}.  If virtual 
+frame pointers are not used, a default definition simply returns 
+@code{FP_REGNUM}, with an offset of zero.
+
+@item USE_STRUCT_CONVENTION (gcc_p, type)
+If defined, this must be an expression that is nonzero if a value of the
+given @var{type} being returned from a function must have space
+allocated for it on the stack.  @var{gcc_p} is true if the function
+being considered is known to have been compiled by GCC; this is helpful
+for systems where GCC is known to use different calling convention than
+other compilers.
+
+@item VARIABLES_INSIDE_BLOCK (desc, gcc_p)
+For dbx-style debugging information, if the compiler puts variable
+declarations inside LBRAC/RBRAC blocks, this should be defined to be
+nonzero.  @var{desc} is the value of @code{n_desc} from the
+@code{N_RBRAC} symbol, and @var{gcc_p} is true if GDB has noticed the
+presence of either the @code{GCC_COMPILED_SYMBOL} or the
+@code{GCC2_COMPILED_SYMBOL}.  By default, this is 0.
+
+@item OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p)
+Similarly, for OS/9000.  Defaults to 1.
+
+@end table
+
+Motorola M68K target conditionals.
+
+@table @code
+
+@item BPT_VECTOR
+Define this to be the 4-bit location of the breakpoint trap vector.  If
+not defined, it will default to @code{0xf}.
+
+@item REMOTE_BPT_VECTOR
+Defaults to @code{1}.
+
+@end table
+
+@section Adding a New Target
+
+The following files define a target to GDB:
+
+@table @file
+
+@item gdb/config/@var{arch}/@var{ttt}.mt
+Contains a Makefile fragment specific to this target.  Specifies what
+object files are needed for target @var{ttt}, by defining
+@samp{TDEPFILES=@dots{}}.  Also specifies the header file which
+describes @var{ttt}, by defining @samp{TM_FILE= tm-@var{ttt}.h}.  You
+can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS}, but
+these are now deprecated and may go away in future versions of GDB.
+
+@item gdb/config/@var{arch}/tm-@var{ttt}.h
+(@file{tm.h} is a link to this file, created by configure).  Contains
+macro definitions about the target machine's registers, stack frame
+format and instructions.
+
+@item gdb/@var{ttt}-tdep.c
+Contains any miscellaneous code required for this target machine.  On
+some machines it doesn't exist at all.  Sometimes the macros in
+@file{tm-@var{ttt}.h} become very complicated, so they are implemented
+as functions here instead, and the macro is simply defined to call the
+function.  This is vastly preferable, since it is easier to understand
+and debug.
+
+@item gdb/config/@var{arch}/tm-@var{arch}.h
+This often exists to describe the basic layout of the target machine's
+processor chip (registers, stack, etc).  If used, it is included by
+@file{tm-@var{ttt}.h}.  It can be shared among many targets that use the
+same processor.
+
+@item gdb/@var{arch}-tdep.c
+Similarly, there are often common subroutines that are shared by all
+target machines that use this particular architecture.
+
+@end table
+
+If you are adding a new operating system for an existing CPU chip, add a
+@file{config/tm-@var{os}.h} file that describes the operating system
+facilities that are unusual (extra symbol table info; the breakpoint
+instruction needed; etc).  Then write a @file{@var{arch}/tm-@var{os}.h}
+that just @code{#include}s @file{tm-@var{arch}.h} and
+@file{config/tm-@var{os}.h}.
+
+
+@node Target Vector Definition
+
+@chapter Target Vector Definition
+
+The target vector defines the interface between GDB's abstract handling
+of target systems, and the nitty-gritty code that actually exercises
+control over a process or a serial port.  GDB includes some 30-40
+different target vectors; however, each configuration of GDB includes
+only a few of them.
+
+@section File Targets
+
+Both executables and core files have target vectors.
+
+@section Standard Protocol and Remote Stubs
+
+GDB's file @file{remote.c} talks a serial protocol to code that runs in
+the target system.  GDB provides several sample ``stubs'' that can be
+integrated into target programs or operating systems for this purpose;
+they are named @file{*-stub.c}.
+
+The GDB user's manual describes how to put such a stub into your target
+code.  What follows is a discussion of integrating the SPARC stub into a
+complicated operating system (rather than a simple program), by Stu
+Grossman, the author of this stub.
+
+The trap handling code in the stub assumes the following upon entry to
+trap_low:
+
+@enumerate
+
+@item %l1 and %l2 contain pc and npc respectively at the time of the trap
+
+@item traps are disabled
+
+@item you are in the correct trap window
+
+@end enumerate
+
+As long as your trap handler can guarantee those conditions, then there
+is no reason why you shouldn't be able to `share' traps with the stub.
+The stub has no requirement that it be jumped to directly from the
+hardware trap vector.  That is why it calls @code{exceptionHandler()},
+which is provided by the external environment.  For instance, this could
+setup the hardware traps to actually execute code which calls the stub
+first, and then transfers to its own trap handler.
+
+For the most point, there probably won't be much of an issue with
+`sharing' traps, as the traps we use are usually not used by the kernel,
+and often indicate unrecoverable error conditions.  Anyway, this is all
+controlled by a table, and is trivial to modify.  The most important
+trap for us is for @code{ta 1}.  Without that, we can't single step or
+do breakpoints.  Everything else is unnecessary for the proper operation
+of the debugger/stub.
+
+From reading the stub, it's probably not obvious how breakpoints work.
+They are simply done by deposit/examine operations from GDB.
+
+@section ROM Monitor Interface
+
+@section Custom Protocols
+
+@section Transport Layer
+
+@section Builtin Simulator
+
+
+@node Native Debugging
+
+@chapter Native Debugging
+
+Several files control GDB's configuration for native support:
+
+@table @file
+
+@item gdb/config/@var{arch}/@var{xyz}.mh
+Specifies Makefile fragments needed when hosting @emph{or native} on
+machine @var{xyz}.  In particular, this lists the required
+native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
+Also specifies the header file which describes native support on
+@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}.  You can also
+define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
+@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
+
+@item gdb/config/@var{arch}/nm-@var{xyz}.h
+(@file{nm.h} is a link to this file, created by configure).  Contains C
+macro definitions describing the native system environment, such as
+child process control and core file support.
+
+@item gdb/@var{xyz}-nat.c
+Contains any miscellaneous C code required for this native support of
+this machine.  On some machines it doesn't exist at all.
+
+@end table
+
+There are some ``generic'' versions of routines that can be used by
+various systems.  These can be customized in various ways by macros
+defined in your @file{nm-@var{xyz}.h} file.  If these routines work for
+the @var{xyz} host, you can just include the generic file's name (with
+@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
+
+Otherwise, if your machine needs custom support routines, you will need
+to write routines that perform the same functions as the generic file.
+Put them into @code{@var{xyz}-nat.c}, and put @code{@var{xyz}-nat.o}
+into @code{NATDEPFILES}.
+
+@table @file
+
+@item inftarg.c
+This contains the @emph{target_ops vector} that supports Unix child
+processes on systems which use ptrace and wait to control the child.
+
+@item procfs.c
+This contains the @emph{target_ops vector} that supports Unix child
+processes on systems which use /proc to control the child.
+
+@item fork-child.c
+This does the low-level grunge that uses Unix system calls to do a "fork
+and exec" to start up a child process.
+
+@item infptrace.c
+This is the low level interface to inferior processes for systems using
+the Unix @code{ptrace} call in a vanilla way.
+
+@end table
+
+@section Native core file Support
+
+@table @file
+
+@item core-aout.c::fetch_core_registers()
+Support for reading registers out of a core file.  This routine calls
+@code{register_addr()}, see below.  Now that BFD is used to read core
+files, virtually all machines should use @code{core-aout.c}, and should
+just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
+@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
+
+@item core-aout.c::register_addr()
+If your @code{nm-@var{xyz}.h} file defines the macro
+@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
+set @code{addr} to the offset within the @samp{user} struct of GDB
+register number @code{regno}.  @code{blockend} is the offset within the
+``upage'' of @code{u.u_ar0}.  If @code{REGISTER_U_ADDR} is defined,
+@file{core-aout.c} will define the @code{register_addr()} function and
+use the macro in it.  If you do not define @code{REGISTER_U_ADDR}, but
+you are using the standard @code{fetch_core_registers()}, you will need
+to define your own version of @code{register_addr()}, put it into your
+@code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
+the @code{NATDEPFILES} list.  If you have your own
+@code{fetch_core_registers()}, you may not need a separate
+@code{register_addr()}.  Many custom @code{fetch_core_registers()}
+implementations simply locate the registers themselves.@refill
+
+@end table
+
+When making GDB run native on a new operating system, to make it
+possible to debug core files, you will need to either write specific
+code for parsing your OS's core files, or customize
+@file{bfd/trad-core.c}.  First, use whatever @code{#include} files your
+machine uses to define the struct of registers that is accessible
+(possibly in the u-area) in a core file (rather than
+@file{machine/reg.h}), and an include file that defines whatever header
+exists on a core file (e.g. the u-area or a @samp{struct core}).  Then
+modify @code{trad_unix_core_file_p()} to use these values to set up the
+section information for the data segment, stack segment, any other
+segments in the core file (perhaps shared library contents or control
+information), ``registers'' segment, and if there are two discontiguous
+sets of registers (e.g.  integer and float), the ``reg2'' segment.  This
+section information basically delimits areas in the core file in a
+standard way, which the section-reading routines in BFD know how to seek
+around in.
+
+Then back in GDB, you need a matching routine called
+@code{fetch_core_registers()}.  If you can use the generic one, it's in
+@file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
+It will be passed a char pointer to the entire ``registers'' segment,
+its length, and a zero; or a char pointer to the entire ``regs2''
+segment, its length, and a 2.  The routine should suck out the supplied
+register values and install them into GDB's ``registers'' array.
+
+If your system uses @file{/proc} to control processes, and uses ELF
+format core files, then you may be able to use the same routines for
+reading the registers out of processes and out of core files.
+
+@section ptrace
+
+@section /proc
+
+@section win32
+
+@section shared libraries
+
+@section Native Conditionals
+
+When GDB is configured and compiled, various macros are defined or left
+undefined, to control compilation when the host and target systems are
+the same.  These macros should be defined (or left undefined) in
+@file{nm-@var{system}.h}.
+
+@table @code
+
+@item ATTACH_DETACH
+If defined, then GDB will include support for the @code{attach} and
+@code{detach} commands.
+
+@item CHILD_PREPARE_TO_STORE
+If the machine stores all registers at once in the child process, then
+define this to ensure that all values are correct.  This usually entails
+a read from the child.
+
+[Note that this is incorrectly defined in @file{xm-@var{system}.h} files
+currently.]
+
+@item FETCH_INFERIOR_REGISTERS
+Define this if the native-dependent code will provide its own routines
+@code{fetch_inferior_registers} and @code{store_inferior_registers} in
+@file{@var{HOST}-nat.c}.  If this symbol is @emph{not} defined, and
+@file{infptrace.c} is included in this configuration, the default
+routines in @file{infptrace.c} are used for these functions.
+
+@item FILES_INFO_HOOK
+(Only defined for Convex.)
+
+@item FP0_REGNUM
+This macro is normally defined to be the number of the first floating
+point register, if the machine has such registers.  As such, it would
+appear only in target-specific code.  However, /proc support uses this
+to decide whether floats are in use on this target.
+
+@item GET_LONGJMP_TARGET
+For most machines, this is a target-dependent parameter.  On the
+DECstation and the Iris, this is a native-dependent parameter, since
+<setjmp.h> is needed to define it.
+
+This macro determines the target PC address that longjmp() will jump to,
+assuming that we have just stopped at a longjmp breakpoint.  It takes a
+CORE_ADDR * as argument, and stores the target PC value through this
+pointer.  It examines the current state of the machine as needed.
+
+@item KERNEL_U_ADDR
+Define this to the address of the @code{u} structure (the ``user
+struct'', also known as the ``u-page'') in kernel virtual memory.  GDB
+needs to know this so that it can subtract this address from absolute
+addresses in the upage, that are obtained via ptrace or from core files.
+On systems that don't need this value, set it to zero.
+
+@item KERNEL_U_ADDR_BSD
+Define this to cause GDB to determine the address of @code{u} at
+runtime, by using Berkeley-style @code{nlist} on the kernel's image in
+the root directory.
+
+@item KERNEL_U_ADDR_HPUX
+Define this to cause GDB to determine the address of @code{u} at
+runtime, by using HP-style @code{nlist} on the kernel's image in the
+root directory.
+
+@item ONE_PROCESS_WRITETEXT
+Define this to be able to, when a breakpoint insertion fails, warn the
+user that another process may be running with the same executable.
+
+@item PROC_NAME_FMT
+Defines the format for the name of a @file{/proc} device.  Should be
+defined in @file{nm.h} @emph{only} in order to override the default
+definition in @file{procfs.c}.
+
+@item PTRACE_FP_BUG
+mach386-xdep.c
+
+@item PTRACE_ARG3_TYPE
+The type of the third argument to the @code{ptrace} system call, if it
+exists and is different from @code{int}.
+
+@item REGISTER_U_ADDR
+Defines the offset of the registers in the ``u area''.
+
+@item SHELL_COMMAND_CONCAT
+If defined, is a string to prefix on the shell command used to start the
+inferior.
+
+@item SHELL_FILE
+If defined, this is the name of the shell to use to run the inferior.
+Defaults to @code{"/bin/sh"}.
+
+@item SOLIB_ADD (filename, from_tty, targ)
+Define this to expand into an expression that will cause the symbols in
+@var{filename} to be added to GDB's symbol table.
+
+@item SOLIB_CREATE_INFERIOR_HOOK
+Define this to expand into any shared-library-relocation code that you
+want to be run just after the child process has been forked.
+
+@item START_INFERIOR_TRAPS_EXPECTED
+When starting an inferior, GDB normally expects to trap twice; once when
+the shell execs, and once when the program itself execs.  If the actual
+number of traps is something other than 2, then define this macro to
+expand into the number expected.
+
+@item SVR4_SHARED_LIBS
+Define this to indicate that SVR4-style shared libraries are in use.
+
+@item USE_PROC_FS
+This determines whether small routines in @file{*-tdep.c}, which
+translate register values between GDB's internal representation and the
+/proc representation, are compiled.
+
+@item U_REGS_OFFSET
+This is the offset of the registers in the upage.  It need only be
+defined if the generic ptrace register access routines in
+@file{infptrace.c} are being used (that is, @file{infptrace.c} is
+configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined).  If
+the default value from @file{infptrace.c} is good enough, leave it
+undefined.
+
+The default value means that u.u_ar0 @emph{points to} the location of
+the registers.  I'm guessing that @code{#define U_REGS_OFFSET 0} means
+that u.u_ar0 @emph{is} the location of the registers.
+
+@item CLEAR_SOLIB
+objfiles.c
+
+@item DEBUG_PTRACE
+Define this to debug ptrace calls.
+
+@end table
+
+
+@node Support Libraries
+
+@chapter Support Libraries
+
+@section BFD
+
+BFD provides support for GDB in several ways:
+
+@table @emph
+
+@item identifying executable and core files
+BFD will identify a variety of file types, including a.out, coff, and
+several variants thereof, as well as several kinds of core files.
+
+@item access to sections of files
+BFD parses the file headers to determine the names, virtual addresses,
+sizes, and file locations of all the various named sections in files
+(such as the text section or the data section).  GDB simply calls BFD to
+read or write section X at byte offset Y for length Z.
+
+@item specialized core file support
+BFD provides routines to determine the failing command name stored in a
+core file, the signal with which the program failed, and whether a core
+file matches (i.e. could be a core dump of) a particular executable
+file.
+
+@item locating the symbol information
+GDB uses an internal interface of BFD to determine where to find the
+symbol information in an executable file or symbol-file.  GDB itself
+handles the reading of symbols, since BFD does not ``understand'' debug
+symbols, but GDB uses BFD's cached information to find the symbols,
+string table, etc.
+
+@end table
+
+@section opcodes
+
+The opcodes library provides GDB's disassembler.  (It's a separate
+library because it's also used in binutils, for @file{objdump}).
+
+@section readline
+
+@section mmalloc
+
+@section libiberty
+
+@section gnu-regex
+
+Regex conditionals.
+
+@table @code
+
+@item C_ALLOCA
+
+@item NFAILURES
+
+@item RE_NREGS
+
+@item SIGN_EXTEND_CHAR
+
+@item SWITCH_ENUM_BUG
+
+@item SYNTAX_TABLE
+
+@item Sword
+
+@item sparc
+
+@end table
+
+@section include
+
+@node Coding
+
+@chapter Coding
+
+This chapter covers topics that are lower-level than the major
+algorithms of GDB.
+
+@section Cleanups
+
+Cleanups are a structured way to deal with things that need to be done
+later.  When your code does something (like @code{malloc} some memory,
+or open a file) that needs to be undone later (e.g. free the memory or
+close the file), it can make a cleanup.  The cleanup will be done at
+some future point: when the command is finished, when an error occurs,
+or when your code decides it's time to do cleanups.
+
+You can also discard cleanups, that is, throw them away without doing
+what they say.  This is only done if you ask that it be done.
+
+Syntax:
+
+@table @code
+
+@item struct cleanup *@var{old_chain};
+Declare a variable which will hold a cleanup chain handle.
+
+@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
+Make a cleanup which will cause @var{function} to be called with
+@var{arg} (a @code{char *}) later.  The result, @var{old_chain}, is a
+handle that can be passed to @code{do_cleanups} or
+@code{discard_cleanups} later.  Unless you are going to call
+@code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
+the result from @code{make_cleanup}.
+
+@item do_cleanups (@var{old_chain});
+Perform all cleanups done since @code{make_cleanup} returned
+@var{old_chain}.  E.g.:
+@example
+make_cleanup (a, 0); 
+old = make_cleanup (b, 0); 
+do_cleanups (old);
+@end example
+@noindent
+will call @code{b()} but will not call @code{a()}.  The cleanup that
+calls @code{a()} will remain in the cleanup chain, and will be done
+later unless otherwise discarded.@refill
+
+@item discard_cleanups (@var{old_chain});
+Same as @code{do_cleanups} except that it just removes the cleanups from
+the chain and does not call the specified functions.
+
+@end table
+
+Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
+that they ``should not be called when cleanups are not in place''.  This
+means that any actions you need to reverse in the case of an error or
+interruption must be on the cleanup chain before you call these
+functions, since they might never return to your code (they
+@samp{longjmp} instead).
+
+@section Wrapping Output Lines
+
+Output that goes through @code{printf_filtered} or @code{fputs_filtered}
+or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
+added in places that would be good breaking points.  The utility
+routines will take care of actually wrapping if the line width is
+exceeded.
+
+The argument to @code{wrap_here} is an indentation string which is
+printed @emph{only} if the line breaks there.  This argument is saved
+away and used later.  It must remain valid until the next call to
+@code{wrap_here} or until a newline has been printed through the
+@code{*_filtered} functions.  Don't pass in a local variable and then
+return!
+
+It is usually best to call @code{wrap_here()} after printing a comma or
+space.  If you call it before printing a space, make sure that your
+indentation properly accounts for the leading space that will print if
+the line wraps there.
+
+Any function or set of functions that produce filtered output must
+finish by printing a newline, to flush the wrap buffer, before switching
+to unfiltered (``@code{printf}'') output.  Symbol reading routines that
+print warnings are a good example.
+
+@section GDB Coding Standards
+
+GDB follows the GNU coding standards, as described in
+@file{etc/standards.texi}.  This file is also available for anonymous
+FTP from GNU archive sites.  GDB takes a strict interpretation of the
+standard; in general, when the GNU standard recommends a practice but
+does not require it, GDB requires it.
+
+GDB follows an additional set of coding standards specific to GDB,
+as described in the following sections.
+
+You can configure with @samp{--enable-build-warnings} to get GCC to
+check on a number of these rules.  GDB sources ought not to engender any
+complaints, unless they are caused by bogus host systems.  (The exact
+set of enabled warnings is currently @samp{-Wall -Wpointer-arith
+-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations}.
+
+@subsection Formatting
+
+The standard GNU recommendations for formatting must be followed
+strictly.
+
+Note that while in a definition, the function's name must be in column
+zero; in a function declaration, the name must be on the same line as
+the return type.
+
+In addition, there must be a space between a function or macro name and
+the opening parenthesis of its argument list (except for macro
+definitions, as required by C).  There must not be a space after an open
+paren/bracket or before a close paren/bracket.
+
+While additional whitespace is generally helpful for reading, do not use
+more than one blank line to separate blocks, and avoid adding whitespace
+after the end of a program line (as of 1/99, some 600 lines had whitespace
+after the semicolon).  Excess whitespace causes difficulties for diff and
+patch.
+
+@subsection Comments
+
+The standard GNU requirements on comments must be followed strictly.
+
+Block comments must appear in the following form, with no `/*'- or
+'*/'-only lines, and no leading `*':
+
+@example @code
+/* Wait for control to return from inferior to debugger.  If inferior
+   gets a signal, we may decide to start it up again instead of
+   returning.  That is why there is a loop in this function.  When
+   this function actually returns it means the inferior should be left
+   stopped and GDB should read more commands.  */
+@end example
+
+(Note that this format is encouraged by Emacs; tabbing for a multi-line
+comment works correctly, and M-Q fills the block consistently.)
+
+Put a blank line between the block comments preceding function or
+variable definitions, and the definition itself.
+
+In general, put function-body comments on lines by themselves, rather
+than trying to fit them into the 20 characters left at the end of a
+line, since either the comment or the code will inevitably get longer
+than will fit, and then somebody will have to move it anyhow.
+
+@subsection C Usage
+
+Code must not depend on the sizes of C data types, the format of the
+host's floating point numbers, the alignment of anything, or the order
+of evaluation of expressions.
+
+Use functions freely.  There are only a handful of compute-bound areas
+in GDB that might be affected by the overhead of a function call, mainly
+in symbol reading.  Most of GDB's performance is limited by the target
+interface (whether serial line or system call).
+
+However, use functions with moderation.  A thousand one-line functions
+are just as hard to understand as a single thousand-line function.
+
+@subsection Function Prototypes
+
+Prototypes must be used to @emph{declare} functions but never to
+@emph{define} them.  Prototypes for GDB functions must include both the
+argument type and name, with the name matching that used in the actual
+function definition.
+
+For the sake of compatibility with pre-ANSI compilers, define prototypes
+with the @code{PARAMS} macro:
+
+@example @code
+extern int memory_remove_breakpoint PARAMS ((CORE_ADDR addr,
+                                             char *contents_cache));
+@end example
+
+Note the double parentheses around the parameter types.  This allows an
+arbitrary number of parameters to be described, without freaking out the
+C preprocessor.  When the function has no parameters, it should be
+described like:
+
+@example @code
+extern void noprocess PARAMS ((void));
+@end example
+
+The @code{PARAMS} macro expands to its argument in ANSI C, or to a
+simple @code{()} in traditional C.
+
+All external functions should have a @code{PARAMS} declaration in a
+header file that callers include, except for @code{_initialize_*}
+functions, which must be external so that @file{init.c} construction
+works, but shouldn't be visible to random source files.
+
+All static functions must be declared in a block near the top of the
+source file.
+
+@subsection Clean Design
+
+In addition to getting the syntax right, there's the little question of
+semantics.  Some things are done in certain ways in GDB because long
+experience has shown that the more obvious ways caused various kinds of
+trouble.
+
+You can't assume the byte order of anything that comes from a target
+(including @var{value}s, object files, and instructions).  Such things
+must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in GDB, or one of
+the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}.
+
+You can't assume that you know what interface is being used to talk to
+the target system.  All references to the target must go through the
+current @code{target_ops} vector.
+
+You can't assume that the host and target machines are the same machine
+(except in the ``native'' support modules).  In particular, you can't
+assume that the target machine's header files will be available on the
+host machine.  Target code must bring along its own header files --
+written from scratch or explicitly donated by their owner, to avoid
+copyright problems.
+
+Insertion of new @code{#ifdef}'s will be frowned upon.  It's much better
+to write the code portably than to conditionalize it for various
+systems.
+
+New @code{#ifdef}'s which test for specific compilers or manufacturers
+or operating systems are unacceptable.  All @code{#ifdef}'s should test
+for features.  The information about which configurations contain which
+features should be segregated into the configuration files.  Experience
+has proven far too often that a feature unique to one particular system
+often creeps into other systems; and that a conditional based on some
+predefined macro for your current system will become worthless over
+time, as new versions of your system come out that behave differently
+with regard to this feature.
+
+Adding code that handles specific architectures, operating systems,
+target interfaces, or hosts, is not acceptable in generic code.  If a
+hook is needed at that point, invent a generic hook and define it for
+your configuration, with something like:
+
+@example
+#ifdef	WRANGLE_SIGNALS
+   WRANGLE_SIGNALS (signo);
+#endif
+@end example
+
+In your host, target, or native configuration file, as appropriate,
+define @code{WRANGLE_SIGNALS} to do the machine-dependent thing.  Take a
+bit of care in defining the hook, so that it can be used by other ports
+in the future, if they need a hook in the same place.
+
+If the hook is not defined, the code should do whatever "most" machines
+want.  Using @code{#ifdef}, as above, is the preferred way to do this,
+but sometimes that gets convoluted, in which case use
+
+@example
+#ifndef SPECIAL_FOO_HANDLING
+#define SPECIAL_FOO_HANDLING(pc, sp) (0)
+#endif
+@end example
+
+where the macro is used or in an appropriate header file.
+
+Whether to include a @dfn{small} hook, a hook around the exact pieces of
+code which are system-dependent, or whether to replace a whole function
+with a hook depends on the case.  A good example of this dilemma can be
+found in @code{get_saved_register}.  All machines that GDB 2.8 ran on
+just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved
+registers.  Then the SPARC and Pyramid came along, and
+@code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were
+introduced.  Then the 29k and 88k required the @code{GET_SAVED_REGISTER}
+hook.  The first three are examples of small hooks; the latter replaces
+a whole function.  In this specific case, it is useful to have both
+kinds; it would be a bad idea to replace all the uses of the small hooks
+with @code{GET_SAVED_REGISTER}, since that would result in much
+duplicated code.  Other times, duplicating a few lines of code here or
+there is much cleaner than introducing a large number of small hooks.
+
+Another way to generalize GDB along a particular interface is with an
+attribute struct.  For example, GDB has been generalized to handle
+multiple kinds of remote interfaces -- not by #ifdef's everywhere, but
+by defining the "target_ops" structure and having a current target (as
+well as a stack of targets below it, for memory references).  Whenever
+something needs to be done that depends on which remote interface we are
+using, a flag in the current target_ops structure is tested (e.g.
+`target_has_stack'), or a function is called through a pointer in the
+current target_ops structure.  In this way, when a new remote interface
+is added, only one module needs to be touched -- the one that actually
+implements the new remote interface.  Other examples of
+attribute-structs are BFD access to multiple kinds of object file
+formats, or GDB's access to multiple source languages.
+
+Please avoid duplicating code.  For example, in GDB 3.x all the code
+interfacing between @code{ptrace} and the rest of GDB was duplicated in
+@file{*-dep.c}, and so changing something was very painful.  In GDB 4.x,
+these have all been consolidated into @file{infptrace.c}.
+@file{infptrace.c} can deal with variations between systems the same way
+any system-independent file would (hooks, #if defined, etc.), and
+machines which are radically different don't need to use infptrace.c at
+all.
+
+
+@node Porting GDB
+
+@chapter Porting GDB
+
+Most of the work in making GDB compile on a new machine is in specifying
+the configuration of the machine.  This is done in a dizzying variety of
+header files and configuration scripts, which we hope to make more
+sensible soon.  Let's say your new host is called an @var{xyz} (e.g.
+@samp{sun4}), and its full three-part configuration name is
+@code{@var{arch}-@var{xvend}-@var{xos}} (e.g.  @samp{sparc-sun-sunos4}).
+In particular:
+
+In the top level directory, edit @file{config.sub} and add @var{arch},
+@var{xvend}, and @var{xos} to the lists of supported architectures,
+vendors, and operating systems near the bottom of the file.  Also, add
+@var{xyz} as an alias that maps to
+@code{@var{arch}-@var{xvend}-@var{xos}}.  You can test your changes by
+running
+
+@example
+./config.sub @var{xyz}
+@end example
+@noindent
+and
+@example
+./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
+@end example
+@noindent
+which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
+and no error messages.
+
+You need to port BFD, if that hasn't been done already.  Porting BFD is
+beyond the scope of this manual.
+
+To configure GDB itself, edit @file{gdb/configure.host} to recognize
+your system and set @code{gdb_host} to @var{xyz}, and (unless your
+desired target is already available) also edit @file{gdb/configure.tgt},
+setting @code{gdb_target} to something appropriate (for instance,
+@var{xyz}).
+
+Finally, you'll need to specify and define GDB's host-, native-, and
+target-dependent @file{.h} and @file{.c} files used for your
+configuration.
+
+@section Configuring GDB for Release
+
+From the top level directory (containing @file{gdb}, @file{bfd},
+@file{libiberty}, and so on):
+@example
+make -f Makefile.in gdb.tar.gz
+@end example
+
+This will properly configure, clean, rebuild any files that are
+distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
+and will then make a tarfile.  (If the top level directory has already
+been configured, you can just do @code{make gdb.tar.gz} instead.)
+
+This procedure requires:
+@itemize @bullet
+@item symbolic links
+@item @code{makeinfo} (texinfo2 level)
+@item @TeX{}
+@item @code{dvips}
+@item @code{yacc} or @code{bison}
+@end itemize
+@noindent
+@dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
+
+@subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
+
+@file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
+which are not yet a default for anything (but we have to start using
+them sometime).
+
+For making paper, the only thing this implies is the right generation of
+@file{texinfo.tex} needs to be included in the distribution.
+
+For making info files, however, rather than duplicating the texinfo2
+distribution, generate @file{gdb-all.texinfo} locally, and include the
+files @file{gdb.info*} in the distribution.  Note the plural;
+@code{makeinfo} will split the document into one overall file and five
+or so included files.
+
+@node Hints
+
+@chapter Hints
+
+Check the @file{README} file, it often has useful information that does not
+appear anywhere else in the directory.
+
+@menu
+* Getting Started::		Getting started working on GDB
+* Debugging GDB::		Debugging GDB with itself
+@end menu
+
+@node Getting Started,,, Hints
+
+@section Getting Started
+
+GDB is a large and complicated program, and if you first starting to
+work on it, it can be hard to know where to start.  Fortunately, if you
+know how to go about it, there are ways to figure out what is going on.
+
+This manual, the GDB Internals manual, has information which applies
+generally to many parts of GDB.
+
+Information about particular functions or data structures are located in
+comments with those functions or data structures.  If you run across a
+function or a global variable which does not have a comment correctly
+explaining what is does, this can be thought of as a bug in GDB; feel
+free to submit a bug report, with a suggested comment if you can figure
+out what the comment should say.  If you find a comment which is
+actually wrong, be especially sure to report that.
+
+Comments explaining the function of macros defined in host, target, or
+native dependent files can be in several places.  Sometimes they are
+repeated every place the macro is defined.  Sometimes they are where the
+macro is used.  Sometimes there is a header file which supplies a
+default definition of the macro, and the comment is there.  This manual
+also documents all the available macros.
+@c (@pxref{Host Conditionals}, @pxref{Target
+@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
+@c Conditionals})
+
+Start with the header files.  Once you some idea of how GDB's internal
+symbol tables are stored (see @file{symtab.h}, @file{gdbtypes.h}), you
+will find it much easier to understand the code which uses and creates
+those symbol tables.
+
+You may wish to process the information you are getting somehow, to
+enhance your understanding of it.  Summarize it, translate it to another
+language, add some (perhaps trivial or non-useful) feature to GDB, use
+the code to predict what a test case would do and write the test case
+and verify your prediction, etc.  If you are reading code and your eyes
+are starting to glaze over, this is a sign you need to use a more active
+approach.
+
+Once you have a part of GDB to start with, you can find more
+specifically the part you are looking for by stepping through each
+function with the @code{next} command.  Do not use @code{step} or you
+will quickly get distracted; when the function you are stepping through
+calls another function try only to get a big-picture understanding
+(perhaps using the comment at the beginning of the function being
+called) of what it does.  This way you can identify which of the
+functions being called by the function you are stepping through is the
+one which you are interested in.  You may need to examine the data
+structures generated at each stage, with reference to the comments in
+the header files explaining what the data structures are supposed to
+look like.
+
+Of course, this same technique can be used if you are just reading the
+code, rather than actually stepping through it.  The same general
+principle applies---when the code you are looking at calls something
+else, just try to understand generally what the code being called does,
+rather than worrying about all its details.
+
+A good place to start when tracking down some particular area is with a
+command which invokes that feature.  Suppose you want to know how
+single-stepping works.  As a GDB user, you know that the @code{step}
+command invokes single-stepping.  The command is invoked via command
+tables (see @file{command.h}); by convention the function which actually
+performs the command is formed by taking the name of the command and
+adding @samp{_command}, or in the case of an @code{info} subcommand,
+@samp{_info}.  For example, the @code{step} command invokes the
+@code{step_command} function and the @code{info display} command invokes
+@code{display_info}.  When this convention is not followed, you might
+have to use @code{grep} or @kbd{M-x tags-search} in emacs, or run GDB on
+itself and set a breakpoint in @code{execute_command}.
+
+If all of the above fail, it may be appropriate to ask for information
+on @code{bug-gdb}.  But @emph{never} post a generic question like ``I was
+wondering if anyone could give me some tips about understanding
+GDB''---if we had some magic secret we would put it in this manual.
+Suggestions for improving the manual are always welcome, of course.
+
+@node Debugging GDB,,,Hints
+
+@section Debugging GDB with itself
+
+If GDB is limping on your machine, this is the preferred way to get it
+fully functional.  Be warned that in some ancient Unix systems, like
+Ultrix 4.2, a program can't be running in one process while it is being
+debugged in another.  Rather than typing the command @code{@w{./gdb
+./gdb}}, which works on Suns and such, you can copy @file{gdb} to
+@file{gdb2} and then type @code{@w{./gdb ./gdb2}}.
+
+When you run GDB in the GDB source directory, it will read a
+@file{.gdbinit} file that sets up some simple things to make debugging
+gdb easier.  The @code{info} command, when executed without a subcommand
+in a GDB being debugged by gdb, will pop you back up to the top level
+gdb.  See @file{.gdbinit} for details.
+
+If you use emacs, you will probably want to do a @code{make TAGS} after
+you configure your distribution; this will put the machine dependent
+routines for your local machine where they will be accessed first by
+@kbd{M-.}
+
+Also, make sure that you've either compiled GDB with your local cc, or
+have run @code{fixincludes} if you are compiling with gcc.
+
+@section Submitting Patches
+
+Thanks for thinking of offering your changes back to the community of
+GDB users.  In general we like to get well designed enhancements.
+Thanks also for checking in advance about the best way to transfer the
+changes.
+
+The GDB maintainers will only install ``cleanly designed'' patches.  You
+may not always agree on what is clean design.
+@c @pxref{Coding Style}, @pxref{Clean Design}.
+
+If the maintainers don't have time to put the patch in when it arrives,
+or if there is any question about a patch, it goes into a large queue
+with everyone else's patches and bug reports.
+
+The legal issue is that to incorporate substantial changes requires a
+copyright assignment from you and/or your employer, granting ownership
+of the changes to the Free Software Foundation.  You can get the
+standard document for doing this by sending mail to
+@code{gnu@@prep.ai.mit.edu} and asking for it.  I recommend that people
+write in "All programs owned by the Free Software Foundation" as "NAME
+OF PROGRAM", so that changes in many programs (not just GDB, but GAS,
+Emacs, GCC, etc) can be contributed with only one piece of legalese
+pushed through the bureacracy and filed with the FSF.  I can't start
+merging changes until this paperwork is received by the FSF (their
+rules, which I follow since I maintain it for them).
+
+Technically, the easiest way to receive changes is to receive each
+feature as a small context diff or unidiff, suitable for "patch".
+Each message sent to me should include the changes to C code and
+header files for a single feature, plus ChangeLog entries for each
+directory where files were modified, and diffs for any changes needed
+to the manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi).  If there
+are a lot of changes for a single feature, they can be split down
+into multiple messages.
+
+In this way, if I read and like the feature, I can add it to the
+sources with a single patch command, do some testing, and check it in.
+If you leave out the ChangeLog, I have to write one.  If you leave
+out the doc, I have to puzzle out what needs documenting.  Etc.
+
+The reason to send each change in a separate message is that I will
+not install some of the changes.  They'll be returned to you with
+questions or comments.  If I'm doing my job, my message back to you
+will say what you have to fix in order to make the change acceptable.
+The reason to have separate messages for separate features is so
+that other changes (which I @emph{am} willing to accept) can be installed
+while one or more changes are being reworked.  If multiple features
+are sent in a single message, I tend to not put in the effort to sort
+out the acceptable changes from the unacceptable, so none of the
+features get installed until all are acceptable.
+
+If this sounds painful or authoritarian, well, it is.  But I get a lot
+of bug reports and a lot of patches, and most of them don't get
+installed because I don't have the time to finish the job that the bug
+reporter or the contributor could have done.  Patches that arrive
+complete, working, and well designed, tend to get installed on the day
+they arrive.  The others go into a queue and get installed if and when
+I scan back over the queue -- which can literally take months
+sometimes.  It's in both our interests to make patch installation easy
+-- you get your changes installed, and I make some forward progress on
+GDB in a normal 12-hour day (instead of them having to wait until I
+have a 14-hour or 16-hour day to spend cleaning up patches before I
+can install them).
+
+Please send patches directly to the GDB maintainers at
+@code{gdb-patches@@cygnus.com}.
+
+@section Obsolete Conditionals
+
+Fragments of old code in GDB sometimes reference or set the following
+configuration macros.  They should not be used by new code, and old uses
+should be removed as those parts of the debugger are otherwise touched.
+
+@table @code
+
+@item STACK_END_ADDR
+This macro used to define where the end of the stack appeared, for use
+in interpreting core file formats that don't record this address in the
+core file itself.  This information is now configured in BFD, and GDB
+gets the info portably from there.  The values in GDB's configuration
+files should be moved into BFD configuration files (if needed there),
+and deleted from all of GDB's config files.
+
+Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
+is so old that it has never been converted to use BFD.  Now that's old!
+
+@item PYRAMID_CONTROL_FRAME_DEBUGGING
+pyr-xdep.c
+@item PYRAMID_CORE
+pyr-xdep.c
+@item PYRAMID_PTRACE
+pyr-xdep.c
+
+@item REG_STACK_SEGMENT
+exec.c
+
+@end table
+
+
+@contents
+@bye
diff --git a/gdb/doc/libgdb.texinfo b/gdb/doc/libgdb.texinfo
new file mode 100644
index 0000000000..4fadcb2c9b
--- /dev/null
+++ b/gdb/doc/libgdb.texinfo
@@ -0,0 +1,878 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename libgdb.info
+@settitle Libgdb
+@setchapternewpage off
+@c %**end of header
+
+@ifinfo
+This file documents libgdb, the GNU symbolic debugger in a library.
+
+This is Edition 0.3, Oct 1993, of @cite{Libgdb}.
+Copyright 1993 Cygnus Support
+
+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.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+
+@c  This title page illustrates only one of the
+@c  two methods of forming a title page.
+
+@titlepage
+@title Libgdb
+@subtitle Version 0.3
+@subtitle Oct 1993
+@author Thomas Lord
+
+@c  The following two commands
+@c  start the copyright page.
+@page
+@vskip 0pt plus 1filll
+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.
+
+Copyright @copyright{} 1993 Cygnus Support
+@end titlepage
+
+@ifinfo
+@node Top, Overview, (dir), (dir)
+
+This info file documents libgdb: an API for GDB, the GNU symbolic debugger.
+
+@menu
+* Overview::	             The basics of libgdb and this document.
+* Interpreter::              Libgdb is an Interpreter-Based Server.
+* Top Level::                You Provide the Top Level for the Libgdb
+                                Command Interpreter .
+* I/O::                      How the Server's I/O Can be Used.
+* Invoking::                 Invoking the Interpreter, Executing
+                                Commands. 
+* Defining Commands::        How New Commands are Created.
+* Variables::                How Builtin Variables are Defined.
+* Asynchronous::             Scheduling Asynchronous Computations.
+* Commands::                 Debugger Commands for Libgdb Applications
+@end menu
+
+@end ifinfo
+@node    Overview, Interpreter, top,      top
+@comment node-name,     next,           previous, up
+@chapter Overview
+@cindex overview
+@cindex definitions
+
+@heading Function and Purpose
+
+Libgdb is a package which provides an API to the functionality of GDB,
+the GNU symbolic debugger.  It is specifically intended to support the
+development of a symbolic debugger with a graphic interface.
+
+
+@heading This Document
+
+This document is a specification of the libgdb API.  It is written in
+the form of a programmer's manual.  So the goal of this document is to
+explain what functions make up the API, and how they can be used in a
+running application.
+
+
+@heading Terminology
+
+In this document, @dfn{libgdb} refers to a library containing the
+functions defined herein, @dfn{application} refers to any program built
+with that library.
+
+
+@heading Dependencies
+
+Programs which are linked with libgdb must be linked with libbfd,
+libopcodes, libiberty, and libmmalloc.
+
+@heading Acknowledgments
+
+Essential contributions to this design were made by Stu Grossman, Jim
+Kingdon, and Rich Pixley.
+
+@node Interpreter, Top Level, Overview, Top
+@comment  node-name,  next,  previous,  up
+@chapter Libgdb is an Interpreter Based Server
+@cindex interpreter
+@cindex server
+
+To understand libgdb, it is necessary to understand how the library is
+structured.  Historically, GDB is written as a small interpreter for a
+simple command language.  The commands of the language perform useful
+debugging functions.
+
+Libgdb is built from GDB by turning the interpreter into a debugging
+server.  The server reads debugging commands from any source and
+interprets them, directing the output arbitrarily.
+
+In addition to changing GDB from a tty-based program to a server, a
+number of new GDB commands have been added to make the server more
+useful for a program with a graphic interface.
+
+Finally, libgdb includes provisions for asynchronous processing within
+the application.
+
+Most operations that can be carried out with libgdb involve the GDB
+command interpreter.  The usual mode of operation is that the operation
+is expressed as a string of GDB commands, which the interpreter is then
+invoked to carry out.  The output from commands executed in this manner
+can be redirected in a variety of useful ways for further processing by
+the application.
+
+The command interpreter provides an extensive system of hooks so an
+application can monitor any aspect of the debugging library's state.  An
+application can set its own breakpoints and attach commands and
+conditions to those.  It is possible to attach hooks to any debugger
+command; the hooks are invoked whenever that command is about to be
+invoked.  By means of these, the displays of a graphical interface can
+be kept fully up to date at all times.
+
+We show you how to define new primitives in the command language.  By
+defining new primitives and using them in breakpoint scripts and command
+hooks, an application can schedule the execution of arbitrary C-code at
+almost any point of interest in the operation of libgdb.
+
+We show you how to define new GDB convenience variables for which your
+code computes a value on demand.  Referring to such variables in a
+breakpoint condition is a convenient way to conditionalize breakpoints
+in novel ways.
+
+To summarize: in libgdb, the gdb command language is turned into a
+debugging server.  The server takes commands as input, and the server's
+output is redirectable.  An application uses libgdb by formatting
+debugging commands and invoking the interpreter.  The application might
+maintain breakpoints, watchpoints and many kinds of hooks.  An application
+can define new primitives for the interpreter.
+
+@node Top Level, I/O, Interpreter, Top
+@chapter You Provide the Top Level for the Libgdb Command Interpreter
+@cindex {top level}
+
+When you use libgdb, your code is providing a @dfn{top level} for the
+command language interpreter.  The top level is significant because it
+provides commands for the the interpreter to execute.  In addition, the
+top level is responsible for handling some kinds of errors, and
+performing certain cleanup operations on behalf of the interpreter.
+
+@heading Initialization
+
+Before calling any other libgdb functions, call this:
+
+@deftypefun void gdb_init (void)
+Perform one-time initialization for libgdb.
+@end deftypefun
+
+An application may wish to evaluate specific gdb commands as part of its
+own initialization.  The details of how this can be accomplished are
+explained below.
+
+@heading The Top-Level Loop
+
+There is a strong presumption in libgdb that the application has
+the form of a loop.  Here is what such a loop might look like:
+
+@example
+while (gdb_still_going ())
+  @{
+    if (!GDB_TOP_LEVEL ())
+      @{
+        char * command;
+        gdb_start_top_loop ();
+        command = process_events ();
+        gdb_execute_command (command);
+        gdb_finish_top_loop ();
+      @}
+    @}
+@end example
+
+The function @code{gdb_still_going} returns 1 until the gdb command
+`quit' is run.
+
+The macro @code{GDB_TOP_LEVEL} invokes setjmp to set the top level error
+handler.  When a command results in an error, the interpreter exits with
+a longjmp. There is nothing special libgdb requires of the top level
+error handler other than it be present and that it restart the top level
+loop.  Errors are explained in detail in a later chapter.
+
+Each time through the top level loop two important things happen: a
+debugger command is constructed on the basis of user input, and the
+interpreter is invoked to execute that command.  In the sample code, the
+call to the imaginary function @code{process_events} represents the
+point at which a graphical interface should read input events until
+ready to execute a debugger command.  The call to
+@code{gdb_execute_command} invokes the command interpreter (what happens
+to the output from the command will be explained later).
+
+Libgdb manages some resources using the top-level loop.  The primary
+reason for this is error-handling: even if a command terminates with an
+error, it may already have allocated resources which need to be freed.
+The freeing of such resources takes place at the top-level, regardless
+of how the the command exits.  The calls to @code{gdb_start_top_loop}
+and @code{gdb_finish_top_loop} let libgdb know when it is safe to
+perform operations associated with these resources.
+
+@heading Breakpoint Commands
+
+Breakpoint commands are scripts of GDB operations associated with 
+particular breakpoints.  When a breakpoint is reached, its associated
+commands are executed.
+
+Breakpoint commands are invoked by the libgdb function
+@code{gdb_finish_top_loop}.  
+
+Notice that if control returns to the top-level error handler, the
+execution of breakpoint commands is bypassed.  This can happen as a
+result of errors during either @code{gdb_execute_command} or
+@code{gdb_finish_top_loop}.
+
+@heading Application Initialization
+
+Sometimes it is inconvenient to execute commands via a command loop for
+example, the commands an application uses to initialize itself.  An
+alternative to @code{execute_command} is @code{execute_catching_errors}.
+When @code{execute_catching_errors} is used, no top level error handler
+need be in effect, and it is not necessary to call
+@code{gdb_start_top_loop} or @code{gdb_finish_top_loop}.
+
+
+@heading Cleanup
+
+The debugger command ``quit'' performs all necessary cleanup for libgdb.
+After it has done so, it changes the return value of
+@code{gdb_still_going} to 0 and returns to the top level error handler.
+
+
+@node I/O, Invoking, Top Level, Top
+@comment  node-name,  next,  previous,  up
+@chapter How the Server's I/O Can be Used
+@cindex I/O
+
+In the last chapter it was pointed out that a libgdb application is
+responsible for providing commands for the interpreter to execute.
+However some commands require further input (for example, the ``quit''
+command might ask for confirmation).  Almost all commands produce output
+of some kind.  The purpose of this section is to explain how libgdb
+performs its I/O, and how an application can take advantage of
+this.
+
+
+@heading I/O Vectors
+
+Libgdb has no fixed strategy for I/O.  Instead, all operations are
+performed by functions called via structures of function pointers.
+Applications supply theses structures and can change them at any
+time.
+
+@deftp Type {struct gdb_input_vector}
+@deftpx Type {struct gdb_output_vector}
+These structures contain a set of function pointers.  Each function
+determines how a particular type of i/o is performed.  The details of
+these strucutres are explained below.
+
+The application allocates these structures, initializes them to all bits
+zero, fills in the function pointers, and then registers names for them
+them with libgdb.
+@end deftp
+
+@deftypefun void gdb_name_input_vector (@var{name}, @var{vec})
+@deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec})
+@deftypefunx void gdb_name_output_vector (@var{name}, @var{vec})
+@deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec})
+@example
+  char * @var{name};
+  struct gdb_output_vector * @var{vec};
+@end example
+These functions are used to give and remove names to i/o vectors.  Note
+that if a name is used twice, the most recent definition applies.
+@end deftypefun
+
+
+
+@subheading Output
+
+An output vector is a structure with at least these fields: 
+
+@example
+struct gdb_output_vector
+@{
+  /* output */
+  void (*put_string) (struct gdb_output_vector *, char * str);
+@}
+@end example
+
+Use the function @code{memset} or something equivalent to initialize an
+output vector to all bits zero.  Then fill in the function pointer with
+your function.
+
+A debugger command can produce three kinds of output: error messages
+(such as when trying to delete a non-existent breakpoint), informational
+messages (such as the notification printed when a breakpoint is hit),
+and the output specifically requested by a command (for example, the
+value printed by the ``print'' command).  At any given time, then,
+libgdb has three output vectors.  These are called the @dfn{error},
+@dfn{info}, @dfn{value} vector respectively.  
+
+@subheading Input
+
+@example
+struct gdb_input_vector
+@{
+  int (*query) (struct gdb_input_vector *,
+                char * prompt,
+                int quit_allowed);
+  int * (*selection) (struct gdb_input_vector *,
+                      char * prompt,
+                      char ** choices);
+  char * (*read_string) (struct gdb_input_vector *,
+                         char * prompt);
+  char ** (*read_strings) (struct gdb_input_vector *,
+                           char * prompt);
+@}
+@end example
+
+Use the function @code{memset} or something equivalent to initialize an
+input vector to all bits zero.  Then fill in the function pointers with
+your functions.
+
+There are four kinds of input requests explicitly made by libgdb.
+
+A @dfn{query} is a yes or no question.  The user can respond to a query
+with an affirmative or negative answer, or by telling gdb to abort the
+command (in some cases an abort is not permitted).  Query should return
+'y' or 'n' or 0 to abort.
+
+A @dfn{selection} is a list of options from which the user selects a subset.
+Selections should return a NULL terminated array of integers, which are
+indexes into the array of choices.  It can return NULL instead to abort
+the command.  The array returned by this function will be passed to
+@code{free} by libgdb.
+
+A @dfn{read_string} asks the user to supply an arbitrary string.  It may
+return NULL to abort the command.  The string returned by @code{read_string}
+should be allocated by @code{malloc}; it will be freed by libgdb.
+
+A @dfn{read_strings} asks the user to supply multiple lines of input
+(for example, the body of a command created using `define').  It, too,
+may return NULL to abort.  The array and the strings returned by this
+function will be freed by libgdb.
+
+@heading I/O Redirection from the Application Top-Level
+
+@deftypefun struct gdb_io_vecs gdb_set_io (struct gdb_io_vecs *)
+@example
+
+struct gdb_io_vecs
+@{
+  struct gdb_input_vector * input;
+  struct gdb_output_vector * error;
+  struct gdb_output_vector * info;
+  struct gdb_output_vector * value;
+@}
+@end example
+
+This establishes a new set of i/o vectors, and returns the old setting.
+Any of the pointers in this structure may be NULL, indicating that the
+current value should be used.
+
+This function is useful for setting up i/o vectors before any libgdb
+commands have been invoked (hence before any input or output has taken
+place).
+@end deftypefun
+
+It is explained in a later chapter how to redirect output temporarily.
+(@xref{Invoking}.)
+
+@heading I/O Redirection in Debugger Commands
+
+A libgdb application creates input and output vectors and assigns them names.
+Which input and output vectors are used by libgdb is established by
+executing these debugger commands: 
+
+@defun {set input-vector} name
+@defunx {set error-output-vector} name
+@defunx {set info-output-vector} name
+@defunx {set value-output-vector} name
+Choose an I/O vector by name.
+@end defun
+
+
+A few debugger commands are for use only within commands defined using
+the debugger command `define' (they have no effect at other times).
+These commands exist so that an application can maintain hooks which
+redirect output without affecting the global I/O vectors.
+
+@defun with-input-vector name
+@defunx with-error-output-vector name
+@defunx with-info-output-vector name
+@defunx with-value-output-vector name
+Set an I/O vector, but only temporarily.  The setting has effect only
+within the command definition in which it occurs.
+@end defun
+
+
+@heading Initial Conditions
+
+When libgdb is initialized, a set of default I/O vectors is put in
+place.  The default vectors are called @code{default-input-vector},
+@code{default-output-vector}, &c.  
+
+The default query function always returns `y'.  Other input functions
+always abort.  The default output functions discard output silently.
+
+
+@node Invoking, Defining Commands, I/O, Top
+@chapter Invoking the Interpreter, Executing Commands
+@cindex {executing commands}
+@cindex {invoking the interpreter}
+
+This section introduces the libgdb functions which invoke the command
+interpreter. 
+
+@deftypefun void gdb_execute_command (@var{command})
+@example
+char * @var{command};
+@end example
+Interpret the argument debugger command.  An error handler must be set
+when this function is called. (@xref{Top Level}.)
+@end deftypefun
+
+It is possible to override the current I/O vectors for the duration of a
+single command:
+
+@deftypefun void gdb_execute_with_io (@var{command}, @var{vecs})
+@example 
+char * @var{command};
+struct gdb_io_vecs * @var{vecs};
+
+struct gdb_io_vecs
+@{
+  struct gdb_input_vector * input;
+  struct gdb_output_vector * error;
+  struct gdb_output_vector * info;
+  struct gdb_output_vector * value;
+@}
+@end example
+
+Execute @var{command}, temporarily using the i/o vectors in @var{vecs}.
+
+Any of the vectors may be NULL, indicating that the current value should
+be used.  An error handler must be in place when this function is used.
+@end deftypefun
+
+@deftypefun {struct gdb_str_output} gdb_execute_for_strings (@var{cmd})
+@example
+char * cmd;
+@end example
+@deftypefunx {struct gdb_str_output} gdb_execute_for_strings2 (@var{cmd}, @var{input})
+@example
+char * cmd;
+struct gdb_input_vector * input;
+@end example
+@page
+@example
+struct gdb_str_output
+@{
+  char * error;
+  char * info;
+  char * value;
+@};
+@end example
+
+Execute @var{cmd}, collecting its output as strings.  If no error
+occurs, all three strings will be present in the structure, the
+empty-string rather than NULL standing for no output of a particular
+kind. 
+
+If the command aborts with an error, then the @code{value} field will be
+NULL, though the other two strings will be present.
+
+In all cases, the strings returned are allocated by malloc and should be
+freed by the caller.
+
+The first form listed uses the current input vector, but overrides the
+current output vector.  The second form additionally allows the input
+vector to be overridden.
+
+This function does not require that an error handler be installed.
+@end deftypefun
+
+@deftypefun void execute_catching_errors (@var{command})
+@example
+char * @var{command};
+@end example
+Like @code{execute_command} except that no error handler is required.
+@end deftypefun
+
+@deftypefun void execute_with_text (@var{command}, @var{text})
+@example
+char * @var{command};
+char ** @var{text};
+@end example
+Like @code{execute_catching_errors}, except that the input vector is
+overridden.  The new input vector handles only calls to @code{query} (by
+returning 'y') and calls to @code{read_strings} by returning a copy of
+@var{text} and the strings it points to.
+
+This form of execute_command is useful for commands like @code{define},
+@code{document}, and @code{commands}.
+@end deftypefun
+
+
+
+@node Defining Commands, Variables, Invoking, Top
+@comment  node-name,  next,  previous,  up
+@chapter How New Commands are Created
+@cindex {commands, defining}
+
+Applications are, of course, free to take advantage of the existing GDB
+macro definition capability (the @code{define} and @code{document}
+functions).  
+
+In addition, an application can add new primitives to the GDB command
+language.
+
+@deftypefun void gdb_define_app_command (@var{name}, @var{fn}, @var{doc})
+@example
+char * @var{name};
+gdb_cmd_fn @var{fn};
+char * @var{doc};
+
+typedef void (*gdb_cmd_fn) (char * args);
+@end example
+
+Create a new command call @var{name}.  The new command is in the
+@code{application} help class.  When invoked, the command-line arguments
+to the command are passed as a single string.
+
+Calling this function twice with the same name replaces an earlier
+definition, but application commands can not replace builtin commands of
+the same name.
+
+The documentation string of the command is set to a copy the string
+@var{doc}.
+@end deftypefun
+
+@node Variables, Asynchronous, Defining Commands, Top
+@comment  node-name,  next,  previous,  up
+@chapter How Builtin Variables are Defined
+@cindex {variables, defining}
+
+Convenience variables provide a way for values maintained by libgdb to
+be referenced in expressions (e.g. @code{$bpnum}).  Libgdb includes a
+means by which the application can define new, integer valued
+convenience variables:
+@page
+@deftypefun void gdb_define_int_var (@var{name}, @var{fn}, @var{fn_arg})
+@example
+char * @var{name};
+int (*@var{fn}) (void *);
+void * @var{fn_arg};
+@end example
+This function defines (or undefines) a convenience variable called @var{name}.
+If @var{fn} is NULL, the variable becomes undefined.  Otherwise,
+@var{fn} is a function which, when passed @var{fn_arg} returns the value
+of the newly defined variable.
+
+No libgdb functions should be called by @var{fn}.
+@end deftypefun
+
+One use for this function is to create breakpoint conditions computed in
+novel ways.  This is done by defining a convenience variable and
+referring to that variable in a breakpoint condition expression.
+
+
+@node Asynchronous, Commands, Variables, Top
+@chapter Scheduling Asynchronous Computations
+@cindex asynchronous
+
+
+A running libgdb function can take a long time.  Libgdb includes a hook
+so that an application can run intermittently during long debugger
+operations.
+
+@deftypefun void gdb_set_poll_fn (@var{fn}, @var{fn_arg})
+@example
+void (*@var{fn})(void * fn_arg, int (*gdb_poll)());
+void * @var{fn_arg};
+@end example
+Arrange to call @var{fn} periodically during lengthy debugger operations.
+If @var{fn} is NULL, polling is turned off.  @var{fn} should take two
+arguments: an opaque pointer passed as @var{fn_arg} to
+@code{gdb_set_poll_fn}, and a function pointer.  The function pointer
+passed to @var{fn} is provided by libgdb and points to a function that
+returns 0 when the poll function should return.  That is, when
+@code{(*gdb_poll)()} returns 0, libgdb is ready to continue @var{fn}
+should return quickly.
+
+It is possible that @code{(*gdb_poll)()} will return 0 the first time it
+is called, so it is reasonable for an application to do minimal processing
+before checking whether to return.
+
+No libgdb functions should be called from an application's poll function,
+with one exception: @code{gdb_request_quit}.
+@end deftypefun
+
+
+@deftypefun void gdb_request_quit (void)
+This function, if called from a poll function, requests that the
+currently executing libgdb command be interrupted as soon as possible,
+and that control be returned to the top-level via an error.
+
+The quit is not immediate.  It will not occur until at least after the
+application's poll function returns.
+@end deftypefun 
+
+@node Commands, Top, Asynchronous, Top
+@comment  node-name,  next,  previous,  up
+@chapter Debugger Commands for Libgdb Applications
+
+The debugger commands available to libgdb applications are the same commands
+available interactively via GDB.  This section is an overview of the
+commands newly created as part of libgdb.
+
+This section is not by any means a complete reference to the GDB command
+language.  See the GDB manual for such a reference.
+
+@menu
+* Command Hooks::    Setting Hooks to Execute With Debugger Commands.
+* View Commands::    View Commands Mirror Show Commands
+* Breakpoints::      The Application Can Have Its Own Breakpoints
+@end menu
+
+@node Command Hooks, View Commands, Commands, Commands
+@comment  node-name,  next,  previous,  up
+@section Setting Hooks to Execute With Debugger Commands.
+
+Debugger commands support hooks.  A command hook is executed just before
+the interpreter invokes the hooked command.
+
+There are two hooks allowed for every command.  By convention, one hook
+is for use by users, the other is for use by the application.
+
+A user hook is created for a command XYZZY by using
+@code{define-command} to create a command called @code{hook-XYZZY}.
+
+An application hook is created for a command XYZZY by using
+@code{define-command} to create a command called @code{apphook-XYZZY}.
+
+Application hooks are useful for interfaces which wish to continuously
+monitor certain aspects of debugger state.  The application can set a
+hook on all commands that might modify the watched state.  When the hook
+is executed, it can use i/o redirection to notify parts of the
+application that previous data may be out of date.  After the top-level loop
+resumes, the application can recompute any values that may have changed.
+(@xref{I/O}.)
+
+@node View Commands, Breakpoints, Command Hooks, Commands
+@comment  node-name,  next,  previous,  up
+@section View Commands Mirror Show Commands
+
+The GDB command language contains many @code{set} and @code{show}
+commands.  These commands are used to modify or examine parameters to
+the debugger.
+
+It is difficult to get the current state of a parameter from the
+@code{show} command because @code{show} is very verbose.
+
+@example
+(gdb) show check type
+Type checking is "auto; currently off".
+(gdb) show width
+Number of characters gdb thinks are in a line is 80.
+@end example
+
+For every @code{show} command, libgdb includes a @code{view} command.
+@code{view} is like @code{show} without the verbose commentary:
+
+@example
+(gdb) view check type
+auto; currently off
+(gdb) view width
+80
+@end example
+
+(The precise format of the ouput from @code{view} is subject to change.
+In particular, @code{view} may one-day print values which can be used as
+arguments to the corresponding @code{set} command.)
+
+@node Breakpoints, Structured Output, View Commands, Commands
+@comment  node-name,  next,  previous,  up
+@section The Application Can Have Its Own Breakpoints
+
+The GDB breakpoint commands were written with a strong presumption that
+all breakpoints are managed by a human user.  Therefore, the command
+language contains commands like `delete' which affect all breakpoints
+without discrimination.
+
+In libgdb, there is added support for breakpoints and watchpoints which
+are set by the application and which should not be affected by ordinary,
+indiscriminate commands.  These are called @dfn{protected} breakpoints.
+
+@deffn {Debugger Command} break-protected ...
+@deffnx {Debugger Command} watch-protected ...
+These work like @code{break} and @code{watch} except that the resulting
+breakpoint is given a negative number.  Negative numbered breakpoints do
+not appear in the output of @code{info breakpoints} but do in that of
+@code{info all-breakpoints}.  Negative numbered breakpoints are not
+affected by commands which ordinarily affect `all' breakpoints (e.g.
+@code{delete} with no arguments).
+
+Note that libgdb itself creates protected breakpoints, so programs
+should not rely on being able to allocate particular protected
+breakpoint numbers for themselves.
+@end deffn
+
+More than one breakpoint may be set at a given location.  Libgdb adds
+the concept of @dfn{priority} to breakpoints.  A priority is an integer,
+assigned to each breakpoint.  When a breakpoint is reached, the
+conditions of all breakpoints at the same location are evaluated in
+order of ascending priority.  When breakpoint commands are executed,
+they are also executed in ascending priority (until all have been
+executed, an error occurs, or one set of commands continues the
+target).
+
+@deffn {Debugger Command} priority n bplist
+Set the priority for breakpoints @var{bplist} to @var{n}.
+By default, breakpoints are assigned a priority of zero.
+@end deffn
+
+@node Structured Output, Commands, Breakpoints, Commands
+@comment  node-name,  next,  previous,  up
+@section  Structured Output, The @code{Explain} Command
+
+(This section may be subject to considerable revision.)
+
+When GDB prints a the value of an expression, the printed representation
+contains information that can be usefully fed back into future commands
+and expressions.  For example, 
+
+@example
+(gdb) print foo
+$16 = @{v = 0x38ae0, v_length = 40@}
+@end example
+
+On the basis of this output, a user knows, for example, that
+@code{$16.v} refers to a pointer valued @code{0x38ae0}
+
+A new output command helps to make information like this available to
+the application.
+
+@deffn {Debugger Command} explain expression
+@deffnx {Debugger Command} explain /format expression
+Print the value of @var{expression} in the manner of the @code{print}
+command, but embed that output in a list syntax containing information
+about the structure of the output.
+@end deffn
+
+As an example, @code{explain argv} might produce this output:
+
+@example
+(exp-attribute
+   ((expression "$19")
+    (type "char **")
+    (address "48560")
+    (deref-expression "*$19"))
+   "$19 = 0x3800\n")
+@end example
+
+The syntax of output from @code{explain} is:
+
+@example
+<explanation> :=    <quoted-string>
+                  | (exp-concat <explanation> <explanation>*)
+                  | (exp-attribute <property-list> <explanation>)
+
+<property-list> := ( <property-pair>* )
+
+<property-pair> := ( <property-name> <quoted-string> )
+@end example
+
+The string-concatenation of all of the @code{<quoted-string>} (except
+those in property lists) yields the output generated by the equivalent
+@code{print} command.  Quoted strings may contain quotes and backslashes
+if they are escaped by backslash.  "\n" in a quoted string stands for
+newline; unescaped newlines do not occur within the strings output by
+@code{explain}.
+
+Property names are made up of alphabetic characters, dashes, and
+underscores.
+
+The set of properties is open-ended.  As GDB acquires support for new
+source languages and other new capabilities, new property types may be
+added to the output of this command.  Future commands may offer
+applications some selectivity concerning which properties are reported.
+
+The initial set of properties defined includes: 
+
+@itemize @bullet
+@item @code{expression}
+
+This is an expression, such as @code{$42} or @code{$42.x}.  The
+expression can be used to refer to the value printed in the attributed
+part of the string.
+
+@item @code{type}
+
+This is a user-readable name for the type of the attributed value.
+
+@item @code{address}
+
+If the value is stored in a target register, this is a register number.
+If the value is stored in a GDB convenience variable, this is an integer
+that is unique among all the convenience variables.  Otherwise, this is
+the address in the target where the value is stored.
+
+@item @code{deref-expression}
+
+If the attributed value is a pointer type, this is an expression that
+refers to the dereferenced value.
+@end itemize
+
+Here is a larger example, using the same object passed to @code{print}
+in an earlier example of this section.
+
+@example
+(gdb) explain foo
+(exp-attribute
+  ( (expression "$16")
+    (type "struct bytecode_vector")
+    (address 14336) )
+  (exp-concat
+    "$16 = @{"
+    (exp-attribute
+      ( (expression "$16.v")
+        (type "char *")
+        (address 14336)
+        (deref-expression "*$16.v") )
+      "v = 0x38ae0")
+    (exp-attribute
+      ( (expression "$16.v_length")
+        (type "int")
+        (address 14340) )
+      ", v_length = 40")
+     "@}\n"))
+@end example
+
+It is undefined how libgdb will indent these lines of output or 
+where newlines will be included.
+
+@bye
diff --git a/gdb/doc/lpsrc.sed b/gdb/doc/lpsrc.sed
new file mode 100644
index 0000000000..1c7af4aaf4
--- /dev/null
+++ b/gdb/doc/lpsrc.sed
@@ -0,0 +1,13 @@
+/font defs: ---/,/end font defs ---/c\
+%-------------------- PostScript (long names) font defs: -----------------\
+\\font\\bbf=Times-Bold at 10pt\
+\\font\\vbbf=Times-Bold at 12pt\
+\\font\\smrm=Times-Roman at 6pt\
+\\font\\brm=Times-Roman at 10pt\
+\\font\\rm=Times-Roman at 8pt\
+\\font\\it=Times-Italic at 8pt\
+\\font\\tt=Courier at 8pt\
+% Used only for \copyright, replacing plain TeX macro.\
+\\font\\sym=Symbol at 7pt\
+\\def\\copyright{{\\sym\\char'323}}\
+%-------------------- end font defs ---------------------------------
diff --git a/gdb/doc/psrc.sed b/gdb/doc/psrc.sed
new file mode 100644
index 0000000000..9bb557eae2
--- /dev/null
+++ b/gdb/doc/psrc.sed
@@ -0,0 +1,13 @@
+/font defs: ---/,/end font defs ---/c\
+%-------------------- PostScript (K Berry names) font defs: --------------\
+\\font\\bbf=ptmb at 10pt\
+\\font\\vbbf=ptmb at 12pt\
+\\font\\smrm=ptmr at 6pt\
+\\font\\brm=ptmr at 10pt\
+\\font\\rm=ptmr at 8pt\
+\\font\\it=ptmri at 8pt\
+\\font\\tt=pcrr at 8pt\
+% Used only for \copyright, replacing plain TeX macro.\
+\\font\\sym=psyr at 7pt\
+\\def\\copyright{{\\sym\\char'323}}\
+%-------------------- end font defs ---------------------------------
diff --git a/gdb/doc/refcard.tex b/gdb/doc/refcard.tex
new file mode 100644
index 0000000000..d2b72de04d
--- /dev/null
+++ b/gdb/doc/refcard.tex
@@ -0,0 +1,645 @@
+%%%%%%%%%%%%%%%% gdb-refcard.tex %%%%%%%%%%%%%%%%
+
+%This file is TeX source for a reference card describing GDB, the GNU debugger.
+%Copyright (C) 1991, 1992, 1993, 1998 Free Software Foundation, Inc.
+%Permission is granted to make and distribute verbatim copies of
+%this reference provided the copyright notices and permission notices
+%are preserved on all copies.
+%
+%TeX markup is a programming language; accordingly this file is source
+%for a program to generate a reference.
+%
+%This program is free software; you can redistribute it and/or modify
+%it under the terms of the GNU General Public License as published by
+%the Free Software Foundation; either version 2, or (at your option)
+%any later version.
+%
+%This program is distributed in the hope that it will be useful, but
+%WITHOUT ANY WARRANTY; without even the implied warranty of
+%MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+%General Public License for more details.
+%
+%You can find a copy of the GNU General Public License at the URL
+%http://www.gnu.org/copyleft/gpl.html; or write to the Free Software
+%Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+%
+%You can contact the maintainer at:  doc@cygnus.com
+%
+%                                Documentation Department
+%                                Cygnus Solutions
+%                                1325 Chesapeake Terrace
+%                                Sunnyvale, CA 94089  USA
+%
+%                                +1 800 CYGNUS-1
+%
+%
+%
+% 22-AUG-1993 Andreas Vogel
+%
+%   Modifications made in order to handle different papersizes correctly.
+%   You only have to set the total width and height of the paper, the
+%   horizontal and vertical margin space measured from *paper edge*
+%   and the interline and interspec spacing.
+%   In order to support a new papersize, you have to fiddle with the
+%   latter four dimensions. Just try out a few values.
+%   All other values will be computed at process time so it should be
+%   quite easy to support different paper sizes - only four values to
+%   guess :-)
+%
+%   To find the configuration places, just search for the string
+%   "CONFIGURATION".
+%
+%   Andreas Vogel (av@ssw.de)
+%
+%
+%
+% Uncomment the following `magnification' command if you want to print
+% out in a larger font.  Caution!  You may need larger paper.  You had
+% best avoid using 3-column output if you try this.  See the ``Three
+% column format'' section below if you want to print in three column
+% format.
+%
+%\magnification=\magstep 1
+%
+% NOTE ON INTENTIONAL OMISSIONS: This reference card includes most GDB
+% commands, but due to space constraints there are some things I chose
+% to omit.  In general, not all synonyms for commands are covered, nor
+% all variations of a command.
+% The GDB-under-Emacs section omits gdb-mode functions without default
+% keybindings.  GDB startup options are not described.
+% set print sevenbit-strings, set symbol-reloading omitted.
+% printsyms, printpsyms, omitted since they're for GDB maintenance primarily
+% share omitted due to obsolescence
+% set check range/type omitted at least til code is in GDB.
+%
+%-------------------- Three column format -----------------------
+
+%%%% --- To disable three column format, comment out this entire section
+
+% Three-column format for landscape printing
+
+%-------- Papersize defs:
+
+\newdimen\totalwidth \newdimen\totalheight
+\newdimen\hmargin    \newdimen\vmargin
+\newdimen\secskip    \newdimen\lskip
+\newdimen\barwidth   \newdimen\barheight
+\newdimen\intersecwidth
+
+%%
+%%  START CONFIGURATION - PAPERSIZE DEFINITIONS
+%------- Papersize params:
+%%  US letter paper (8.5x11in)
+%%
+\totalwidth=11in    % total width of paper
+\totalheight=8.5in  % total height of paper
+\hmargin=.25in      % horizontal margin width
+\vmargin=.25in      % vertical margin width
+\secskip=1pc        % space between refcard secs
+\lskip=2pt          % extra skip between \sec entries
+%------- end papersize params
+%%
+%%  change according to personal taste, not papersize dependent
+%%
+\barwidth=.1pt       % width of the cropmark bar
+\barheight=2pt       % height of the cropmark bar
+\intersecwidth=0.5em % width between \itmwid and \dfnwid
+%%
+%%  END CONFIGURATION - PAPERSIZE DEFINITIONS
+%%
+
+%%
+%%  values to be computed - nothing to configure
+%%
+\newdimen\fullhsize     % width of area without margins
+\newdimen\itmwid        % width of item column
+\newdimen\dfnwid        % width of definition column
+\newdimen\temp          % only for temporary use
+
+%%
+%%  adjust the offsets so the margins are measured *from paper edge*
+%%
+\hoffset=-1in \advance \hoffset by \hmargin
+\voffset=-1in \advance \voffset by \vmargin
+
+%%
+%%  fullhsize = totalwidth - (2 * hmargin)
+%%
+\fullhsize=\totalwidth
+\temp=\hmargin \multiply \temp by 2 \advance \fullhsize by -\temp
+
+%%
+%%  hsize = (fullhsize - (4 * hmargin) - (2 * barwidth)) / 3
+%%
+\hsize=\fullhsize
+\temp=\hmargin \multiply \temp by 4 \advance \hsize by -\temp
+\temp=\barwidth \multiply \temp by 2 \advance \hsize by -\temp
+\divide \hsize by 3
+
+%%
+%%  vsize = totalheight - (2 * vmargin)
+%%
+\vsize=\totalheight
+\temp=\vmargin \multiply \temp by 2 \advance \vsize by -\temp
+
+%%
+%%  itmwid = (hsize - intersecwidth) * 1/3
+%%  dfnwid = (hsize - intersecwidth) * 2/3
+%%
+\temp=\hsize \advance \temp by -\intersecwidth \divide \temp by 3
+\itmwid=\temp
+\dfnwid=\hsize \advance \dfnwid by -\itmwid
+
+%-------- end papersize defs
+
+
+\def\fulline{\hbox to \fullhsize}
+\let\lcr=L \newbox\leftcolumn\newbox\centercolumn
+\output={\if L\lcr
+            \global\setbox\leftcolumn=\columnbox \global\let\lcr=C
+	 \else
+            \if C\lcr
+               \global\setbox\centercolumn=\columnbox \global\let\lcr=R
+            \else \tripleformat \global\let\lcr=L
+            \fi
+         \fi
+%         \ifnum\outputpenalty>-20000 \else\dosupereject\fi
+      }
+
+%%
+%%  START CONFIGURATION - ALTERNATIVE FOLDING GUIDES
+%%
+%%  For NO printed folding guide,
+%%  comment out other \def\vdecor's and uncomment:
+
+%\def\vdecor{\hskip\hmargin plus1fil\hskip\barwidth plus1fil\hskip\hmargin plus1fil}
+
+%%  For SOLID LINE folding guide,
+%%  comment out other \def\vdecor's and uncomment:
+
+%\def\vdecor{\hskip\hmargin plus1fil \vrule width \barwidth \hskip\hmargin plus1fil}
+
+%%  For SMALL MARKS NEAR TOP AND BOTTOM as folding guide,
+%%  comment out other \def\vdecor's and uncomment:
+
+\def\vdecor{\hskip\hmargin plus1fil
+\vbox to \vsize{\hbox to \barwidth{\vrule height\barheight width\barwidth}\vfill
+\hbox to \barwidth{\vrule height\barheight width\barwidth}}%THIS PERCENT SIGN IS ESSENTIAL
+\hskip\hmargin plus1fil}
+
+%%
+%%  END CONFIGURATION - ALTERNATIVES FOR FOLDING GUIDES
+%%
+
+\def\tripleformat{\shipout\vbox{\fulline{\box\leftcolumn\vdecor
+					 \box\centercolumn\vdecor
+					 \columnbox}
+			       }
+                 \advancepageno}
+\def\columnbox{\leftline{\pagebody}}
+\def\bye{\par\vfill
+         \supereject
+         \if R\lcr \null\vfill\eject\fi
+         \end}
+
+%-------------------- end three column format -----------------------
+
+%-------------------- Computer Modern font defs: --------------------
+\font\bbf=cmbx10
+\font\vbbf=cmbx12
+\font\smrm=cmr6
+\font\brm=cmr10
+\font\rm=cmr7
+\font\it=cmti7
+\font\tt=cmtt8
+%-------------------- end font defs ---------------------------------
+
+%
+\hyphenpenalty=5000\tolerance=2000\raggedright\raggedbottom
+\normalbaselineskip=9pt\baselineskip=9pt
+%
+\parindent=0pt
+\parskip=0pt
+\footline={\vbox to0pt{\hss}}
+%
+\def\ctl#1{{\tt C-#1}}
+\def\opt#1{{\brm[{\rm #1}]}}
+\def\xtra#1{\noalign{\smallskip{\tt#1}}}
+%
+\long\def\sec#1;#2\endsec{\vskip \secskip
+\halign{%
+%COL 1 (of halign):
+\vtop{\hsize=\itmwid\tt
+##\par\vskip \lskip }\hfil
+%COL 2 (of halign):
+&\vtop{\hsize=\dfnwid\hangafter=1\hangindent=\intersecwidth
+\rm ##\par\vskip \lskip}\cr
+%Tail of \long\def fills in halign body with \sec args:
+\noalign{{\bbf #1}\vskip \lskip}
+#2
+}
+}
+
+{\vbbf GDB QUICK REFERENCE}\hfil{\smrm GDB Version 4}\qquad
+
+\sec Essential Commands;
+gdb {\it program} \opt{{\it core}}&debug {\it program} \opt{using
+coredump {\it core}}\cr
+b \opt{\it file\tt:}{\it function}&set breakpoint at {\it function} \opt{in \it file}\cr
+run \opt{{\it arglist}}&start your program \opt{with {\it arglist}}\cr
+bt& backtrace: display program stack\cr
+p {\it expr}&display the value of an expression\cr
+c &continue running your program\cr
+n &next line, stepping over function calls\cr
+s &next line, stepping into function calls\cr
+\endsec
+
+\sec Starting GDB;
+gdb&start GDB, with no debugging files\cr
+gdb {\it program}&begin debugging {\it program}\cr
+gdb {\it program core}&debug coredump {\it core} produced by {\it
+program}\cr
+gdb --help&describe command line options\cr
+\endsec
+
+\sec Stopping GDB;
+quit&exit GDB; also {\tt q} or {\tt EOF} (eg \ctl{d})\cr
+INTERRUPT&(eg \ctl{c}) terminate current command, or send to running process\cr
+\endsec
+
+\sec Getting Help;
+help&list classes of commands\cr
+help {\it class}&one-line descriptions for commands in {\it class}\cr
+help {\it command}&describe {\it command}\cr
+\endsec
+
+\sec Executing your Program;
+run {\it arglist}&start your program with {\it arglist}\cr
+run&start your program with current argument list\cr
+run $\ldots$ <{\it inf} >{\it outf}&start your program with input, output
+redirected\cr
+\cr
+kill&kill running program\cr
+\cr
+tty {\it dev}&use {\it dev} as stdin and stdout for next {\tt run}\cr
+set args {\it arglist}&specify {\it arglist} for next
+{\tt run}\cr
+set args&specify empty argument list\cr
+show args&display argument list\cr
+\cr
+show env&show all environment variables\cr
+show env {\it var}&show value of environment variable {\it var}\cr
+set env {\it var} {\it string}&set environment variable {\it var}\cr
+unset env {\it var}&remove {\it var} from environment\cr
+\endsec
+
+\sec Shell Commands;
+cd {\it dir}&change working directory to {\it dir}\cr
+pwd&Print working directory\cr
+make $\ldots$&call ``{\tt make}''\cr
+shell {\it cmd}&execute arbitrary shell command string\cr
+\endsec
+
+\vfill
+\line{\smrm \opt{ } surround optional arguments \hfill $\ldots$ show
+one or more arguments}
+\vskip\baselineskip
+\centerline{\smrm \copyright 1998 Free Software Foundation, Inc.\qquad Permissions on back}
+\eject
+\sec Breakpoints and Watchpoints;
+break \opt{\it file\tt:}{\it line}\par
+b \opt{\it file\tt:}{\it line}&set breakpoint at {\it line} number \opt{in \it file}\par 
+eg:\quad{\tt break main.c:37}\quad\cr
+break \opt{\it file\tt:}{\it func}&set breakpoint at {\it
+func} \opt{in \it file}\cr
+break +{\it offset}\par
+break -{\it offset}&set break at {\it offset} lines from current stop\cr
+break *{\it addr}&set breakpoint at address {\it addr}\cr
+break&set breakpoint at next instruction\cr
+break $\ldots$ if {\it expr}&break conditionally on nonzero {\it expr}\cr
+cond {\it n} \opt{\it expr}&new conditional expression on breakpoint
+{\it n}; make unconditional if no {\it expr}\cr
+tbreak $\ldots$&temporary break; disable when reached\cr
+rbreak {\it regex}&break on all functions matching {\it regex}\cr
+watch {\it expr}&set a watchpoint for expression {\it expr}\cr
+catch {\it event}&break at {\it event}, which may be {\tt catch}, {\tt throw},
+{\tt exec}, {\tt fork}, {\tt vfork}, {\tt load}, or {\tt unload}.\cr
+\cr
+info break&show defined breakpoints\cr
+info watch&show defined watchpoints\cr
+\cr
+clear&delete breakpoints at next instruction\cr
+clear \opt{\it file\tt:}{\it fun}&delete breakpoints at entry to {\it fun}()\cr
+clear \opt{\it file\tt:}{\it line}&delete breakpoints on source line \cr
+delete \opt{{\it n}}&delete breakpoints
+\opt{or breakpoint {\it n}}\cr
+\cr
+disable \opt{{\it n}}&disable breakpoints
+\opt{or breakpoint {\it n}}
+\cr
+enable \opt{{\it n}}&enable breakpoints 
+\opt{or breakpoint {\it n}}
+\cr
+enable once \opt{{\it n}}&enable breakpoints \opt{or breakpoint {\it n}}; 
+disable again when reached
+\cr
+enable del \opt{{\it n}}&enable breakpoints \opt{or breakpoint {\it n}}; 
+delete when reached
+\cr
+\cr
+ignore {\it n} {\it count}&ignore breakpoint {\it n}, {\it count}
+times\cr
+\cr
+commands {\it n}\par
+\qquad \opt{\tt silent}\par
+\qquad {\it command-list}&execute GDB {\it command-list} every time breakpoint {\it n} is reached. \opt{{\tt silent} suppresses default
+display}\cr
+end&end of {\it command-list}\cr
+\endsec
+
+\sec Program Stack;
+backtrace \opt{\it n}\par
+bt \opt{\it n}&print trace of all frames in stack; or of {\it n}
+frames---innermost if {\it n}{\tt >0}, outermost if {\it n}{\tt <0}\cr
+frame \opt{\it n}&select frame number {\it n} or frame at address {\it
+n}; if no {\it n}, display current frame\cr
+up {\it n}&select frame {\it n} frames up\cr
+down {\it n}&select frame {\it n} frames down\cr
+info frame \opt{\it addr}&describe selected frame, or frame at
+{\it addr}\cr
+info args&arguments of selected frame\cr
+info locals&local variables of selected frame\cr
+info reg \opt{\it rn}$\ldots$\par
+info all-reg \opt{\it rn}&register values \opt{for regs {\it rn\/}} in
+selected frame; {\tt all-reg} includes floating point\cr
+\endsec
+
+\vfill\eject
+\sec Execution Control;
+continue \opt{\it count}\par
+c \opt{\it count}&continue running; if {\it count} specified, ignore
+this breakpoint next {\it count} times\cr
+\cr
+step \opt{\it count}\par
+s \opt{\it count}&execute until another line reached; repeat {\it count} times if
+specified\cr
+stepi \opt{\it count}\par
+si \opt{\it count}&step by machine instructions rather than source
+lines\cr
+\cr
+next \opt{\it count}\par
+n \opt{\it count}&execute next line, including any function calls\cr
+nexti \opt{\it count}\par
+ni \opt{\it count}&next machine instruction rather than source
+line\cr
+\cr
+until \opt{\it location}&run until next instruction (or {\it
+location})\cr
+finish&run until selected stack frame returns\cr
+return \opt{\it expr}&pop selected stack frame without executing
+\opt{setting return value}\cr
+signal {\it num}&resume execution with signal {\it s} (none if {\tt 0})\cr
+jump {\it line}\par
+jump *{\it address}&resume execution at specified {\it line} number or
+{\it address}\cr
+set var={\it expr}&evaluate {\it expr} without displaying it; use for
+altering program variables\cr
+\endsec
+
+\sec Display;
+print \opt{\tt/{\it f}\/} \opt{\it expr}\par
+p \opt{\tt/{\it f}\/} \opt{\it expr}&show value of {\it expr} \opt{or
+last value \tt \$} according to format {\it f}:\cr
+\qquad x&hexadecimal\cr
+\qquad d&signed decimal\cr
+\qquad u&unsigned decimal\cr
+\qquad o&octal\cr
+\qquad t&binary\cr
+\qquad a&address, absolute and relative\cr
+\qquad c&character\cr
+\qquad f&floating point\cr
+call \opt{\tt /{\it f}\/} {\it expr}&like {\tt print} but does not display
+{\tt void}\cr
+x \opt{\tt/{\it Nuf}\/} {\it expr}&examine memory at address {\it expr};
+optional format spec follows slash\cr
+\quad {\it N}&count of how many units to display\cr
+\quad {\it u}&unit size; one of\cr
+&{\tt\qquad b}\ individual bytes\cr
+&{\tt\qquad h}\ halfwords (two bytes)\cr
+&{\tt\qquad w}\ words (four bytes)\cr
+&{\tt\qquad g}\ giant words (eight bytes)\cr
+\quad {\it f}&printing format.  Any {\tt print} format, or\cr
+&{\tt\qquad s}\ null-terminated string\cr
+&{\tt\qquad i}\ machine instructions\cr
+disassem \opt{\it addr}&display memory as machine instructions\cr
+\endsec
+
+\sec Automatic Display;
+display \opt{\tt/\it f\/} {\it expr}&show value of {\it expr} each time
+program stops \opt{according to format {\it f}\/}\cr
+display&display all enabled expressions on list\cr
+undisplay {\it n}&remove number(s) {\it n} from list of
+automatically displayed expressions\cr
+disable disp {\it n}&disable display for expression(s) number {\it
+n}\cr
+enable disp {\it n}&enable display for expression(s) number {\it
+n}\cr
+info display&numbered list of display expressions\cr
+\endsec
+
+\vfill\eject
+
+\sec Expressions;
+{\it expr}&an expression in C, C++, or Modula-2 (including function calls), or:\cr
+{\it addr\/}@{\it len}&an array of {\it len} elements beginning at {\it
+addr}\cr
+{\it file}::{\it nm}&a variable or function {\it nm} defined in {\it
+file}\cr
+$\tt\{${\it type}$\tt\}${\it addr}&read memory at {\it addr} as specified
+{\it type}\cr
+\$&most recent displayed value\cr
+\${\it n}&{\it n}th displayed value\cr
+\$\$&displayed value previous to \$\cr
+\$\${\it n}&{\it n}th displayed value back from \$\cr
+\$\_&last address examined with {\tt x}\cr
+\$\_\_&value at address \$\_\cr
+\${\it var}&convenience variable; assign any value\cr
+\cr
+show values \opt{{\it n}}&show last 10 values \opt{or surrounding
+\${\it n}}\cr
+show conv&display all convenience variables\cr
+\endsec
+
+\sec Symbol Table;
+info address {\it s}&show where symbol {\it s} is stored\cr
+info func \opt{\it regex}&show names, types of defined functions
+(all, or matching {\it regex})\cr
+info var \opt{\it regex}&show names, types of global variables (all,
+or matching {\it regex})\cr
+whatis \opt{\it expr}\par
+ptype \opt{\it expr}&show data type of {\it expr} \opt{or \tt \$}
+without evaluating; {\tt ptype} gives more detail\cr
+ptype {\it type}&describe type, struct, union, or enum\cr
+\endsec
+
+\sec GDB Scripts;
+source {\it script}&read, execute GDB commands from file {\it
+script}\cr
+\cr
+define {\it cmd}\par
+\qquad {\it command-list}&create new GDB command {\it cmd}; 
+execute script defined by {\it command-list}\cr
+end&end of {\it command-list}\cr
+document {\it cmd}\par
+\qquad {\it help-text}&create online documentation 
+for new GDB command {\it cmd}\cr
+end&end of {\it help-text}\cr
+\endsec
+
+\sec Signals;
+handle {\it signal} {\it act}&specify GDB actions for {\it signal}:\cr
+\quad print&announce signal\cr
+\quad noprint&be silent for signal\cr
+\quad stop&halt execution on signal\cr
+\quad nostop&do not halt execution\cr
+\quad pass&allow your program to handle signal\cr
+\quad nopass&do not allow your program to see signal\cr
+info signals&show table of signals, GDB action for each\cr
+\endsec
+
+\sec Debugging Targets;
+target {\it type} {\it param}&connect to target machine, process, or file\cr
+help target&display available targets\cr
+attach {\it param}&connect to another process\cr
+detach&release target from GDB control\cr
+\endsec
+
+\vfill\eject
+\sec Controlling GDB;
+set {\it param} {\it value}&set one of GDB's internal parameters\cr
+show {\it param}&display current setting of parameter\cr
+\xtra{\rm Parameters understood by {\tt set} and {\tt show}:}
+\quad complaint {\it limit}&number of messages on unusual symbols\cr
+\quad confirm {\it on/off}&enable or disable cautionary queries\cr
+\quad editing {\it on/off}&control {\tt readline} command-line editing\cr
+\quad height {\it lpp}&number of lines before pause in display\cr
+\quad language {\it lang}&Language for GDB expressions ({\tt auto}, {\tt c} or
+{\tt modula-2})\cr
+\quad listsize {\it n}&number of lines shown by {\tt list}\cr
+\quad prompt {\it str}&use {\it str} as GDB prompt\cr
+\quad radix {\it base}&octal, decimal, or hex number representation\cr
+\quad verbose {\it on/off}&control messages when loading
+symbols\cr
+\quad width {\it cpl}&number of characters before line folded\cr
+\quad write {\it on/off}&Allow or forbid patching binary, core files
+(when reopened with {\tt exec} or {\tt core})
+\cr
+\quad history $\ldots$\par
+\quad h $\ldots$&groups with the following options:\cr
+\quad h exp {\it off/on}&disable/enable {\tt readline} history expansion\cr
+\quad h file {\it filename}&file for recording GDB command history\cr
+\quad h size {\it size}&number of commands kept in history list\cr
+\quad h save {\it off/on}&control use of external file for
+command history\cr
+\cr
+\quad print $\ldots$\par
+\quad p $\ldots$&groups with the following options:\cr
+\quad p address {\it on/off}&print memory addresses in stacks,
+values\cr
+\quad p  array {\it off/on}&compact or attractive format for
+arrays\cr
+\quad p demangl {\it on/off}&source (demangled) or internal form for C++
+symbols\cr
+\quad p asm-dem {\it on/off}&demangle C++ symbols in
+machine-instruction output\cr
+\quad p elements {\it limit}&number of array elements to display\cr
+\quad p object {\it on/off}&print C++ derived types for objects\cr
+\quad p pretty {\it off/on}&struct display: compact or indented\cr
+\quad p union {\it on/off}&display of union members\cr
+\quad p vtbl {\it off/on}&display of C++ virtual function
+tables\cr
+\cr
+show commands&show last 10 commands\cr
+show commands {\it n}&show 10 commands around number {\it n}\cr
+show commands +&show next 10 commands\cr
+\endsec
+
+\sec Working Files;
+file \opt{\it file}&use {\it file} for both symbols and executable;
+with no arg, discard both\cr
+core \opt{\it file}&read {\it file} as coredump; or discard\cr
+exec \opt{\it file}&use {\it file} as executable only; or discard\cr
+symbol \opt{\it file}&use symbol table from {\it file}; or discard\cr
+load {\it file}&dynamically link {\it file\/} and add its symbols\cr
+add-sym {\it file} {\it addr}&read additional symbols from {\it file},
+dynamically loaded at {\it addr}\cr
+info files&display working files and targets in use\cr
+path {\it dirs}&add {\it dirs} to front of path searched for
+executable and symbol files\cr
+show path&display executable and symbol file path\cr
+info share&list names of shared libraries currently loaded\cr
+\endsec
+
+\vfill\eject
+\sec Source Files;
+dir {\it names}&add directory {\it names} to front of source path\cr
+dir&clear source path\cr
+show dir&show current source path\cr
+\cr
+list&show next ten lines of source\cr
+list -&show previous ten lines\cr
+list {\it lines}&display source surrounding {\it lines}, 
+specified as:\cr
+\quad{\opt{\it file\tt:}\it num}&line number \opt{in named file}\cr
+\quad{\opt{\it file\tt:}\it function}&beginning of function \opt{in
+named file}\cr
+\quad{\tt +\it off}&{\it off} lines after last printed\cr
+\quad{\tt -\it off}&{\it off} lines previous to last printed\cr
+\quad{\tt*\it address}&line containing {\it address}\cr
+list {\it f},{\it l}&from line {\it f} to line {\it l}\cr
+info line {\it num}&show starting, ending addresses of compiled code for
+source line {\it num}\cr
+info source&show name of current source file\cr
+info sources&list all source files in use\cr
+forw {\it regex}&search following source lines for {\it regex}\cr
+rev {\it regex}&search preceding source lines for {\it regex}\cr
+\endsec
+
+\sec GDB under GNU Emacs;
+M-x gdb&run GDB under Emacs\cr
+\ctl{h} m&describe GDB mode\cr
+M-s&step one line ({\tt step})\cr
+M-n&next line ({\tt next})\cr
+M-i&step one instruction ({\tt stepi})\cr
+\ctl{c} \ctl{f}&finish current stack frame ({\tt finish})\cr
+M-c&continue ({\tt cont})\cr
+M-u&up {\it arg} frames ({\tt up})\cr
+M-d&down {\it arg} frames ({\tt down})\cr
+\ctl{x} \&&copy number from point, insert at end\cr
+\ctl{x} SPC&(in source file) set break at point\cr
+\endsec
+
+\sec GDB License;
+show copying&Display GNU General Public License\cr
+show warranty&There is NO WARRANTY for GDB.  Display full no-warranty
+statement.\cr 
+\endsec
+
+
+\vfill
+{\smrm\parskip=6pt
+\centerline{Copyright \copyright 1991, '92, '93, '98 Free Software Foundation, Inc.}
+\centerline{Roland H. Pesch}
+\centerline{The author assumes no responsibility for any errors on this card.}
+
+This card may be freely distributed under the terms of the GNU
+General Public License.
+
+\centerline{Please contribute to development of this card by
+annotating it.  Improvements can be sent to bug-gdb@gnu.org.}
+
+GDB itself is free software; you are welcome to distribute copies of
+it under the terms of the GNU General Public License.  There is
+absolutely no warranty for GDB.
+}
+\end
diff --git a/gdb/doc/remote.texi b/gdb/doc/remote.texi
new file mode 100644
index 0000000000..816b65837d
--- /dev/null
+++ b/gdb/doc/remote.texi
@@ -0,0 +1,1708 @@
+@c								-*- Texinfo -*-
+@c Copyright (c) 1990 1991 1992 1993 Free Software Foundation, Inc.
+@c This file is part of the source for the GDB manual.
+@c This text diverted to "Remote Debugging" section in general case;
+@c however, if we're doing a manual specifically for one of these, it
+@c belongs up front (in "Getting In and Out" chapter).
+
+@ifset REMOTESTUB
+@node Remote Serial
+@subsection The @value{GDBN} remote serial protocol
+
+@cindex remote serial debugging, overview
+To debug a program running on another machine (the debugging
+@dfn{target} machine), you must first arrange for all the usual
+prerequisites for the program to run by itself.  For example, for a C
+program, you need:
+
+@enumerate
+@item
+A startup routine to set up the C runtime environment; these usually
+have a name like @file{crt0}.  The startup routine may be supplied by
+your hardware supplier, or you may have to write your own.
+
+@item 
+You probably need a C subroutine library to support your program's
+subroutine calls, notably managing input and output.
+
+@item
+A way of getting your program to the other machine---for example, a
+download program.  These are often supplied by the hardware
+manufacturer, but you may have to write your own from hardware
+documentation.
+@end enumerate
+
+The next step is to arrange for your program to use a serial port to
+communicate with the machine where @value{GDBN} is running (the @dfn{host}
+machine).  In general terms, the scheme looks like this:
+
+@table @emph
+@item On the host,
+@value{GDBN} already understands how to use this protocol; when everything
+else is set up, you can simply use the @samp{target remote} command
+(@pxref{Targets,,Specifying a Debugging Target}).
+
+@item On the target,
+you must link with your program a few special-purpose subroutines that
+implement the @value{GDBN} remote serial protocol.  The file containing these
+subroutines is called  a @dfn{debugging stub}.
+
+@ifset GDBSERVER
+On certain remote targets, you can use an auxiliary program
+@code{gdbserver} instead of linking a stub into your program.
+@xref{Server,,Using the @code{gdbserver} program}, for details.
+@end ifset
+@end table
+
+The debugging stub is specific to the architecture of the remote
+machine; for example, use @file{sparc-stub.c} to debug programs on
+@sc{sparc} boards.
+
+@cindex remote serial stub list
+These working remote stubs are distributed with @value{GDBN}:
+
+@table @code
+
+@item i386-stub.c
+@kindex i386-stub.c
+@cindex Intel
+@cindex i386
+For Intel 386 and compatible architectures.
+
+@item m68k-stub.c
+@kindex m68k-stub.c
+@cindex Motorola 680x0
+@cindex m680x0
+For Motorola 680x0 architectures.
+
+@item sh-stub.c
+@kindex sh-stub.c
+@cindex Hitachi
+@cindex SH
+For Hitachi SH architectures.
+
+@item sparc-stub.c
+@kindex sparc-stub.c
+@cindex Sparc
+For @sc{sparc} architectures.
+
+@item sparcl-stub.c
+@kindex sparcl-stub.c
+@cindex Fujitsu
+@cindex SparcLite
+For Fujitsu @sc{sparclite} architectures.
+
+@end table
+
+The @file{README} file in the @value{GDBN} distribution may list other
+recently added stubs.
+
+@menu
+* Stub Contents::       What the stub can do for you
+* Bootstrapping::       What you must do for the stub
+* Debug Session::       Putting it all together
+* Protocol::            Outline of the communication protocol
+@ifset GDBSERVER
+* Server::		Using the `gdbserver' program
+@end ifset
+@ifset GDBSERVE
+* NetWare::		Using the `gdbserve.nlm' program
+@end ifset
+@end menu
+
+@node Stub Contents
+@subsubsection What the stub can do for you
+
+@cindex remote serial stub
+The debugging stub for your architecture supplies these three
+subroutines:
+
+@table @code
+@item set_debug_traps
+@kindex set_debug_traps
+@cindex remote serial stub, initialization
+This routine arranges for @code{handle_exception} to run when your
+program stops.  You must call this subroutine explicitly near the
+beginning of your program.
+
+@item handle_exception
+@kindex handle_exception
+@cindex remote serial stub, main routine
+This is the central workhorse, but your program never calls it
+explicitly---the setup code arranges for @code{handle_exception} to
+run when a trap is triggered.
+
+@code{handle_exception} takes control when your program stops during
+execution (for example, on a breakpoint), and mediates communications
+with @value{GDBN} on the host machine.  This is where the communications
+protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
+representative on the target machine; it begins by sending summary
+information on the state of your program, then continues to execute,
+retrieving and transmitting any information @value{GDBN} needs, until you
+execute a @value{GDBN} command that makes your program resume; at that point,
+@code{handle_exception} returns control to your own code on the target
+machine. 
+
+@item breakpoint
+@cindex @code{breakpoint} subroutine, remote
+Use this auxiliary subroutine to make your program contain a
+breakpoint.  Depending on the particular situation, this may be the only
+way for @value{GDBN} to get control.  For instance, if your target
+machine has some sort of interrupt button, you won't need to call this;
+pressing the interrupt button transfers control to
+@code{handle_exception}---in effect, to @value{GDBN}.  On some machines,
+simply receiving characters on the serial port may also trigger a trap;
+again, in that situation, you don't need to call @code{breakpoint} from
+your own program---simply running @samp{target remote} from the host
+@value{GDBN} session gets control.  
+
+Call @code{breakpoint} if none of these is true, or if you simply want
+to make certain your program stops at a predetermined point for the
+start of your debugging session.
+@end table
+
+@node Bootstrapping
+@subsubsection What you must do for the stub
+
+@cindex remote stub, support routines
+The debugging stubs that come with @value{GDBN} are set up for a particular
+chip architecture, but they have no information about the rest of your
+debugging target machine.
+
+First of all you need to tell the stub how to communicate with the
+serial port.
+
+@table @code
+@item int getDebugChar()
+@kindex getDebugChar
+Write this subroutine to read a single character from the serial port.
+It may be identical to @code{getchar} for your target system; a
+different name is used to allow you to distinguish the two if you wish.
+
+@item void putDebugChar(int)
+@kindex putDebugChar
+Write this subroutine to write a single character to the serial port.
+It may be identical to @code{putchar} for your target system; a 
+different name is used to allow you to distinguish the two if you wish.
+@end table
+
+@cindex control C, and remote debugging
+@cindex interrupting remote targets
+If you want @value{GDBN} to be able to stop your program while it is
+running, you need to use an interrupt-driven serial driver, and arrange
+for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
+character).  That is the character which @value{GDBN} uses to tell the
+remote system to stop.
+
+Getting the debugging target to return the proper status to @value{GDBN}
+probably requires changes to the standard stub; one quick and dirty way
+is to just execute a breakpoint instruction (the ``dirty'' part is that
+@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
+
+Other routines you need to supply are:
+
+@table @code
+@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
+@kindex exceptionHandler
+Write this function to install @var{exception_address} in the exception
+handling tables.  You need to do this because the stub does not have any
+way of knowing what the exception handling tables on your target system
+are like (for example, the processor's table might be in @sc{rom},
+containing entries which point to a table in @sc{ram}).
+@var{exception_number} is the exception number which should be changed;
+its meaning is architecture-dependent (for example, different numbers
+might represent divide by zero, misaligned access, etc).  When this
+exception occurs, control should be transferred directly to
+@var{exception_address}, and the processor state (stack, registers,
+and so on) should be just as it is when a processor exception occurs.  So if
+you want to use a jump instruction to reach @var{exception_address}, it
+should be a simple jump, not a jump to subroutine.
+
+For the 386, @var{exception_address} should be installed as an interrupt
+gate so that interrupts are masked while the handler runs.  The gate
+should be at privilege level 0 (the most privileged level).  The
+@sc{sparc} and 68k stubs are able to mask interrup themselves without
+help from @code{exceptionHandler}.
+
+@item void flush_i_cache()
+@kindex flush_i_cache
+(sparc and sparclite only) Write this subroutine to flush the
+instruction cache, if any, on your target machine.  If there is no
+instruction cache, this subroutine may be a no-op.
+
+On target machines that have instruction caches, @value{GDBN} requires this
+function to make certain that the state of your program is stable.
+@end table
+
+@noindent
+You must also make sure this library routine is available:
+
+@table @code
+@item void *memset(void *, int, int)
+@kindex memset
+This is the standard library function @code{memset} that sets an area of
+memory to a known value.  If you have one of the free versions of
+@code{libc.a}, @code{memset} can be found there; otherwise, you must
+either obtain it from your hardware manufacturer, or write your own.
+@end table
+
+If you do not use the GNU C compiler, you may need other standard
+library subroutines as well; this varies from one stub to another,
+but in general the stubs are likely to use any of the common library
+subroutines which @code{gcc} generates as inline code.
+
+
+@node Debug Session
+@subsubsection Putting it all together
+
+@cindex remote serial debugging summary
+In summary, when your program is ready to debug, you must follow these
+steps.
+
+@enumerate
+@item
+Make sure you have the supporting low-level routines
+(@pxref{Bootstrapping,,What you must do for the stub}):
+@display
+@code{getDebugChar}, @code{putDebugChar},
+@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
+@end display
+
+@item
+Insert these lines near the top of your program:
+
+@example
+set_debug_traps();
+breakpoint();
+@end example
+
+@item
+For the 680x0 stub only, you need to provide a variable called
+@code{exceptionHook}.  Normally you just use:
+
+@example
+void (*exceptionHook)() = 0;
+@end example
+
+but if before calling @code{set_debug_traps}, you set it to point to a
+function in your program, that function is called when
+@code{@value{GDBN}} continues after stopping on a trap (for example, bus
+error).  The function indicated by @code{exceptionHook} is called with
+one parameter: an @code{int} which is the exception number.
+
+@item
+Compile and link together: your program, the @value{GDBN} debugging stub for
+your target architecture, and the supporting subroutines.
+
+@item
+Make sure you have a serial connection between your target machine and
+the @value{GDBN} host, and identify the serial port on the host.
+
+@item
+@c The "remote" target now provides a `load' command, so we should
+@c document that.  FIXME.
+Download your program to your target machine (or get it there by
+whatever means the manufacturer provides), and start it.
+
+@item
+To start remote debugging, run @value{GDBN} on the host machine, and specify
+as an executable file the program that is running in the remote machine.
+This tells @value{GDBN} how to find your program's symbols and the contents
+of its pure text.
+
+@cindex serial line, @code{target remote}
+Then establish communication using the @code{target remote} command.
+Its argument specifies how to communicate with the target
+machine---either via a devicename attached to a direct serial line, or a
+TCP port (usually to a terminal server which in turn has a serial line
+to the target).  For example, to use a serial line connected to the
+device named @file{/dev/ttyb}:
+
+@example
+target remote /dev/ttyb
+@end example
+
+@cindex TCP port, @code{target remote}
+To use a TCP connection, use an argument of the form
+@code{@var{host}:port}.  For example, to connect to port 2828 on a
+terminal server named @code{manyfarms}:
+
+@example
+target remote manyfarms:2828
+@end example
+@end enumerate
+
+Now you can use all the usual commands to examine and change data and to
+step and continue the remote program.
+
+To resume the remote program and stop debugging it, use the @code{detach}
+command.
+
+@cindex interrupting remote programs
+@cindex remote programs, interrupting
+Whenever @value{GDBN} is waiting for the remote program, if you type the
+interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
+program.  This may or may not succeed, depending in part on the hardware
+and the serial drivers the remote system uses.  If you type the
+interrupt character once again, @value{GDBN} displays this prompt:
+
+@example
+Interrupted while waiting for the program.
+Give up (and stop debugging it)?  (y or n)
+@end example
+
+If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
+(If you decide you want to try again later, you can use @samp{target
+remote} again to connect once more.)  If you type @kbd{n}, @value{GDBN}
+goes back to waiting.
+
+@node Protocol
+@subsubsection Communication protocol
+
+@cindex debugging stub, example
+@cindex remote stub, example
+@cindex stub example, remote debugging
+The stub files provided with @value{GDBN} implement the target side of the
+communication protocol, and the @value{GDBN} side is implemented in the
+@value{GDBN} source file @file{remote.c}.  Normally, you can simply allow
+these subroutines to communicate, and ignore the details.  (If you're
+implementing your own stub file, you can still ignore the details: start
+with one of the existing stub files.  @file{sparc-stub.c} is the best
+organized, and therefore the easiest to read.)
+
+However, there may be occasions when you need to know something about
+the protocol---for example, if there is only one serial port to your
+target machine, you might want your program to do something special if
+it recognizes a packet meant for @value{GDBN}.
+
+@cindex protocol, @value{GDBN} remote serial
+@cindex serial protocol, @value{GDBN} remote
+@cindex remote serial protocol
+All @value{GDBN} commands and responses (other than acknowledgements, which
+are single characters) are sent as a packet which includes a
+checksum.  A packet is introduced with the character @samp{$}, and ends
+with the character @samp{#} followed by a two-digit checksum:
+
+@example
+$@var{packet info}#@var{checksum}
+@end example
+
+@cindex checksum, for @value{GDBN} remote
+@noindent
+@var{checksum} is computed as the modulo 256 sum of the @var{packet
+info} characters.
+
+When either the host or the target machine receives a packet, the first
+response expected is an acknowledgement: a single character, either
+@samp{+} (to indicate the package was received correctly) or @samp{-}
+(to request retransmission).
+
+The host (@value{GDBN}) sends commands, and the target (the debugging stub
+incorporated in your program) sends data in response.  The target also
+sends data when your program stops.
+
+Command packets are distinguished by their first character, which
+identifies the kind of command.
+
+These are some of the commands currently supported (for a complete list of 
+commands, look in @file{gdb/remote.c.}):
+
+@table @code
+@item g
+Requests the values of CPU registers.
+
+@item G
+Sets the values of CPU registers.
+
+@item m@var{addr},@var{count}
+Read @var{count} bytes at location @var{addr}.
+
+@item M@var{addr},@var{count}:@dots{}
+Write @var{count} bytes at location @var{addr}.
+
+@need 500
+@item c
+@itemx c@var{addr}
+Resume execution at the current address (or at @var{addr} if supplied).
+
+@need 500
+@item s
+@itemx s@var{addr}
+Step the target program for one instruction, from either the current
+program counter or from @var{addr} if supplied.
+
+@item k
+Kill the target program.
+
+@item ?
+Report the most recent signal.  To allow you to take advantage of the
+@value{GDBN} signal handling commands, one of the functions of the debugging
+stub is to report CPU traps as the corresponding POSIX signal values.
+
+@item T
+Allows the remote stub to send only the registers that @value{GDBN} needs
+to make a quick decision about single-stepping or conditional breakpoints.
+This eliminates the need to fetch the entire register set for each instruction
+being stepped through.
+
+@value{GDBN} now implements a write-through cache for registers and only
+re-reads the registers if the target has run.
+@end table
+
+@kindex set remotedebug
+@kindex show remotedebug
+@cindex packets, reporting on stdout
+@cindex serial connections, debugging
+If you have trouble with the serial connection, you can use the command
+@code{set remotedebug}.  This makes @value{GDBN} report on all packets sent
+back and forth across the serial line to the remote machine.  The
+packet-debugging information is printed on the @value{GDBN} standard output
+stream.  @code{set remotedebug off} turns it off, and @code{show
+remotedebug} shows you its current state.
+
+@ifset GDBSERVER
+@node Server
+@subsubsection Using the @code{gdbserver} program
+
+@kindex gdbserver
+@cindex remote connection without stubs
+@code{gdbserver} is a control program for Unix-like systems, which
+allows you to connect your program with a remote @value{GDBN} via
+@code{target remote}---but without linking in the usual debugging stub.
+
+@code{gdbserver} is not a complete replacement for the debugging stubs,
+because it requires essentially the same operating-system facilities
+that @value{GDBN} itself does.  In fact, a system that can run
+@code{gdbserver} to connect to a remote @value{GDBN} could also run
+@value{GDBN} locally!  @code{gdbserver} is sometimes useful nevertheless,
+because it is a much smaller program than @value{GDBN} itself.  It is
+also easier to port than all of @value{GDBN}, so you may be able to get
+started more quickly on a new system by using @code{gdbserver}.
+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} to make a similar
+choice for debugging.
+
+@value{GDBN} and @code{gdbserver} communicate via either a serial line
+or a TCP connection, using the standard @value{GDBN} remote serial
+protocol.
+
+@table @emph
+@item On the target machine,
+you need to have a copy of the program you want to debug.
+@code{gdbserver} does not need your program's symbol table, so you can
+strip the program if necessary to save space.  @value{GDBN} on the host
+system does all the symbol handling.
+
+To use the server, you must tell it how to communicate with @value{GDBN};
+the name of your program; and the arguments for your program.  The
+syntax is:
+
+@smallexample
+target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
+@end smallexample
+
+@var{comm} is either a device name (to use a serial line) or a TCP
+hostname and portnumber.  For example, to debug Emacs with the argument
+@samp{foo.txt} and communicate with @value{GDBN} over the serial port
+@file{/dev/com1}:
+
+@smallexample
+target> gdbserver /dev/com1 emacs foo.txt
+@end smallexample
+
+@code{gdbserver} waits passively for the host @value{GDBN} to communicate
+with it.
+
+To use a TCP connection instead of a serial line:
+
+@smallexample
+target> gdbserver host:2345 emacs foo.txt
+@end smallexample
+
+The only difference from the previous example is the first argument,
+specifying that you are communicating with the host @value{GDBN} via
+TCP.  The @samp{host:2345} argument means that @code{gdbserver} is to
+expect a TCP connection from machine @samp{host} to local TCP port 2345.
+(Currently, the @samp{host} 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} is
+reserved for @code{telnet}).@footnote{If you choose a port number that
+conflicts with another service, @code{gdbserver} prints an error message
+and exits.} You must use the same port number with the host @value{GDBN}
+@code{target remote} command.
+
+@item On the @value{GDBN} host machine,
+you need an unstripped copy of your program, since @value{GDBN} needs
+symbols and debugging information.  Start up @value{GDBN} as usual,
+using the name of the local copy of your program as the first argument.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600 bps.)  After that, use @code{target
+remote} to establish communications with @code{gdbserver}.  Its argument
+is either a device name (usually a serial device, like
+@file{/dev/ttyb}), or a TCP port descriptor in the form
+@code{@var{host}:@var{PORT}}.  For example:
+
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
+
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and
+
+@smallexample
+(@value{GDBP}) target remote the-target:2345
+@end smallexample
+
+@noindent
+communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
+For TCP connections, you must start up @code{gdbserver} prior to using
+the @code{target remote} command.  Otherwise you may get an error whose
+text depends on the host system, but which usually looks something like
+@samp{Connection refused}.
+@end table
+@end ifset
+
+@ifset GDBSERVE
+@node NetWare
+@subsubsection Using the @code{gdbserve.nlm} program
+
+@kindex gdbserve.nlm
+@code{gdbserve.nlm} is a control program for NetWare systems, which
+allows you to connect your program with a remote @value{GDBN} via
+@code{target remote}.
+
+@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
+using the standard @value{GDBN} remote serial protocol.
+
+@table @emph
+@item On the target machine,
+you need to have a copy of the program you want to debug.
+@code{gdbserve.nlm} does not need your program's symbol table, so you
+can strip the program if necessary to save space.  @value{GDBN} on the
+host system does all the symbol handling.
+
+To use the server, you must tell it how to communicate with
+@value{GDBN}; the name of your program; and the arguments for your
+program.  The syntax is:
+
+@smallexample 
+load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
+              [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
+@end smallexample
+
+@var{board} and @var{port} specify the serial line; @var{baud} specifies
+the baud rate used by the connection.  @var{port} and @var{node} default
+to 0, @var{baud} defaults to 9600 bps.
+
+For example, to debug Emacs with the argument @samp{foo.txt}and
+communicate with @value{GDBN} over serial port number 2 or board 1 
+using a 19200 bps connection:
+
+@smallexample
+load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
+@end smallexample
+
+@item On the @value{GDBN} host machine,
+you need an unstripped copy of your program, since @value{GDBN} needs
+symbols and debugging information.  Start up @value{GDBN} as usual,
+using the name of the local copy of your program as the first argument.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600 bps.  After that, use @code{target
+remote} to establish communications with @code{gdbserve.nlm}.  Its
+argument is a device name (usually a serial device, like
+@file{/dev/ttyb}).  For example:
+
+@smallexample
+(@value{GDBP}) target remote /dev/ttyb
+@end smallexample
+
+@noindent
+communications with the server via serial line @file{/dev/ttyb}.
+@end table
+@end ifset
+
+@end ifset
+
+@ifset I960
+@node i960-Nindy Remote
+@subsection @value{GDBN} with a remote i960 (Nindy)
+
+@cindex Nindy
+@cindex i960
+@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems.  When
+@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
+tell @value{GDBN} how to connect to the 960 in several ways:
+
+@itemize @bullet
+@item
+Through command line options specifying serial port, version of the
+Nindy protocol, and communications speed;
+
+@item
+By responding to a prompt on startup;
+
+@item
+By using the @code{target} command at any point during your @value{GDBN}
+session.  @xref{Target Commands, ,Commands for managing targets}.
+
+@end itemize
+
+@menu
+* Nindy Startup::               Startup with Nindy
+* Nindy Options::               Options for Nindy
+* Nindy Reset::                 Nindy reset command
+@end menu
+
+@node Nindy Startup
+@subsubsection Startup with Nindy
+
+If you simply start @code{@value{GDBP}} without using any command-line
+options, you are prompted for what serial port to use, @emph{before} you
+reach the ordinary @value{GDBN} prompt:
+
+@example
+Attach /dev/ttyNN -- specify NN, or "quit" to quit:  
+@end example
+
+@noindent
+Respond to the prompt with whatever suffix (after @samp{/dev/tty})
+identifies the serial port you want to use.  You can, if you choose,
+simply start up with no Nindy connection by responding to the prompt
+with an empty line.  If you do this and later wish to attach to Nindy,
+use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
+
+@node Nindy Options
+@subsubsection Options for Nindy
+
+These are the startup options for beginning your @value{GDBN} session with a
+Nindy-960 board attached:
+
+@table @code
+@item -r @var{port}
+Specify the serial port name of a serial interface to be used to connect
+to the target system.  This option is only available when @value{GDBN} is
+configured for the Intel 960 target architecture.  You may specify
+@var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
+device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
+suffix for a specific @code{tty} (e.g. @samp{-r a}).
+
+@item -O
+(An uppercase letter ``O'', not a zero.)  Specify that @value{GDBN} should use
+the ``old'' Nindy monitor protocol to connect to the target system.
+This option is only available when @value{GDBN} is configured for the Intel 960
+target architecture.
+
+@quotation
+@emph{Warning:} if you specify @samp{-O}, but are actually trying to
+connect to a target system that expects the newer protocol, the connection
+fails, appearing to be a speed mismatch.  @value{GDBN} repeatedly
+attempts to reconnect at several different line speeds.  You can abort
+this process with an interrupt.
+@end quotation
+
+@item -brk
+Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
+system, in an attempt to reset it, before connecting to a Nindy target.
+
+@quotation
+@emph{Warning:} Many target systems do not have the hardware that this
+requires; it only works with a few boards.
+@end quotation
+@end table
+
+The standard @samp{-b} option controls the line speed used on the serial
+port.
+
+@c @group
+@node Nindy Reset
+@subsubsection Nindy reset command
+
+@table @code
+@item reset
+@kindex reset
+For a Nindy target, this command sends a ``break'' to the remote target
+system; this is only useful if the target has been equipped with a
+circuit to perform a hard reset (or some other interesting action) when
+a break is detected.
+@end table
+@c @end group
+@end ifset
+
+@ifset AMD29K
+@node UDI29K Remote
+@subsection The UDI protocol for AMD29K
+
+@cindex UDI
+@cindex AMD29K via UDI
+@value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
+protocol for debugging the a29k processor family.  To use this
+configuration with AMD targets running the MiniMON monitor, you need the
+program @code{MONTIP}, available from AMD at no charge.  You can also
+use @value{GDBN} with the UDI-conformant a29k simulator program
+@code{ISSTIP}, also available from AMD.
+
+@table @code
+@item target udi @var{keyword}
+@kindex udi
+Select the UDI interface to a remote a29k board or simulator, where
+@var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
+This file contains keyword entries which specify parameters used to
+connect to a29k targets.  If the @file{udi_soc} file is not in your
+working directory, you must set the environment variable @samp{UDICONF}
+to its pathname.
+@end table
+
+@node EB29K Remote
+@subsection The EBMON protocol for AMD29K
+
+@cindex EB29K board
+@cindex running 29K programs
+
+AMD distributes a 29K development board meant to fit in a PC, together
+with a DOS-hosted monitor program called @code{EBMON}.  As a shorthand
+term, this development system is called the ``EB29K''.  To use
+@value{GDBN} from a Unix system to run programs on the EB29K board, you
+must first connect a serial cable between the PC (which hosts the EB29K
+board) and a serial port on the Unix system.  In the following, we
+assume you've hooked the cable between the PC's @file{COM1} port and
+@file{/dev/ttya} on the Unix system.
+
+@menu
+* Comms (EB29K)::               Communications setup
+* gdb-EB29K::                   EB29K cross-debugging
+* Remote Log::                  Remote log
+@end menu
+
+@node Comms (EB29K)
+@subsubsection Communications setup
+
+The next step is to set up the PC's port, by doing something like this
+in DOS on the PC:
+
+@example
+C:\> MODE com1:9600,n,8,1,none
+@end example
+
+@noindent
+This example---run on an MS DOS 4.0 system---sets the PC port to 9600
+bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
+you must match the communications parameters when establishing the Unix
+end of the connection as well.
+@c FIXME: Who knows what this "no retry action" crud from the DOS manual may
+@c       mean?  It's optional; leave it out? ---doc@cygnus.com, 25feb91 
+
+To give control of the PC to the Unix side of the serial line, type
+the following at the DOS console:
+
+@example
+C:\> CTTY com1
+@end example
+
+@noindent
+(Later, if you wish to return control to the DOS console, you can use
+the command @code{CTTY con}---but you must send it over the device that
+had control, in our example over the @file{COM1} serial line).
+
+From the Unix host, use a communications program such as @code{tip} or
+@code{cu} to communicate with the PC; for example,
+
+@example
+cu -s 9600 -l /dev/ttya
+@end example
+
+@noindent
+The @code{cu} options shown specify, respectively, the linespeed and the
+serial port to use.  If you use @code{tip} instead, your command line
+may look something like the following:
+
+@example
+tip -9600 /dev/ttya
+@end example
+
+@noindent
+Your system may require a different name where we show
+@file{/dev/ttya} as the argument to @code{tip}.  The communications
+parameters, including which port to use, are associated with the
+@code{tip} argument in the ``remote'' descriptions file---normally the
+system table @file{/etc/remote}.
+@c FIXME: What if anything needs doing to match the "n,8,1,none" part of
+@c the DOS side's comms setup?  cu can support -o (odd
+@c parity), -e (even parity)---apparently no settings for no parity or
+@c for character size.  Taken from stty maybe...?  John points out tip
+@c can set these as internal variables, eg ~s parity=none; man stty
+@c suggests that it *might* work to stty these options with stdin or
+@c stdout redirected... ---doc@cygnus.com, 25feb91
+
+@kindex EBMON
+Using the @code{tip} or @code{cu} connection, change the DOS working
+directory to the directory containing a copy of your 29K program, then
+start the PC program @code{EBMON} (an EB29K control program supplied
+with your board by AMD).  You should see an initial display from
+@code{EBMON} similar to the one that follows, ending with the
+@code{EBMON} prompt @samp{#}---
+
+@example
+C:\> G:
+
+G:\> CD \usr\joe\work29k
+
+G:\USR\JOE\WORK29K> EBMON
+Am29000 PC Coprocessor Board Monitor, version 3.0-18
+Copyright 1990 Advanced Micro Devices, Inc.
+Written by Gibbons and Associates, Inc.
+
+Enter '?' or 'H' for help
+
+PC Coprocessor Type   = EB29K
+I/O Base              = 0x208
+Memory Base           = 0xd0000
+
+Data Memory Size      = 2048KB
+Available I-RAM Range = 0x8000 to 0x1fffff
+Available D-RAM Range = 0x80002000 to 0x801fffff
+
+PageSize              = 0x400
+Register Stack Size   = 0x800
+Memory Stack Size     = 0x1800
+
+CPU PRL               = 0x3
+Am29027 Available     = No
+Byte Write Available  = Yes
+
+# ~.
+@end example
+
+Then exit the @code{cu} or @code{tip} program (done in the example by
+typing @code{~.} at the @code{EBMON} prompt).  @code{EBMON} keeps
+running, ready for @value{GDBN} to take over.
+
+For this example, we've assumed what is probably the most convenient
+way to make sure the same 29K program is on both the PC and the Unix
+system: a PC/NFS connection that establishes ``drive @code{G:}'' on the
+PC as a file system on the Unix host.  If you do not have PC/NFS or
+something similar connecting the two systems, you must arrange some
+other way---perhaps floppy-disk transfer---of getting the 29K program
+from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
+serial line.
+
+@node gdb-EB29K
+@subsubsection EB29K cross-debugging
+
+Finally, @code{cd} to the directory containing an image of your 29K
+program on the Unix system, and start @value{GDBN}---specifying as argument the
+name of your 29K program:
+
+@example
+cd /usr/joe/work29k
+@value{GDBP} myfoo
+@end example
+
+@need 500
+Now you can use the @code{target} command:
+
+@example
+target amd-eb /dev/ttya 9600 MYFOO
+@c FIXME: test above 'target amd-eb' as spelled, with caps!  caps are meant to
+@c emphasize that this is the name as seen by DOS (since I think DOS is
+@c single-minded about case of letters).  ---doc@cygnus.com, 25feb91
+@end example
+
+@noindent
+In this example, we've assumed your program is in a file called
+@file{myfoo}.  Note that the filename given as the last argument to
+@code{target amd-eb} should be the name of the program as it appears to DOS.
+In our example this is simply @code{MYFOO}, but in general it can include
+a DOS path, and depending on your transfer mechanism may not resemble
+the name on the Unix side.
+
+At this point, you can set any breakpoints you wish; when you are ready
+to see your program run on the 29K board, use the @value{GDBN} command
+@code{run}.
+
+To stop debugging the remote program, use the @value{GDBN} @code{detach}
+command.
+
+To return control of the PC to its console, use @code{tip} or @code{cu}
+once again, after your @value{GDBN} session has concluded, to attach to
+@code{EBMON}.  You can then type the command @code{q} to shut down
+@code{EBMON}, returning control to the DOS command-line interpreter.
+Type @code{CTTY con} to return command input to the main DOS console,
+and type @kbd{~.} to leave @code{tip} or @code{cu}.
+
+@node Remote Log
+@subsubsection Remote log
+@kindex eb.log
+@cindex log file for EB29K
+
+The @code{target amd-eb} command creates a file @file{eb.log} in the
+current working directory, to help debug problems with the connection.
+@file{eb.log} records all the output from @code{EBMON}, including echoes
+of the commands sent to it.  Running @samp{tail -f} on this file in
+another window often helps to understand trouble with @code{EBMON}, or
+unexpected events on the PC side of the connection.
+
+@end ifset
+
+@ifset ST2000
+@node ST2000 Remote
+@subsection @value{GDBN} with a Tandem ST2000
+
+To connect your ST2000 to the host system, see the manufacturer's
+manual.  Once the ST2000 is physically attached, you can run:
+
+@example
+target st2000 @var{dev} @var{speed}
+@end example
+
+@noindent
+to establish it as your debugging environment.  @var{dev} is normally
+the name of a serial device, such as @file{/dev/ttya}, connected to the
+ST2000 via a serial line.  You can instead specify @var{dev} as a TCP
+connection (for example, to a serial line attached via a terminal
+concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
+
+The @code{load} and @code{attach} commands are @emph{not} defined for
+this target; you must load your program into the ST2000 as you normally
+would for standalone operation.  @value{GDBN} reads debugging information
+(such as symbols) from a separate, debugging version of the program
+available on your host computer.
+@c FIXME!! This is terribly vague; what little content is here is
+@c basically hearsay.
+
+@cindex ST2000 auxiliary commands
+These auxiliary @value{GDBN} commands are available to help you with the ST2000
+environment:
+
+@table @code
+@item st2000 @var{command}
+@kindex st2000 @var{cmd}
+@cindex STDBUG commands (ST2000)
+@cindex commands to STDBUG (ST2000)
+Send a @var{command} to the STDBUG monitor.  See the manufacturer's
+manual for available commands.
+
+@item connect
+@cindex connect (to STDBUG)
+Connect the controlling terminal to the STDBUG command monitor.  When
+you are done interacting with STDBUG, typing either of two character
+sequences gets you back to the @value{GDBN} command prompt:
+@kbd{@key{RET}~.} (Return, followed by tilde and period) or
+@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
+@end table
+@end ifset
+
+@ifset VXWORKS
+@node VxWorks Remote
+@subsection @value{GDBN} and VxWorks
+@cindex VxWorks
+
+@value{GDBN} enables developers to spawn and debug tasks running on networked
+VxWorks targets from a Unix host.  Already-running tasks spawned from
+the VxWorks shell can also be debugged.  @value{GDBN} uses code that runs on
+both the Unix host and on the VxWorks target.  The program
+@code{gdb} is installed and executed on the Unix host.  (It may be
+installed with the name @code{vxgdb}, to distinguish it from a
+@value{GDBN} for debugging programs on the host itself.)
+
+@table @code
+@item VxWorks-timeout @var{args}
+@kindex vxworks-timeout
+All VxWorks-based targets now support the option @code{vxworks-timeout}.  
+This option is set by the user, and  @var{args} represents the number of 
+seconds @value{GDBN} waits for responses to rpc's.  You might use this if 
+your VxWorks target is a slow software simulator or is on the far side 
+of a thin network line.
+@end table
+
+The following information on connecting to VxWorks was current when
+this manual was produced; newer releases of VxWorks may use revised
+procedures.
+
+@kindex INCLUDE_RDB
+To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
+to include the remote debugging interface routines in the VxWorks
+library @file{rdb.a}.  To do this, define @code{INCLUDE_RDB} in the
+VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
+kernel.  The resulting kernel contains @file{rdb.a}, and spawns the
+source debugging task @code{tRdbTask} when VxWorks is booted.  For more
+information on configuring and remaking VxWorks, see the manufacturer's
+manual.
+@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
+
+Once you have included @file{rdb.a} in your VxWorks system image and set
+your Unix execution search path to find @value{GDBN}, you are ready to
+run @value{GDBN}.  From your Unix host, run @code{gdb} (or @code{vxgdb},
+depending on your installation).
+
+@value{GDBN} comes up showing the prompt:
+
+@example
+(vxgdb)
+@end example
+
+@menu
+* VxWorks Connection::          Connecting to VxWorks
+* VxWorks Download::            VxWorks download
+* VxWorks Attach::              Running tasks
+@end menu
+
+@node VxWorks Connection
+@subsubsection Connecting to VxWorks
+
+The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
+network.  To connect to a target whose host name is ``@code{tt}'', type:
+
+@example
+(vxgdb) target vxworks tt
+@end example
+
+@need 750
+@value{GDBN} displays messages like these:
+
+@smallexample
+Attaching remote machine across net... 
+Connected to tt.
+@end smallexample
+
+@need 1000
+@value{GDBN} then attempts to read the symbol tables of any object modules
+loaded into the VxWorks target since it was last booted.  @value{GDBN} locates
+these files by searching the directories listed in the command search
+path (@pxref{Environment, ,Your program's environment}); if it fails
+to find an object file, it displays a message such as:
+
+@example
+prog.o: No such file or directory.
+@end example
+
+When this happens, add the appropriate directory to the search path with
+the @value{GDBN} command @code{path}, and execute the @code{target}
+command again.
+
+@node VxWorks Download
+@subsubsection VxWorks download
+
+@cindex download to VxWorks
+If you have connected to the VxWorks target and you want to debug an
+object that has not yet been loaded, you can use the @value{GDBN}
+@code{load} command to download a file from Unix to VxWorks
+incrementally.  The object file given as an argument to the @code{load}
+command is actually opened twice: first by the VxWorks target in order
+to download the code, then by @value{GDBN} in order to read the symbol
+table.  This can lead to problems if the current working directories on
+the two systems differ.  If both systems have NFS mounted the same
+filesystems, you can avoid these problems by using absolute paths.
+Otherwise, it is simplest to set the working directory on both systems
+to the directory in which the object file resides, and then to reference
+the file by its name, without any path.  For instance, a program
+@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
+and in @file{@var{hostpath}/vw/demo/rdb} on the host.  To load this
+program, type this on VxWorks:
+
+@example
+-> cd "@var{vxpath}/vw/demo/rdb"
+@end example
+v
+Then, in @value{GDBN}, type:
+
+@example
+(vxgdb) cd @var{hostpath}/vw/demo/rdb 
+(vxgdb) load prog.o
+@end example
+
+@value{GDBN} displays a response similar to this:
+
+@smallexample
+Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
+@end smallexample
+
+You can also use the @code{load} command to reload an object module
+after editing and recompiling the corresponding source file.  Note that
+this makes @value{GDBN} delete all currently-defined breakpoints,
+auto-displays, and convenience variables, and to clear the value
+history.  (This is necessary in order to preserve the integrity of
+debugger data structures that reference the target system's symbol
+table.)
+
+@node VxWorks Attach
+@subsubsection Running tasks
+
+@cindex running VxWorks tasks
+You can also attach to an existing task using the @code{attach} command as
+follows:
+
+@example
+(vxgdb) attach @var{task}
+@end example
+
+@noindent
+where @var{task} is the VxWorks hexadecimal task ID.  The task can be running
+or suspended when you attach to it.  Running tasks are suspended at
+the time of attachment.
+@end ifset
+
+@ifset SPARCLET
+@node Sparclet Remote
+@subsection @value{GDBN} and Sparclet
+@cindex Sparclet
+
+@value{GDBN} enables developers to debug tasks running on 
+Sparclet targets from a Unix host.  
+@value{GDBN} uses code that runs on
+both the Unix host and on the Sparclet target.  The program
+@code{gdb} is installed and executed on the Unix host.  
+
+@table @code
+@item timeout @var{args}
+@kindex remotetimeout
+@value{GDBN} now supports the option @code{remotetimeout}.  
+This option is set by the user, and  @var{args} represents the number of 
+seconds @value{GDBN} waits for responses.  
+@end table
+
+@kindex Compiling
+When compiling for debugging, include the options "-g" to get debug 
+information and "-Ttext" to relocate the program to where you wish to
+load it on the target.  You may also want to add the options "-n" or 
+"-N" in order to reduce the size of the sections.
+
+@example
+sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
+@end example
+
+You can use objdump to verify that the addresses are what you intended.
+
+@example
+sparclet-aout-objdump --headers --syms prog
+@end example
+
+@kindex Running
+Once you have set
+your Unix execution search path to find @value{GDBN}, you are ready to
+run @value{GDBN}.  From your Unix host, run @code{gdb} 
+(or @code{sparclet-aout-gdb}, depending on your installation).
+
+@value{GDBN} comes up showing the prompt:
+
+@example
+(gdbslet)
+@end example
+
+@menu
+* Sparclet File::                Setting the file to debug
+* Sparclet Connection::          Connecting to Sparclet
+* Sparclet Download::            Sparclet download
+* Sparclet Execution::           Running and debugging 
+@end menu
+
+@node Sparclet File
+@subsubsection Setting file to debug
+
+The @value{GDBN} command @code{file} lets you choose with program to debug.
+
+@example
+(gdbslet) file prog
+@end example
+
+@need 1000
+@value{GDBN} then attempts to read the symbol table of @file{prog}.
+@value{GDBN} locates
+the file by searching the directories listed in the command search
+path.
+If the file was compiled with debug information (option "-g"), source
+files will be searched as well.
+@value{GDBN} locates
+the source files by searching the directories listed in the directory search
+path (@pxref{Environment, ,Your program's environment}).
+If it fails
+to find a file, it displays a message such as:
+
+@example
+prog: No such file or directory.
+@end example
+
+When this happens, add the appropriate directories to the search paths with
+the @value{GDBN} commands @code{path} and @code{dir}, and execute the 
+@code{target} command again.
+
+@node Sparclet Connection
+@subsubsection Connecting to Sparclet
+
+The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
+To connect to a target on serial port ``@code{ttya}'', type:
+
+@example
+(gdbslet) target sparclet /dev/ttya
+Remote target sparclet connected to /dev/ttya
+main () at ../prog.c:3 
+@end example
+
+@need 750
+@value{GDBN} displays messages like these:
+
+@smallexample
+Connected to ttya.
+@end smallexample
+
+@node Sparclet Download
+@subsubsection Sparclet download
+
+@cindex download to Sparclet
+Once connected to the Sparclet target, 
+you can use the @value{GDBN}
+@code{load} command to download the file from the host to the target.
+The file name and load offset should be given as arguments to the @code{load}
+command.
+Since the file format is aout, the program must be loaded to the starting 
+address.  You can use objdump to find out what this value is.  The load
+offset is an offset which is added to the VMA (virtual memory address)
+of each of the file's sections.
+For instance, if the program
+@file{prog} was linked to text address 0x1201000, with data at 0x12010160
+and bss at 0x12010170, in @value{GDBN}, type:
+
+@example
+(gdbslet) load prog 0x12010000
+Loading section .text, size 0xdb0 vma 0x12010000
+@end example
+
+If the code is loaded at a different address then what the program was linked 
+to, you may need to use the @code{section} and @code{add-symbol-file} commands 
+to tell @value{GDBN} where to map the symbol table.
+
+@node Sparclet Execution
+@subsubsection Running and debugging
+
+@cindex running and debugging Sparclet programs
+You can now begin debugging the task using @value{GDBN}'s execution control
+commands, @code{b}, @code{step}, @code{run}, etc.  See the @value{GDBN} 
+manual for the list of commands.
+
+@example
+(gdbslet) b main
+Breakpoint 1 at 0x12010000: file prog.c, line 3.
+(gdbslet) run 
+Starting program: prog
+Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
+3        char *symarg = 0;
+(gdbslet) step
+4        char *execarg = "hello!";
+(gdbslet)                           
+@end example
+
+@end ifset
+
+@ifset H8
+@node Hitachi Remote
+@subsection @value{GDBN} and Hitachi microprocessors
+@value{GDBN} needs to know these things to talk to your
+Hitachi SH, H8/300, or H8/500: 
+
+@enumerate
+@item
+that you want to use @samp{target hms}, the remote debugging interface
+for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
+emulator for the Hitachi SH and the Hitachi 300H.  (@samp{target hms} is
+the default when GDB is configured specifically for the Hitachi SH,
+H8/300, or H8/500.)
+
+@item
+what serial device connects your host to your Hitachi board (the first
+serial device available on your host is the default).
+
+@ifclear H8EXCLUSIVE
+@c this is only for Unix hosts, not of interest to Hitachi
+@item
+what speed to use over the serial device.
+@end ifclear
+@end enumerate
+
+@menu
+* Hitachi Boards::      Connecting to Hitachi boards.
+* Hitachi ICE::         Using the E7000 In-Circuit Emulator.
+* Hitachi Special::     Special @value{GDBN} commands for Hitachi micros.
+@end menu
+
+@node Hitachi Boards
+@subsubsection Connecting to Hitachi boards
+
+@ifclear H8EXCLUSIVE
+@c only for Unix hosts
+@kindex device
+@cindex serial device, Hitachi micros
+Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you
+need to explicitly set the serial device.  The default @var{port} is the
+first available port on your host.  This is only necessary on Unix
+hosts, where it is typically something like @file{/dev/ttya}.
+
+@kindex speed
+@cindex serial line speed, Hitachi micros
+@code{@value{GDBP}} has another special command to set the communications
+speed: @samp{speed @var{bps}}.  This command also is only used from Unix
+hosts; on DOS hosts, set the line speed as usual from outside GDB with
+the DOS @kbd{mode} command (for instance, @w{@samp{mode
+com2:9600,n,8,1,p}} for a 9600 bps connection).
+
+The @samp{device} and @samp{speed} commands are available only when you
+use a Unix host to debug your Hitachi microprocessor programs.  If you
+use a DOS host,
+@end ifclear
+@value{GDBN} depends on an auxiliary terminate-and-stay-resident program
+called @code{asynctsr} to communicate with the development board
+through a PC serial port.  You must also use the DOS @code{mode} command
+to set up the serial port on the DOS side.
+
+@ifset DOSHOST
+The following sample session illustrates the steps needed to start a
+program under @value{GDBN} control on an H8/300.  The example uses a
+sample H8/300 program called @file{t.x}.  The procedure is the same for
+the Hitachi SH and the H8/500.
+
+First hook up your development board.  In this example, we use a
+board attached to serial port @code{COM2}; if you use a different serial
+port, substitute its name in the argument of the @code{mode} command.
+When you call @code{asynctsr}, the auxiliary comms program used by the
+degugger, you give it just the numeric part of the serial port's name;
+for example, @samp{asyncstr 2} below runs @code{asyncstr} on
+@code{COM2}.
+
+@example
+C:\H8300\TEST> asynctsr 2
+C:\H8300\TEST> mode com2:9600,n,8,1,p
+
+Resident portion of MODE loaded
+
+COM2: 9600, n, 8, 1, p
+
+@end example
+
+@quotation
+@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
+@code{asynctsr}.  If you also run PC-NFS on your DOS host, you may need to
+disable it, or even boot without it, to use @code{asynctsr} to control
+your development board.
+@end quotation
+
+@kindex target hms
+Now that serial communications are set up, and the development board is
+connected, you can start up @value{GDBN}.  Call @code{@value{GDBP}} with
+the name of your program as the argument.  @code{@value{GDBP}} prompts
+you, as usual, with the prompt @samp{(@value{GDBP})}.  Use two special
+commands to begin your debugging session: @samp{target hms} to specify
+cross-debugging to the Hitachi board, and the @code{load} command to
+download your program to the board.  @code{load} displays the names of
+the program's sections, and a @samp{*} for each 2K of data downloaded.
+(If you want to refresh @value{GDBN} data on symbols or on the
+executable file without downloading, use the @value{GDBN} commands
+@code{file} or @code{symbol-file}.  These commands, and @code{load}
+itself, are described in @ref{Files,,Commands to specify files}.)
+
+@smallexample
+(eg-C:\H8300\TEST) @value{GDBP} t.x
+GDB is free software and you are welcome to distribute copies
+ of it under certain conditions; type "show copying" to see 
+ the conditions.
+There is absolutely no warranty for GDB; type "show warranty" 
+for details.
+GDB @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
+(gdb) target hms
+Connected to remote H8/300 HMS system.
+(gdb) load t.x
+.text   : 0x8000 .. 0xabde ***********
+.data   : 0xabde .. 0xad30 *
+.stack  : 0xf000 .. 0xf014 *
+@end smallexample
+
+At this point, you're ready to run or debug your program.  From here on,
+you can use all the usual @value{GDBN} commands.  The @code{break} command
+sets breakpoints; the @code{run} command starts your program;
+@code{print} or @code{x} display data; the @code{continue} command
+resumes execution after stopping at a breakpoint.  You can use the
+@code{help} command at any time to find out more about @value{GDBN} commands.
+
+Remember, however, that @emph{operating system} facilities aren't
+available on your development board; for example, if your program hangs,
+you can't send an interrupt---but you can press the @sc{reset} switch!
+
+Use the @sc{reset} button on the development board
+@itemize @bullet
+@item
+to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
+no way to pass an interrupt signal to the development board); and
+
+@item
+to return to the @value{GDBN} command prompt after your program finishes
+normally.  The communications protocol provides no other way for @value{GDBN}
+to detect program completion.
+@end itemize
+
+In either case, @value{GDBN} sees the effect of a @sc{reset} on the
+development board as a ``normal exit'' of your program.
+@end ifset
+
+@node Hitachi ICE
+@subsubsection Using the E7000 in-circuit emulator
+
+@kindex target e7000
+You can use the E7000 in-circuit emulator to develop code for either the
+Hitachi SH or the H8/300H.  Use one of these forms of the @samp{target
+e7000} command to connect @value{GDBN} to your E7000:
+
+@table @code
+@item target e7000 @var{port} @var{speed}
+Use this form if your E7000 is connected to a serial port.  The
+@var{port} argument identifies what serial port to use (for example,
+@samp{com2}).  The third argument is the line speed in bits per second
+(for example, @samp{9600}).
+
+@item target e7000 @var{hostname}
+If your E7000 is installed as a host on a TCP/IP network, you can just
+specify its hostname; @value{GDBN} uses @code{telnet} to connect.
+@end table
+
+@node Hitachi Special
+@subsubsection Special @value{GDBN} commands for Hitachi micros
+
+Some @value{GDBN} commands are available only on the H8/300 or the
+H8/500 configurations:
+
+@table @code
+@kindex set machine
+@kindex show machine
+@item set machine h8300
+@itemx set machine h8300h
+Condition @value{GDBN} for one of the two variants of the H8/300
+architecture with @samp{set machine}.  You can use @samp{show machine}
+to check which variant is currently in effect.
+
+@kindex set memory @var{mod}
+@cindex memory models, H8/500
+@item set memory @var{mod}
+@itemx show memory
+Specify which H8/500 memory model (@var{mod}) you are using with
+@samp{set memory}; check which memory model is in effect with @samp{show
+memory}.  The accepted values for @var{mod} are @code{small},
+@code{big}, @code{medium}, and @code{compact}.
+@end table
+
+@end ifset
+
+@ifset MIPS
+@node MIPS Remote
+@subsection @value{GDBN} and remote MIPS boards
+
+@cindex MIPS boards
+@value{GDBN} can use the MIPS remote debugging protocol to talk to a
+MIPS board attached to a serial line.  This is available when
+you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
+
+@need 1000
+Use these @value{GDBN} commands to specify the connection to your target board:
+
+@table @code
+@item target mips @var{port}
+@kindex target mips @var{port}
+To run a program on the board, start up @code{@value{GDBP}} with the
+name of your program as the argument.  To connect to the board, use the
+command @samp{target mips @var{port}}, where @var{port} is the name of
+the serial port connected to the board.  If the program has not already
+been downloaded to the board, you may use the @code{load} command to
+download it.  You can then use all the usual @value{GDBN} commands.
+
+For example, this sequence connects to the target board through a serial
+port, and loads and runs a program called @var{prog} through the
+debugger:
+
+@example
+host$ @value{GDBP} @var{prog}
+GDB is free software and @dots{}
+(gdb) target mips /dev/ttyb
+(gdb) load @var{prog}
+(gdb) run
+@end example
+
+@item target mips @var{hostname}:@var{portnumber}
+On some @value{GDBN} host configurations, you can specify a TCP
+connection (for instance, to a serial line managed by a terminal
+concentrator) instead of a serial port, using the syntax
+@samp{@var{hostname}:@var{portnumber}}.
+
+@item target pmon @var{port}
+@kindex target pmon @var{port}
+
+@item target ddb @var{port}
+@kindex target ddb @var{port}
+
+@item target lsi @var{port}
+@kindex target lsi @var{port}
+
+@end table
+
+
+@noindent
+@value{GDBN} also supports these special commands for MIPS targets:
+
+@table @code
+@item set processor @var{args}
+@itemx show processor
+@kindex set processor @var{args}
+@kindex show processor
+Use the @code{set processor} command to set the type of MIPS
+processor when you want to access processor-type-specific registers.
+For example, @code{set processor @var{r3041}} tells @value{GDBN} 
+to use the CPO registers appropriate for the 3041 chip.
+Use the @code{show processor} command to see what MIPS processor @value{GDBN} 
+is using.  Use the @code{info reg} command to see what registers
+@value{GDBN} is using. 
+
+@item set mipsfpu double
+@itemx set mipsfpu single
+@itemx set mipsfpu none
+@itemx show mipsfpu
+@kindex set mipsfpu
+@kindex show mipsfpu
+@cindex MIPS remote floating point
+@cindex floating point, MIPS remote
+If your target board does not support the MIPS floating point
+coprocessor, you should use the command @samp{set mipsfpu none} (if you
+need this, you may wish to put the command in your @value{GDBINIT}
+file).  This tells @value{GDBN} how to find the return value of
+functions which return floating point values.  It also allows
+@value{GDBN} to avoid saving the floating point registers when calling
+functions on the board.  If you are using a floating point coprocessor
+with only single precision floating point support, as on the @sc{r4650}
+processor, use the command @samp{set mipsfpu single}.  The default
+double precision floating point coprocessor may be selected using
+@samp{set mipsfpu double}.
+
+In previous versions the only choices were double precision or no
+floating point, so @samp{set mipsfpu on} will select double precision
+and @samp{set mipsfpu off} will select no floating point.
+
+As usual, you can inquire about the @code{mipsfpu} variable with
+@samp{show mipsfpu}.
+
+@item set remotedebug @var{n}
+@itemx show remotedebug
+@kindex set remotedebug
+@kindex show remotedebug
+@cindex @code{remotedebug}, MIPS protocol
+@cindex MIPS @code{remotedebug} protocol
+@c FIXME! For this to be useful, you must know something about the MIPS
+@c FIXME...protocol.  Where is it described?
+You can see some debugging information about communications with the board
+by setting the @code{remotedebug} variable.  If you set it to @code{1} using
+@samp{set remotedebug 1}, every packet is displayed.  If you set it
+to @code{2}, every character is displayed.  You can check the current value
+at any time with the command @samp{show remotedebug}.
+
+@item set timeout @var{seconds}
+@itemx set retransmit-timeout @var{seconds}
+@itemx show timeout
+@itemx show retransmit-timeout
+@cindex @code{timeout}, MIPS protocol
+@cindex @code{retransmit-timeout}, MIPS protocol
+@kindex set timeout
+@kindex show timeout
+@kindex set retransmit-timeout
+@kindex show retransmit-timeout
+You can control the timeout used while waiting for a packet, in the MIPS
+remote protocol, with the @code{set timeout @var{seconds}} command.  The
+default is 5 seconds.  Similarly, you can control the timeout used while
+waiting for an acknowledgement of a packet with the @code{set
+retransmit-timeout @var{seconds}} command.  The default is 3 seconds.
+You can inspect both values with @code{show timeout} and @code{show
+retransmit-timeout}.  (These commands are @emph{only} available when
+@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
+
+The timeout set by @code{set timeout} does not apply when @value{GDBN}
+is waiting for your program to stop.  In that case, @value{GDBN} waits
+forever because it has no way of knowing how long the program is going
+to run before stopping.
+@end table
+@end ifset
+
+@ifset SIMS
+@node Simulator
+@subsection Simulated CPU target
+
+@ifset GENERIC
+@cindex simulator
+@cindex simulator, Z8000
+@cindex Z8000 simulator
+@cindex simulator, H8/300 or H8/500
+@cindex H8/300 or H8/500 simulator
+@cindex simulator, Hitachi SH
+@cindex Hitachi SH simulator
+@cindex CPU simulator
+For some configurations, @value{GDBN} includes a CPU simulator that you
+can use instead of a hardware CPU to debug your programs.
+Currently, simulators are available for ARM, D10V, D30V, FR30, H8/300,
+H8/500, i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850,
+W65, and Z8000.
+@end ifset
+
+@ifclear GENERIC
+@ifset H8
+@cindex simulator, H8/300 or H8/500
+@cindex Hitachi H8/300 or H8/500 simulator
+@cindex simulator, Hitachi SH
+@cindex Hitachi SH simulator
+When configured for debugging Hitachi microprocessor targets,
+@value{GDBN} includes a CPU simulator for the target chip (a Hitachi SH,
+H8/300, or H8/500).
+@end ifset
+
+@ifset Z8K
+@cindex simulator, Z8000
+@cindex Zilog Z8000 simulator
+When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
+a Z8000 simulator.
+@end ifset
+@end ifclear
+
+@ifset Z8K
+For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
+unsegmented variant of the Z8000 architecture) or the Z8001 (the
+segmented variant).  The simulator recognizes which architecture is
+appropriate by inspecting the object code.
+@end ifset
+
+@table @code
+@item target sim @var{args}
+@kindex sim
+@kindex target sim
+Debug programs on a simulated CPU.  If the simulator supports setup
+options, specify them via @var{args}.
+@end table
+
+@noindent
+After specifying this target, you can debug programs for the simulated
+CPU in the same style as programs for your host computer; use the
+@code{file} command to load a new program image, the @code{run} command
+to run your program, and so on.
+
+As well as making available all the usual machine registers (see
+@code{info reg}), the Z8000 simulator provides three additional items
+of information as specially named registers:
+
+@table @code
+@item cycles
+Counts clock-ticks in the simulator.
+
+@item insts
+Counts instructions run in the simulator.
+
+@item time
+Execution time in 60ths of a second. 
+@end table
+
+You can refer to these values in @value{GDBN} expressions with the usual
+conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
+conditional breakpoint that suspends only after at least 5000
+simulated clock ticks.
+@end ifset
+
+@c need to add much more detail about sims!
diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo
new file mode 100644
index 0000000000..a4f0bc9398
--- /dev/null
+++ b/gdb/doc/stabs.texinfo
@@ -0,0 +1,4019 @@
+\input texinfo
+@setfilename stabs.info
+
+@c @finalout
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Stabs: (stabs).                 The "stabs" debugging information format.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@ifinfo
+This document describes the stabs debugging symbol tables.
+
+Copyright 1992, 93, 94, 95, 97, 1998 Free Software Foundation, Inc.
+Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,
+and David MacKenzie.
+
+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.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy or distribute modified versions of this
+manual under the terms of the GPL (for which purpose this text may be
+regarded as a program in the language TeX).
+@end ifinfo
+
+@setchapternewpage odd
+@settitle STABS
+@titlepage
+@title The ``stabs'' debug format
+@author Julia Menapace, Jim Kingdon, David MacKenzie
+@author Cygnus Support
+@page
+@tex
+\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
+\xdef\manvers{\$Revision$}  % For use in headers, footers too
+{\parskip=0pt
+\hfill Cygnus Support\par
+\hfill \manvers\par
+\hfill \TeX{}info \texinfoversion\par
+}
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 93, 94, 95, 97, 1998 Free Software Foundation, Inc.
+Contributed by Cygnus Support.
+
+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.
+
+@end titlepage
+
+@ifinfo
+@node Top
+@top The "stabs" representation of debugging information
+
+This document describes the stabs debugging format.
+
+@menu
+* Overview::			Overview of stabs
+* Program Structure::		Encoding of the structure of the program
+* Constants::			Constants
+* Variables::
+* Types::			Type definitions
+* Symbol Tables::		Symbol information in symbol tables
+* Cplusplus::			Stabs specific to C++
+* Stab Types::			Symbol types in a.out files
+* Symbol Descriptors::		Table of symbol descriptors
+* Type Descriptors::		Table of type descriptors
+* Expanded Reference::		Reference information by stab type
+* Questions::			Questions and anomolies
+* Stab Sections::		In some object file formats, stabs are
+                                in sections.
+* Symbol Types Index::          Index of symbolic stab symbol type names.
+@end menu
+@end ifinfo
+
+
+@node Overview
+@chapter Overview of Stabs
+
+@dfn{Stabs} refers to a format for information that describes a program
+to a debugger.  This format was apparently invented by
+Peter Kessler at
+the University of California at Berkeley, for the @code{pdx} Pascal
+debugger; the format has spread widely since then.
+
+This document is one of the few published sources of documentation on
+stabs.  It is believed to be comprehensive for stabs used by C.  The
+lists of symbol descriptors (@pxref{Symbol Descriptors}) and type
+descriptors (@pxref{Type Descriptors}) are believed to be completely
+comprehensive.  Stabs for COBOL-specific features and for variant
+records (used by Pascal and Modula-2) are poorly documented here.
+
+@c FIXME: Need to document all OS9000 stuff in GDB; see all references
+@c to os9k_stabs in stabsread.c.
+
+Other sources of information on stabs are @cite{Dbx and Dbxtool
+Interfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files
+Reference}, Fourth Edition, September 1992, "dbx Stabstring Grammar" in
+the a.out section, page 2-31.  This document is believed to incorporate
+the information from those two sources except where it explicitly directs
+you to them for more information.
+
+@menu
+* Flow::			Overview of debugging information flow
+* Stabs Format::		Overview of stab format
+* String Field::		The string field
+* C Example::			A simple example in C source
+* Assembly Code::		The simple example at the assembly level
+@end menu
+
+@node Flow
+@section Overview of Debugging Information Flow
+
+The GNU C compiler compiles C source in a @file{.c} file into assembly
+language in a @file{.s} file, which the assembler translates into
+a @file{.o} file, which the linker combines with other @file{.o} files and
+libraries to produce an executable file.
+
+With the @samp{-g} option, GCC puts in the @file{.s} file additional
+debugging information, which is slightly transformed by the assembler
+and linker, and carried through into the final executable.  This
+debugging information describes features of the source file like line
+numbers, the types and scopes of variables, and function names,
+parameters, and scopes.
+
+For some object file formats, the debugging information is encapsulated
+in assembler directives known collectively as @dfn{stab} (symbol table)
+directives, which are interspersed with the generated code.  Stabs are
+the native format for debugging information in the a.out and XCOFF
+object file formats.  The GNU tools can also emit stabs in the COFF and
+ECOFF object file formats.
+
+The assembler adds the information from stabs to the symbol information
+it places by default in the symbol table and the string table of the
+@file{.o} file it is building.  The linker consolidates the @file{.o}
+files into one executable file, with one symbol table and one string
+table.  Debuggers use the symbol and string tables in the executable as
+a source of debugging information about the program.
+
+@node Stabs Format
+@section Overview of Stab Format
+
+There are three overall formats for stab assembler directives,
+differentiated by the first word of the stab.  The name of the directive
+describes which combination of four possible data fields follows.  It is
+either @code{.stabs} (string), @code{.stabn} (number), or @code{.stabd}
+(dot).  IBM's XCOFF assembler uses @code{.stabx} (and some other
+directives such as @code{.file} and @code{.bi}) instead of
+@code{.stabs}, @code{.stabn} or @code{.stabd}.
+
+The overall format of each class of stab is:
+
+@example
+.stabs "@var{string}",@var{type},@var{other},@var{desc},@var{value}
+.stabn @var{type},@var{other},@var{desc},@var{value}
+.stabd @var{type},@var{other},@var{desc}
+.stabx "@var{string}",@var{value},@var{type},@var{sdb-type}
+@end example
+
+@c what is the correct term for "current file location"?  My AIX
+@c assembler manual calls it "the value of the current location counter".
+For @code{.stabn} and @code{.stabd}, there is no @var{string} (the
+@code{n_strx} field is zero; see @ref{Symbol Tables}).  For
+@code{.stabd}, the @var{value} field is implicit and has the value of
+the current file location.  For @code{.stabx}, the @var{sdb-type} field
+is unused for stabs and can always be set to zero.  The @var{other}
+field is almost always unused and can be set to zero.
+
+The number in the @var{type} field gives some basic information about
+which type of stab this is (or whether it @emph{is} a stab, as opposed
+to an ordinary symbol).  Each valid type number defines a different stab
+type; further, the stab type defines the exact interpretation of, and
+possible values for, any remaining @var{string}, @var{desc}, or
+@var{value} fields present in the stab.  @xref{Stab Types}, for a list
+in numeric order of the valid @var{type} field values for stab directives.
+
+@node String Field
+@section The String Field
+
+For most stabs the string field holds the meat of the
+debugging information.  The flexible nature of this field
+is what makes stabs extensible.  For some stab types the string field
+contains only a name.  For other stab types the contents can be a great
+deal more complex.
+
+The overall format of the string field for most stab types is:
+
+@example
+"@var{name}:@var{symbol-descriptor} @var{type-information}"
+@end example
+
+@var{name} is the name of the symbol represented by the stab; it can
+contain a pair of colons (@pxref{Nested Symbols}).  @var{name} can be
+omitted, which means the stab represents an unnamed object.  For
+example, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does
+not give the type a name.  Omitting the @var{name} field is supported by
+AIX dbx and GDB after about version 4.8, but not other debuggers.  GCC
+sometimes uses a single space as the name instead of omitting the name
+altogether; apparently that is supported by most debuggers.
+
+The @var{symbol-descriptor} following the @samp{:} is an alphabetic
+character that tells more specifically what kind of symbol the stab
+represents. If the @var{symbol-descriptor} is omitted, but type
+information follows, then the stab represents a local variable.  For a
+list of symbol descriptors, see @ref{Symbol Descriptors}.  The @samp{c}
+symbol descriptor is an exception in that it is not followed by type
+information.  @xref{Constants}.
+
+@var{type-information} is either a @var{type-number}, or
+@samp{@var{type-number}=}.  A @var{type-number} alone is a type
+reference, referring directly to a type that has already been defined.
+
+The @samp{@var{type-number}=} form is a type definition, where the
+number represents a new type which is about to be defined.  The type
+definition may refer to other types by number, and those type numbers
+may be followed by @samp{=} and nested definitions.  Also, the Lucid
+compiler will repeat @samp{@var{type-number}=} more than once if it
+wants to define several type numbers at once.
+
+In a type definition, if the character that follows the equals sign is
+non-numeric then it is a @var{type-descriptor}, and tells what kind of
+type is about to be defined.  Any other values following the
+@var{type-descriptor} vary, depending on the @var{type-descriptor}.
+@xref{Type Descriptors}, for a list of @var{type-descriptor} values.  If
+a number follows the @samp{=} then the number is a @var{type-reference}.
+For a full description of types, @ref{Types}.
+
+A @var{type-number} is often a single number.  The GNU and Sun tools
+additionally permit a @var{type-number} to be a pair
+(@var{file-number},@var{filetype-number}) (the parentheses appear in the
+string, and serve to distinguish the two cases).  The @var{file-number}
+is a number starting with 1 which is incremented for each seperate
+source file in the compilation (e.g., in C, each header file gets a
+different number).  The @var{filetype-number} is a number starting with
+1 which is incremented for each new type defined in the file.
+(Separating the file number and the type number permits the
+@code{N_BINCL} optimization to succeed more often; see @ref{Include
+Files}).
+
+There is an AIX extension for type attributes.  Following the @samp{=}
+are any number of type attributes.  Each one starts with @samp{@@} and
+ends with @samp{;}.  Debuggers, including AIX's dbx and GDB 4.10, skip
+any type attributes they do not recognize.  GDB 4.9 and other versions
+of dbx may not do this.  Because of a conflict with C++
+(@pxref{Cplusplus}), new attributes should not be defined which begin
+with a digit, @samp{(}, or @samp{-}; GDB may be unable to distinguish
+those from the C++ type descriptor @samp{@@}.  The attributes are:
+
+@table @code
+@item a@var{boundary}
+@var{boundary} is an integer specifying the alignment.  I assume it
+applies to all variables of this type.
+
+@item p@var{integer}
+Pointer class (for checking).  Not sure what this means, or how
+@var{integer} is interpreted.
+
+@item P
+Indicate this is a packed type, meaning that structure fields or array
+elements are placed more closely in memory, to save memory at the
+expense of speed.
+
+@item s@var{size}
+Size in bits of a variable of this type.  This is fully supported by GDB
+4.11 and later.
+
+@item S
+Indicate that this type is a string instead of an array of characters,
+or a bitstring instead of a set.  It doesn't change the layout of the
+data being represented, but does enable the debugger to know which type
+it is.
+@end table
+
+All of this can make the string field quite long.  All versions of GDB,
+and some versions of dbx, can handle arbitrarily long strings.  But many
+versions of dbx (or assemblers or linkers, I'm not sure which)
+cretinously limit the strings to about 80 characters, so compilers which
+must work with such systems need to split the @code{.stabs} directive
+into several @code{.stabs} directives.  Each stab duplicates every field
+except the string field.  The string field of every stab except the last
+is marked as continued with a backslash at the end (in the assembly code
+this may be written as a double backslash, depending on the assembler).
+Removing the backslashes and concatenating the string fields of each
+stab produces the original, long string.  Just to be incompatible (or so
+they don't have to worry about what the assembler does with
+backslashes), AIX can use @samp{?} instead of backslash.
+
+@node C Example
+@section A Simple Example in C Source
+
+To get the flavor of how stabs describe source information for a C
+program, let's look at the simple program:
+
+@example
+main()
+@{
+        printf("Hello world");
+@}
+@end example
+
+When compiled with @samp{-g}, the program above yields the following
+@file{.s} file.  Line numbers have been added to make it easier to refer
+to parts of the @file{.s} file in the description of the stabs that
+follows.
+
+@node Assembly Code
+@section The Simple Example at the Assembly Level
+
+This simple ``hello world'' example demonstrates several of the stab
+types used to describe C language source files.
+
+@example
+1  gcc2_compiled.:
+2  .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
+3  .stabs "hello.c",100,0,0,Ltext0
+4  .text
+5  Ltext0:
+6  .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
+7  .stabs "char:t2=r2;0;127;",128,0,0,0
+8  .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
+9  .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
+10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
+11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
+12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
+13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
+14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
+15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
+16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
+17 .stabs "float:t12=r1;4;0;",128,0,0,0
+18 .stabs "double:t13=r1;8;0;",128,0,0,0
+19 .stabs "long double:t14=r1;8;0;",128,0,0,0
+20 .stabs "void:t15=15",128,0,0,0
+21      .align 4
+22 LC0:
+23      .ascii "Hello, world!\12\0"
+24      .align 4
+25      .global _main
+26      .proc 1
+27 _main:
+28 .stabn 68,0,4,LM1
+29 LM1:
+30      !#PROLOGUE# 0
+31      save %sp,-136,%sp
+32      !#PROLOGUE# 1
+33      call ___main,0
+34      nop
+35 .stabn 68,0,5,LM2
+36 LM2:
+37 LBB2:
+38      sethi %hi(LC0),%o1
+39      or %o1,%lo(LC0),%o0
+40      call _printf,0
+41      nop
+42 .stabn 68,0,6,LM3
+43 LM3:
+44 LBE2:
+45 .stabn 68,0,6,LM4
+46 LM4:
+47 L1:
+48      ret
+49      restore
+50 .stabs "main:F1",36,0,0,_main
+51 .stabn 192,0,0,LBB2
+52 .stabn 224,0,0,LBE2
+@end example
+
+@node Program Structure
+@chapter Encoding the Structure of the Program
+
+The elements of the program structure that stabs encode include the name
+of the main function, the names of the source and include files, the
+line numbers, procedure names and types, and the beginnings and ends of
+blocks of code.
+
+@menu
+* Main Program::		Indicate what the main program is
+* Source Files::		The path and name of the source file
+* Include Files::               Names of include files
+* Line Numbers::
+* Procedures::
+* Nested Procedures::
+* Block Structure::
+* Alternate Entry Points::      Entering procedures except at the beginning.
+@end menu
+
+@node Main Program
+@section Main Program
+
+@findex N_MAIN
+Most languages allow the main program to have any name.  The
+@code{N_MAIN} stab type tells the debugger the name that is used in this
+program.  Only the string field is significant; it is the name of
+a function which is the main program.  Most C compilers do not use this
+stab (they expect the debugger to assume that the name is @code{main}),
+but some C compilers emit an @code{N_MAIN} stab for the @code{main}
+function.  I'm not sure how XCOFF handles this.
+
+@node Source Files
+@section Paths and Names of the Source Files
+
+@findex N_SO
+Before any other stabs occur, there must be a stab specifying the source
+file.  This information is contained in a symbol of stab type
+@code{N_SO}; the string field contains the name of the file.  The
+value of the symbol is the start address of the portion of the
+text section corresponding to that file.
+
+With the Sun Solaris2 compiler, the desc field contains a
+source-language code.
+@c Do the debuggers use it?  What are the codes? -djm
+
+Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also
+include the directory in which the source was compiled, in a second
+@code{N_SO} symbol preceding the one containing the file name.  This
+symbol can be distinguished by the fact that it ends in a slash.  Code
+from the @code{cfront} C++ compiler can have additional @code{N_SO} symbols for
+nonexistent source files after the @code{N_SO} for the real source file;
+these are believed to contain no useful information.
+
+For example:
+
+@example
+.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0     # @r{100 is N_SO}
+.stabs "hello.c",100,0,0,Ltext0
+        .text
+Ltext0:
+@end example
+
+@findex C_FILE
+Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler
+directive which assembles to a @code{C_FILE} symbol; explaining this in
+detail is outside the scope of this document.
+
+@c FIXME: Exactly when should the empty N_SO be used?  Why?
+If it is useful to indicate the end of a source file, this is done with
+an @code{N_SO} symbol with an empty string for the name.  The value is
+the address of the end of the text section for the file.  For some
+systems, there is no indication of the end of a source file, and you
+just need to figure it ended when you see an @code{N_SO} for a different
+source file, or a symbol ending in @code{.o} (which at least some
+linkers insert to mark the start of a new @code{.o} file).
+
+@node Include Files
+@section Names of Include Files
+
+There are several schemes for dealing with include files: the
+traditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the
+XCOFF @code{C_BINCL} approach (which despite the similar name has little in
+common with @code{N_BINCL}).
+
+@findex N_SOL
+An @code{N_SOL} symbol specifies which include file subsequent symbols
+refer to.  The string field is the name of the file and the value is the
+text address corresponding to the end of the previous include file and
+the start of this one.  To specify the main source file again, use an
+@code{N_SOL} symbol with the name of the main source file.
+
+@findex N_BINCL
+@findex N_EINCL
+@findex N_EXCL
+The @code{N_BINCL} approach works as follows.  An @code{N_BINCL} symbol
+specifies the start of an include file.  In an object file, only the
+string is significant; the linker puts data into some of the other
+fields.  The end of the include file is marked by an @code{N_EINCL}
+symbol (which has no string field).  In an object file, there is no
+significant data in the @code{N_EINCL} symbol.  @code{N_BINCL} and
+@code{N_EINCL} can be nested.
+
+If the linker detects that two source files have identical stabs between
+an @code{N_BINCL} and @code{N_EINCL} pair (as will generally be the case
+for a header file), then it only puts out the stabs once.  Each
+additional occurance is replaced by an @code{N_EXCL} symbol.  I believe
+the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
+ones which supports this feature.
+
+A linker which supports this feature will set the value of a
+@code{N_BINCL} symbol to the total of all the characters in the stabs
+strings included in the header file, omitting any file numbers.  The
+value of an @code{N_EXCL} symbol is the same as the value of the
+@code{N_BINCL} symbol it replaces.  This information can be used to
+match up @code{N_EXCL} and @code{N_BINCL} symbols which have the same
+filename.  The @code{N_EINCL} value, and the values of the other and
+description fields for all three, appear to always be zero.
+
+@findex C_BINCL
+@findex C_EINCL
+For the start of an include file in XCOFF, use the @file{.bi} assembler
+directive, which generates a @code{C_BINCL} symbol.  A @file{.ei}
+directive, which generates a @code{C_EINCL} symbol, denotes the end of
+the include file.  Both directives are followed by the name of the
+source file in quotes, which becomes the string for the symbol.
+The value of each symbol, produced automatically by the assembler
+and linker, is the offset into the executable of the beginning
+(inclusive, as you'd expect) or end (inclusive, as you would not expect)
+of the portion of the COFF line table that corresponds to this include
+file.  @code{C_BINCL} and @code{C_EINCL} do not nest.
+
+@node Line Numbers
+@section Line Numbers
+
+@findex N_SLINE
+An @code{N_SLINE} symbol represents the start of a source line.  The
+desc field contains the line number and the value contains the code
+address for the start of that source line.  On most machines the address
+is absolute; for stabs in sections (@pxref{Stab Sections}), it is
+relative to the function in which the @code{N_SLINE} symbol occurs.
+
+@findex N_DSLINE
+@findex N_BSLINE
+GNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line
+numbers in the data or bss segments, respectively.  They are identical
+to @code{N_SLINE} but are relocated differently by the linker.  They
+were intended to be used to describe the source location of a variable
+declaration, but I believe that GCC2 actually puts the line number in
+the desc field of the stab for the variable itself.  GDB has been
+ignoring these symbols (unless they contain a string field) since
+at least GDB 3.5.
+
+For single source lines that generate discontiguous code, such as flow
+of control statements, there may be more than one line number entry for
+the same source line.  In this case there is a line number entry at the
+start of each code range, each with the same line number.
+
+XCOFF does not use stabs for line numbers.  Instead, it uses COFF line
+numbers (which are outside the scope of this document).  Standard COFF
+line numbers cannot deal with include files, but in XCOFF this is fixed
+with the @code{C_BINCL} method of marking include files (@pxref{Include
+Files}).
+
+@node Procedures
+@section Procedures
+
+@findex N_FUN, for functions
+@findex N_FNAME
+@findex N_STSYM, for functions (Sun acc)
+@findex N_GSYM, for functions (Sun acc)
+All of the following stabs normally use the @code{N_FUN} symbol type.
+However, Sun's @code{acc} compiler on SunOS4 uses @code{N_GSYM} and
+@code{N_STSYM}, which means that the value of the stab for the function
+is useless and the debugger must get the address of the function from
+the non-stab symbols instead.  On systems where non-stab symbols have
+leading underscores, the stabs will lack underscores and the debugger
+needs to know about the leading underscore to match up the stab and the
+non-stab symbol.  BSD Fortran is said to use @code{N_FNAME} with the
+same restriction; the value of the symbol is not useful (I'm not sure it
+really does use this, because GDB doesn't handle this and no one has
+complained).
+
+@findex C_FUN
+A function is represented by an @samp{F} symbol descriptor for a global
+(extern) function, and @samp{f} for a static (local) function.  For
+a.out, the value of the symbol is the address of the start of the
+function; it is already relocated.  For stabs in ELF, the SunPRO
+compiler version 2.0.1 and GCC put out an address which gets relocated
+by the linker.  In a future release SunPRO is planning to put out zero,
+in which case the address can be found from the ELF (non-stab) symbol.
+Because looking things up in the ELF symbols would probably be slow, I'm
+not sure how to find which symbol of that name is the right one, and
+this doesn't provide any way to deal with nested functions, it would
+probably be better to make the value of the stab an address relative to
+the start of the file, or just absolute.  See @ref{ELF Linker
+Relocation} for more information on linker relocation of stabs in ELF
+files.  For XCOFF, the stab uses the @code{C_FUN} storage class and the
+value of the stab is meaningless; the address of the function can be
+found from the csect symbol (XTY_LD/XMC_PR).
+
+The type information of the stab represents the return type of the
+function; thus @samp{foo:f5} means that foo is a function returning type
+5.  There is no need to try to get the line number of the start of the
+function from the stab for the function; it is in the next
+@code{N_SLINE} symbol.
+
+@c FIXME: verify whether the "I suspect" below is true or not.
+Some compilers (such as Sun's Solaris compiler) support an extension for
+specifying the types of the arguments.  I suspect this extension is not
+used for old (non-prototyped) function definitions in C.  If the
+extension is in use, the type information of the stab for the function
+is followed by type information for each argument, with each argument
+preceded by @samp{;}.  An argument type of 0 means that additional
+arguments are being passed, whose types and number may vary (@samp{...}
+in ANSI C).  GDB has tolerated this extension (parsed the syntax, if not
+necessarily used the information) since at least version 4.8; I don't
+know whether all versions of dbx tolerate it.  The argument types given
+here are not redundant with the symbols for the formal parameters
+(@pxref{Parameters}); they are the types of the arguments as they are
+passed, before any conversions might take place.  For example, if a C
+function which is declared without a prototype takes a @code{float}
+argument, the value is passed as a @code{double} but then converted to a
+@code{float}.  Debuggers need to use the types given in the arguments
+when printing values, but when calling the function they need to use the
+types given in the symbol defining the function.
+
+If the return type and types of arguments of a function which is defined
+in another source file are specified (i.e., a function prototype in ANSI
+C), traditionally compilers emit no stab; the only way for the debugger
+to find the information is if the source file where the function is
+defined was also compiled with debugging symbols.  As an extension the
+Solaris compiler uses symbol descriptor @samp{P} followed by the return
+type of the function, followed by the arguments, each preceded by
+@samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}.
+This use of symbol descriptor @samp{P} can be distinguished from its use
+for register parameters (@pxref{Register Parameters}) by the fact that it has
+symbol type @code{N_FUN}.
+
+The AIX documentation also defines symbol descriptor @samp{J} as an
+internal function.  I assume this means a function nested within another
+function.  It also says symbol descriptor @samp{m} is a module in
+Modula-2 or extended Pascal.
+
+Procedures (functions which do not return values) are represented as
+functions returning the @code{void} type in C.  I don't see why this couldn't
+be used for all languages (inventing a @code{void} type for this purpose if
+necessary), but the AIX documentation defines @samp{I}, @samp{P}, and
+@samp{Q} for internal, global, and static procedures, respectively.
+These symbol descriptors are unusual in that they are not followed by
+type information.
+
+The following example shows a stab for a function @code{main} which
+returns type number @code{1}.  The @code{_main} specified for the value
+is a reference to an assembler label which is used to fill in the start
+address of the function.
+
+@example
+.stabs "main:F1",36,0,0,_main      # @r{36 is N_FUN}
+@end example
+
+The stab representing a procedure is located immediately following the
+code of the procedure.  This stab is in turn directly followed by a
+group of other stabs describing elements of the procedure.  These other
+stabs describe the procedure's parameters, its block local variables, and
+its block structure.
+
+If functions can appear in different sections, then the debugger may not
+be able to find the end of a function.  Recent versions of GCC will mark
+the end of a function with an @code{N_FUN} symbol with an empty string
+for the name.  The value is the address of the end of the current
+function.  Without such a symbol, there is no indication of the address
+of the end of a function, and you must assume that it ended at the
+starting address of the next function or at the end of the text section
+for the program.
+
+@node Nested Procedures
+@section Nested Procedures
+
+For any of the symbol descriptors representing procedures, after the
+symbol descriptor and the type information is optionally a scope
+specifier.  This consists of a comma, the name of the procedure, another
+comma, and the name of the enclosing procedure.  The first name is local
+to the scope specified, and seems to be redundant with the name of the
+symbol (before the @samp{:}).  This feature is used by GCC, and
+presumably Pascal, Modula-2, etc., compilers, for nested functions.
+
+If procedures are nested more than one level deep, only the immediately
+containing scope is specified.  For example, this code:
+
+@example
+int
+foo (int x)
+@{
+  int bar (int y)
+    @{
+      int baz (int z)
+        @{
+          return x + y + z;
+        @}
+      return baz (x + 2 * y);
+    @}
+  return x + bar (3 * x);
+@}
+@end example
+
+@noindent
+produces the stabs:
+
+@example
+.stabs "baz:f1,baz,bar",36,0,0,_baz.15         # @r{36 is N_FUN}
+.stabs "bar:f1,bar,foo",36,0,0,_bar.12
+.stabs "foo:F1",36,0,0,_foo
+@end example
+
+@node Block Structure
+@section Block Structure
+
+@findex N_LBRAC
+@findex N_RBRAC
+@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of
+@c function relative (as documented below).  But GDB has never been able
+@c to deal with that (it had wanted them to be relative to the file, but
+@c I just fixed that (between GDB 4.12 and 4.13)), so it is function
+@c relative just like ELF and SOM and the below documentation.
+The program's block structure is represented by the @code{N_LBRAC} (left
+brace) and the @code{N_RBRAC} (right brace) stab types.  The variables
+defined inside a block precede the @code{N_LBRAC} symbol for most
+compilers, including GCC.  Other compilers, such as the Convex, Acorn
+RISC machine, and Sun @code{acc} compilers, put the variables after the
+@code{N_LBRAC} symbol.  The values of the @code{N_LBRAC} and
+@code{N_RBRAC} symbols are the start and end addresses of the code of
+the block, respectively.  For most machines, they are relative to the
+starting address of this source file.  For the Gould NP1, they are
+absolute.  For stabs in sections (@pxref{Stab Sections}), they are
+relative to the function in which they occur.
+
+The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block
+scope of a procedure are located after the @code{N_FUN} stab that
+represents the procedure itself.
+
+Sun documents the desc field of @code{N_LBRAC} and
+@code{N_RBRAC} symbols as containing the nesting level of the block.
+However, dbx seems to not care, and GCC always sets desc to
+zero.
+
+@findex .bb
+@findex .be
+@findex C_BLOCK
+For XCOFF, block scope is indicated with @code{C_BLOCK} symbols.  If the
+name of the symbol is @samp{.bb}, then it is the beginning of the block;
+if the name of the symbol is @samp{.be}; it is the end of the block.
+
+@node Alternate Entry Points
+@section Alternate Entry Points
+
+@findex N_ENTRY
+@findex C_ENTRY
+Some languages, like Fortran, have the ability to enter procedures at
+some place other than the beginning.  One can declare an alternate entry
+point.  The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN
+compiler doesn't use it.  According to AIX documentation, only the name
+of a @code{C_ENTRY} stab is significant; the address of the alternate
+entry point comes from the corresponding external symbol.  A previous
+revision of this document said that the value of an @code{N_ENTRY} stab
+was the address of the alternate entry point, but I don't know the
+source for that information.
+
+@node Constants
+@chapter Constants
+
+The @samp{c} symbol descriptor indicates that this stab represents a
+constant.  This symbol descriptor is an exception to the general rule
+that symbol descriptors are followed by type information.  Instead, it
+is followed by @samp{=} and one of the following:
+
+@table @code
+@item b @var{value}
+Boolean constant.  @var{value} is a numeric value; I assume it is 0 for
+false or 1 for true.
+
+@item c @var{value}
+Character constant.  @var{value} is the numeric value of the constant.
+
+@item e @var{type-information} , @var{value}
+Constant whose value can be represented as integral.
+@var{type-information} is the type of the constant, as it would appear
+after a symbol descriptor (@pxref{String Field}).  @var{value} is the
+numeric value of the constant.  GDB 4.9 does not actually get the right
+value if @var{value} does not fit in a host @code{int}, but it does not
+do anything violent, and future debuggers could be extended to accept
+integers of any size (whether unsigned or not).  This constant type is
+usually documented as being only for enumeration constants, but GDB has
+never imposed that restriction; I don't know about other debuggers.
+
+@item i @var{value}
+Integer constant.  @var{value} is the numeric value.  The type is some
+sort of generic integer type (for GDB, a host @code{int}); to specify
+the type explicitly, use @samp{e} instead.
+
+@item r @var{value}
+Real constant.  @var{value} is the real value, which can be @samp{INF}
+(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet
+NaN (not-a-number), or @samp{SNAN} for a signalling NaN.  If it is a
+normal number the format is that accepted by the C library function
+@code{atof}.
+
+@item s @var{string}
+String constant.  @var{string} is a string enclosed in either @samp{'}
+(in which case @samp{'} characters within the string are represented as
+@samp{\'} or @samp{"} (in which case @samp{"} characters within the
+string are represented as @samp{\"}).
+
+@item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern}
+Set constant.  @var{type-information} is the type of the constant, as it
+would appear after a symbol descriptor (@pxref{String Field}).
+@var{elements} is the number of elements in the set (does this means
+how many bits of @var{pattern} are actually used, which would be
+redundant with the type, or perhaps the number of bits set in
+@var{pattern}?  I don't get it), @var{bits} is the number of bits in the
+constant (meaning it specifies the length of @var{pattern}, I think),
+and @var{pattern} is a hexadecimal representation of the set.  AIX
+documentation refers to a limit of 32 bytes, but I see no reason why
+this limit should exist.  This form could probably be used for arbitrary
+constants, not just sets; the only catch is that @var{pattern} should be
+understood to be target, not host, byte order and format.
+@end table
+
+The boolean, character, string, and set constants are not supported by
+GDB 4.9, but it ignores them.  GDB 4.8 and earlier gave an error
+message and refused to read symbols from the file containing the
+constants.
+
+The above information is followed by @samp{;}.
+
+@node Variables
+@chapter Variables
+
+Different types of stabs describe the various ways that variables can be
+allocated: on the stack, globally, in registers, in common blocks,
+statically, or as arguments to a function.
+
+@menu
+* Stack Variables::		Variables allocated on the stack.
+* Global Variables::		Variables used by more than one source file.
+* Register Variables::		Variables in registers.
+* Common Blocks::		Variables statically allocated together.
+* Statics::			Variables local to one source file.
+* Based Variables::		Fortran pointer based variables.
+* Parameters::			Variables for arguments to functions.
+@end menu
+
+@node Stack Variables
+@section Automatic Variables Allocated on the Stack
+
+If a variable's scope is local to a function and its lifetime is only as
+long as that function executes (C calls such variables
+@dfn{automatic}), it can be allocated in a register (@pxref{Register
+Variables}) or on the stack.
+
+@findex N_LSYM, for stack variables
+@findex C_LSYM
+Each variable allocated on the stack has a stab with the symbol
+descriptor omitted.  Since type information should begin with a digit,
+@samp{-}, or @samp{(}, only those characters precluded from being used
+for symbol descriptors.  However, the Acorn RISC machine (ARM) is said
+to get this wrong: it puts out a mere type definition here, without the
+preceding @samp{@var{type-number}=}.  This is a bad idea; there is no
+guarantee that type descriptors are distinct from symbol descriptors.
+Stabs for stack variables use the @code{N_LSYM} stab type, or
+@code{C_LSYM} for XCOFF.
+
+The value of the stab is the offset of the variable within the
+local variables.  On most machines this is an offset from the frame
+pointer and is negative.  The location of the stab specifies which block
+it is defined in; see @ref{Block Structure}.
+
+For example, the following C code:
+
+@example
+int
+main ()
+@{
+  int x;
+@}
+@end example
+
+produces the following stabs:
+
+@example
+.stabs "main:F1",36,0,0,_main   # @r{36 is N_FUN}
+.stabs "x:1",128,0,0,-12        # @r{128 is N_LSYM}
+.stabn 192,0,0,LBB2             # @r{192 is N_LBRAC}
+.stabn 224,0,0,LBE2             # @r{224 is N_RBRAC}
+@end example
+
+@xref{Procedures} for more information on the @code{N_FUN} stab, and
+@ref{Block Structure} for more information on the @code{N_LBRAC} and
+@code{N_RBRAC} stabs.
+
+@node Global Variables
+@section Global Variables
+
+@findex N_GSYM
+@findex C_GSYM
+@c FIXME: verify for sure that it really is C_GSYM on XCOFF
+A variable whose scope is not specific to just one source file is
+represented by the @samp{G} symbol descriptor.  These stabs use the
+@code{N_GSYM} stab type (C_GSYM for XCOFF).  The type information for
+the stab (@pxref{String Field}) gives the type of the variable.
+
+For example, the following source code:
+
+@example
+char g_foo = 'c';
+@end example
+
+@noindent
+yields the following assembly code:
+
+@example
+.stabs "g_foo:G2",32,0,0,0     # @r{32 is N_GSYM}
+     .global _g_foo
+     .data
+_g_foo:
+     .byte 99
+@end example
+
+The address of the variable represented by the @code{N_GSYM} is not
+contained in the @code{N_GSYM} stab.  The debugger gets this information
+from the external symbol for the global variable.  In the example above,
+the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to
+produce an external symbol.
+
+Some compilers, like GCC, output @code{N_GSYM} stabs only once, where
+the variable is defined.  Other compilers, like SunOS4 /bin/cc, output a
+@code{N_GSYM} stab for each compilation unit which references the
+variable.
+
+@node Register Variables
+@section Register Variables
+
+@findex N_RSYM
+@findex C_RSYM
+@c According to an old version of this manual, AIX uses C_RPSYM instead
+@c of C_RSYM.  I am skeptical; this should be verified.
+Register variables have their own stab type, @code{N_RSYM}
+(@code{C_RSYM} for XCOFF), and their own symbol descriptor, @samp{r}.
+The stab's value is the number of the register where the variable data
+will be stored.
+@c .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc)
+
+AIX defines a separate symbol descriptor @samp{d} for floating point
+registers.  This seems unnecessary; why not just just give floating
+point registers different register numbers?  I have not verified whether
+the compiler actually uses @samp{d}.
+
+If the register is explicitly allocated to a global variable, but not
+initialized, as in:
+
+@example
+register int g_bar asm ("%g5");
+@end example
+
+@noindent
+then the stab may be emitted at the end of the object file, with
+the other bss symbols.
+
+@node Common Blocks
+@section Common Blocks
+
+A common block is a statically allocated section of memory which can be
+referred to by several source files.  It may contain several variables.
+I believe Fortran is the only language with this feature.
+
+@findex N_BCOMM
+@findex N_ECOMM
+@findex C_BCOMM
+@findex C_ECOMM
+A @code{N_BCOMM} stab begins a common block and an @code{N_ECOMM} stab
+ends it.  The only field that is significant in these two stabs is the
+string, which names a normal (non-debugging) symbol that gives the
+address of the common block.  According to IBM documentation, only the
+@code{N_BCOMM} has the name of the common block (even though their
+compiler actually puts it both places).
+
+@findex N_ECOML
+@findex C_ECOML
+The stabs for the members of the common block are between the
+@code{N_BCOMM} and the @code{N_ECOMM}; the value of each stab is the
+offset within the common block of that variable.  IBM uses the
+@code{C_ECOML} stab type, and there is a corresponding @code{N_ECOML}
+stab type, but Sun's Fortran compiler uses @code{N_GSYM} instead.  The
+variables within a common block use the @samp{V} symbol descriptor (I
+believe this is true of all Fortran variables).  Other stabs (at least
+type declarations using @code{C_DECL}) can also be between the
+@code{N_BCOMM} and the @code{N_ECOMM}.
+
+@node Statics
+@section Static Variables
+
+Initialized static variables are represented by the @samp{S} and
+@samp{V} symbol descriptors.  @samp{S} means file scope static, and
+@samp{V} means procedure scope static.  One exception: in XCOFF, IBM's
+xlc compiler always uses @samp{V}, and whether it is file scope or not
+is distinguished by whether the stab is located within a function.
+
+@c This is probably not worth mentioning; it is only true on the sparc
+@c for `double' variables which although declared const are actually in
+@c the data segment (the text segment can't guarantee 8 byte alignment).
+@c (although GCC
+@c 2.4.5 has a bug in that it uses @code{N_FUN}, so neither dbx nor GDB can
+@c find the variables)
+@findex N_STSYM
+@findex N_LCSYM
+@findex N_FUN, for variables
+@findex N_ROSYM
+In a.out files, @code{N_STSYM} means the data section, @code{N_FUN}
+means the text section, and @code{N_LCSYM} means the bss section.  For
+those systems with a read-only data section separate from the text
+section (Solaris), @code{N_ROSYM} means the read-only data section.
+
+For example, the source lines:
+
+@example
+static const int var_const = 5;
+static int var_init = 2;
+static int var_noinit;
+@end example
+
+@noindent
+yield the following stabs:
+
+@example
+.stabs "var_const:S1",36,0,0,_var_const      # @r{36 is N_FUN}
+@dots{}
+.stabs "var_init:S1",38,0,0,_var_init        # @r{38 is N_STSYM}
+@dots{}
+.stabs "var_noinit:S1",40,0,0,_var_noinit    # @r{40 is N_LCSYM}
+@end example
+
+@findex C_STSYM
+@findex C_BSTAT
+@findex C_ESTAT
+In XCOFF files, the stab type need not indicate the section;
+@code{C_STSYM} can be used for all statics.  Also, each static variable
+is enclosed in a static block.  A @code{C_BSTAT} (emitted with a
+@samp{.bs} assembler directive) symbol begins the static block; its
+value is the symbol number of the csect symbol whose value is the
+address of the static block, its section is the section of the variables
+in that static block, and its name is @samp{.bs}.  A @code{C_ESTAT}
+(emitted with a @samp{.es} assembler directive) symbol ends the static
+block; its name is @samp{.es} and its value and section are ignored.
+
+In ECOFF files, the storage class is used to specify the section, so the
+stab type need not indicate the section.
+
+In ELF files, for the SunPRO compiler version 2.0.1, symbol descriptor
+@samp{S} means that the address is absolute (the linker relocates it)
+and symbol descriptor @samp{V} means that the address is relative to the
+start of the relevant section for that compilation unit.  SunPRO has
+plans to have the linker stop relocating stabs; I suspect that their the
+debugger gets the address from the corresponding ELF (not stab) symbol.
+I'm not sure how to find which symbol of that name is the right one.
+The clean way to do all this would be to have a the value of a symbol
+descriptor @samp{S} symbol be an offset relative to the start of the
+file, just like everything else, but that introduces obvious
+compatibility problems.  For more information on linker stab relocation,
+@xref{ELF Linker Relocation}.
+
+@node Based Variables
+@section Fortran Based Variables
+
+Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature
+which allows allocating arrays with @code{malloc}, but which avoids
+blurring the line between arrays and pointers the way that C does.  In
+stabs such a variable uses the @samp{b} symbol descriptor.
+
+For example, the Fortran declarations
+
+@example
+real foo, foo10(10), foo10_5(10,5)
+pointer (foop, foo)
+pointer (foo10p, foo10)
+pointer (foo105p, foo10_5)
+@end example
+
+produce the stabs
+
+@example
+foo:b6
+foo10:bar3;1;10;6
+foo10_5:bar3;1;5;ar3;1;10;6
+@end example
+
+In this example, @code{real} is type 6 and type 3 is an integral type
+which is the type of the subscripts of the array (probably
+@code{integer}).
+
+The @samp{b} symbol descriptor is like @samp{V} in that it denotes a
+statically allocated symbol whose scope is local to a function; see
+@xref{Statics}.  The value of the symbol, instead of being the address
+of the variable itself, is the address of a pointer to that variable.
+So in the above example, the value of the @code{foo} stab is the address
+of a pointer to a real, the value of the @code{foo10} stab is the
+address of a pointer to a 10-element array of reals, and the value of
+the @code{foo10_5} stab is the address of a pointer to a 5-element array
+of 10-element arrays of reals.
+
+@node Parameters
+@section Parameters
+
+Formal parameters to a function are represented by a stab (or sometimes
+two; see below) for each parameter.  The stabs are in the order in which
+the debugger should print the parameters (i.e., the order in which the
+parameters are declared in the source file).  The exact form of the stab
+depends on how the parameter is being passed.
+
+@findex N_PSYM
+@findex C_PSYM
+Parameters passed on the stack use the symbol descriptor @samp{p} and
+the @code{N_PSYM} symbol type (or @code{C_PSYM} for XCOFF).  The value
+of the symbol is an offset used to locate the parameter on the stack;
+its exact meaning is machine-dependent, but on most machines it is an
+offset from the frame pointer.
+
+As a simple example, the code:
+
+@example
+main (argc, argv)
+     int argc;
+     char **argv;
+@end example
+
+produces the stabs:
+
+@example
+.stabs "main:F1",36,0,0,_main                 # @r{36 is N_FUN}
+.stabs "argc:p1",160,0,0,68                   # @r{160 is N_PSYM}
+.stabs "argv:p20=*21=*2",160,0,0,72
+@end example
+
+The type definition of @code{argv} is interesting because it contains
+several type definitions.  Type 21 is pointer to type 2 (char) and
+@code{argv} (type 20) is pointer to type 21.
+
+@c FIXME: figure out what these mean and describe them coherently.
+The following symbol descriptors are also said to go with @code{N_PSYM}.
+The value of the symbol is said to be an offset from the argument
+pointer (I'm not sure whether this is true or not).
+
+@example
+pP (<<??>>)
+pF Fortran function parameter
+X  (function result variable)
+@end example
+
+@menu
+* Register Parameters::
+* Local Variable Parameters::
+* Reference Parameters::
+* Conformant Arrays::
+@end menu
+
+@node Register Parameters
+@subsection Passing Parameters in Registers
+
+If the parameter is passed in a register, then traditionally there are
+two symbols for each argument:
+
+@example
+.stabs "arg:p1" . . .       ; N_PSYM
+.stabs "arg:r1" . . .       ; N_RSYM
+@end example
+
+Debuggers use the second one to find the value, and the first one to
+know that it is an argument.
+
+@findex C_RPSYM
+@findex N_RSYM, for parameters
+Because that approach is kind of ugly, some compilers use symbol
+descriptor @samp{P} or @samp{R} to indicate an argument which is in a
+register.  Symbol type @code{C_RPSYM} is used in XCOFF and @code{N_RSYM}
+is used otherwise.  The symbol's value is the register number.  @samp{P}
+and @samp{R} mean the same thing; the difference is that @samp{P} is a
+GNU invention and @samp{R} is an IBM (XCOFF) invention.  As of version
+4.9, GDB should handle either one.
+
+There is at least one case where GCC uses a @samp{p} and @samp{r} pair
+rather than @samp{P}; this is where the argument is passed in the
+argument list and then loaded into a register.
+
+According to the AIX documentation, symbol descriptor @samp{D} is for a
+parameter passed in a floating point register.  This seems
+unnecessary---why not just use @samp{R} with a register number which
+indicates that it's a floating point register?  I haven't verified
+whether the system actually does what the documentation indicates.
+
+@c FIXME: On the hppa this is for any type > 8 bytes, I think, and not
+@c for small structures (investigate).
+On the sparc and hppa, for a @samp{P} symbol whose type is a structure
+or union, the register contains the address of the structure.  On the
+sparc, this is also true of a @samp{p} and @samp{r} pair (using Sun
+@code{cc}) or a @samp{p} symbol.  However, if a (small) structure is
+really in a register, @samp{r} is used.  And, to top it all off, on the
+hppa it might be a structure which was passed on the stack and loaded
+into a register and for which there is a @samp{p} and @samp{r} pair!  I
+believe that symbol descriptor @samp{i} is supposed to deal with this
+case (it is said to mean "value parameter by reference, indirect
+access"; I don't know the source for this information), but I don't know
+details or what compilers or debuggers use it, if any (not GDB or GCC).
+It is not clear to me whether this case needs to be dealt with
+differently than parameters passed by reference (@pxref{Reference Parameters}).
+
+@node Local Variable Parameters
+@subsection Storing Parameters as Local Variables
+
+There is a case similar to an argument in a register, which is an
+argument that is actually stored as a local variable.  Sometimes this
+happens when the argument was passed in a register and then the compiler
+stores it as a local variable.  If possible, the compiler should claim
+that it's in a register, but this isn't always done.
+
+If a parameter is passed as one type and converted to a smaller type by
+the prologue (for example, the parameter is declared as a @code{float},
+but the calling conventions specify that it is passed as a
+@code{double}), then GCC2 (sometimes) uses a pair of symbols.  The first
+symbol uses symbol descriptor @samp{p} and the type which is passed.
+The second symbol has the type and location which the parameter actually
+has after the prologue.  For example, suppose the following C code
+appears with no prototypes involved:
+
+@example
+void
+subr (f)
+     float f;
+@{
+@end example
+
+if @code{f} is passed as a double at stack offset 8, and the prologue
+converts it to a float in register number 0, then the stabs look like:
+
+@example
+.stabs "f:p13",160,0,3,8   # @r{160 is @code{N_PSYM}, here 13 is @code{double}}
+.stabs "f:r12",64,0,3,0    # @r{64 is @code{N_RSYM}, here 12 is @code{float}}
+@end example
+
+In both stabs 3 is the line number where @code{f} is declared
+(@pxref{Line Numbers}).
+
+@findex N_LSYM, for parameter
+GCC, at least on the 960, has another solution to the same problem.  It
+uses a single @samp{p} symbol descriptor for an argument which is stored
+as a local variable but uses @code{N_LSYM} instead of @code{N_PSYM}.  In
+this case, the value of the symbol is an offset relative to the local
+variables for that function, not relative to the arguments; on some
+machines those are the same thing, but not on all.
+
+@c This is mostly just background info; the part that logically belongs
+@c here is the last sentence.  
+On the VAX or on other machines in which the calling convention includes
+the number of words of arguments actually passed, the debugger (GDB at
+least) uses the parameter symbols to keep track of whether it needs to
+print nameless arguments in addition to the formal parameters which it
+has printed because each one has a stab.  For example, in 
+
+@example
+extern int fprintf (FILE *stream, char *format, @dots{});
+@dots{}
+fprintf (stdout, "%d\n", x);
+@end example
+
+there are stabs for @code{stream} and @code{format}.  On most machines,
+the debugger can only print those two arguments (because it has no way
+of knowing that additional arguments were passed), but on the VAX or
+other machines with a calling convention which indicates the number of
+words of arguments, the debugger can print all three arguments.  To do
+so, the parameter symbol (symbol descriptor @samp{p}) (not necessarily
+@samp{r} or symbol descriptor omitted symbols) needs to contain the
+actual type as passed (for example, @code{double} not @code{float} if it
+is passed as a double and converted to a float).
+
+@node Reference Parameters
+@subsection Passing Parameters by Reference
+
+If the parameter is passed by reference (e.g., Pascal @code{VAR}
+parameters), then the symbol descriptor is @samp{v} if it is in the
+argument list, or @samp{a} if it in a register.  Other than the fact
+that these contain the address of the parameter rather than the
+parameter itself, they are identical to @samp{p} and @samp{R},
+respectively.  I believe @samp{a} is an AIX invention; @samp{v} is
+supported by all stabs-using systems as far as I know.
+
+@node Conformant Arrays
+@subsection Passing Conformant Array Parameters
+
+@c Is this paragraph correct?  It is based on piecing together patchy
+@c information and some guesswork
+Conformant arrays are a feature of Modula-2, and perhaps other
+languages, in which the size of an array parameter is not known to the
+called function until run-time.  Such parameters have two stabs: a
+@samp{x} for the array itself, and a @samp{C}, which represents the size
+of the array.  The value of the @samp{x} stab is the offset in the
+argument list where the address of the array is stored (it this right?
+it is a guess); the value of the @samp{C} stab is the offset in the
+argument list where the size of the array (in elements? in bytes?) is
+stored.
+
+@node Types
+@chapter Defining Types
+
+The examples so far have described types as references to previously
+defined types, or defined in terms of subranges of or pointers to
+previously defined types.  This chapter describes the other type
+descriptors that may follow the @samp{=} in a type definition.
+
+@menu
+* Builtin Types::		Integers, floating point, void, etc.
+* Miscellaneous Types::		Pointers, sets, files, etc.
+* Cross-References::		Referring to a type not yet defined.
+* Subranges::			A type with a specific range.
+* Arrays::			An aggregate type of same-typed elements.
+* Strings::			Like an array but also has a length.
+* Enumerations::		Like an integer but the values have names.
+* Structures::			An aggregate type of different-typed elements.
+* Typedefs::			Giving a type a name.
+* Unions::			Different types sharing storage.
+* Function Types::
+@end menu
+
+@node Builtin Types
+@section Builtin Types
+
+Certain types are built in (@code{int}, @code{short}, @code{void},
+@code{float}, etc.); the debugger recognizes these types and knows how
+to handle them.  Thus, don't be surprised if some of the following ways
+of specifying builtin types do not specify everything that a debugger
+would need to know about the type---in some cases they merely specify
+enough information to distinguish the type from other types.
+
+The traditional way to define builtin types is convolunted, so new ways
+have been invented to describe them.  Sun's @code{acc} uses special
+builtin type descriptors (@samp{b} and @samp{R}), and IBM uses negative
+type numbers.  GDB accepts all three ways, as of version 4.8; dbx just
+accepts the traditional builtin types and perhaps one of the other two
+formats.  The following sections describe each of these formats.
+
+@menu
+* Traditional Builtin Types::	Put on your seatbelts and prepare for kludgery
+* Builtin Type Descriptors::	Builtin types with special type descriptors
+* Negative Type Numbers::	Builtin types using negative type numbers
+@end menu
+
+@node Traditional Builtin Types
+@subsection Traditional Builtin Types
+
+This is the traditional, convoluted method for defining builtin types.
+There are several classes of such type definitions: integer, floating
+point, and @code{void}.
+
+@menu
+* Traditional Integer Types::
+* Traditional Other Types::
+@end menu
+
+@node Traditional Integer Types
+@subsubsection Traditional Integer Types
+
+Often types are defined as subranges of themselves.  If the bounding values
+fit within an @code{int}, then they are given normally.  For example:
+
+@example
+.stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0    # @r{128 is N_LSYM}
+.stabs "char:t2=r2;0;127;",128,0,0,0
+@end example
+
+Builtin types can also be described as subranges of @code{int}:
+
+@example
+.stabs "unsigned short:t6=r1;0;65535;",128,0,0,0
+@end example
+
+If the lower bound of a subrange is 0 and the upper bound is -1,
+the type is an unsigned integral type whose bounds are too
+big to describe in an @code{int}.  Traditionally this is only used for
+@code{unsigned int} and @code{unsigned long}:
+
+@example
+.stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
+@end example
+
+For larger types, GCC 2.4.5 puts out bounds in octal, with one or more
+leading zeroes.  In this case a negative bound consists of a number
+which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in
+the number (except the sign bit), and a positive bound is one which is a
+1 bit for each bit in the number (except possibly the sign bit).  All
+known versions of dbx and GDB version 4 accept this (at least in the
+sense of not refusing to process the file), but GDB 3.5 refuses to read
+the whole file containing such symbols.  So GCC 2.3.3 did not output the
+proper size for these types.  As an example of octal bounds, the string
+fields of the stabs for 64 bit integer types look like:
+
+@c .stabs directives, etc., omitted to make it fit on the page.
+@example
+long int:t3=r1;001000000000000000000000;000777777777777777777777;
+long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777;
+@end example
+
+If the lower bound of a subrange is 0 and the upper bound is negative,
+the type is an unsigned integral type whose size in bytes is the
+absolute value of the upper bound.  I believe this is a Convex
+convention for @code{unsigned long long}.
+
+If the lower bound of a subrange is negative and the upper bound is 0,
+the type is a signed integral type whose size in bytes is
+the absolute value of the lower bound.  I believe this is a Convex
+convention for @code{long long}.  To distinguish this from a legitimate
+subrange, the type should be a subrange of itself.  I'm not sure whether
+this is the case for Convex.
+
+@node Traditional Other Types
+@subsubsection Traditional Other Types
+
+If the upper bound of a subrange is 0 and the lower bound is positive,
+the type is a floating point type, and the lower bound of the subrange
+indicates the number of bytes in the type:
+
+@example
+.stabs "float:t12=r1;4;0;",128,0,0,0
+.stabs "double:t13=r1;8;0;",128,0,0,0
+@end example
+
+However, GCC writes @code{long double} the same way it writes
+@code{double}, so there is no way to distinguish.
+
+@example
+.stabs "long double:t14=r1;8;0;",128,0,0,0
+@end example
+
+Complex types are defined the same way as floating-point types; there is
+no way to distinguish a single-precision complex from a double-precision
+floating-point type.
+
+The C @code{void} type is defined as itself:
+
+@example
+.stabs "void:t15=15",128,0,0,0
+@end example
+
+I'm not sure how a boolean type is represented.
+
+@node Builtin Type Descriptors
+@subsection Defining Builtin Types Using Builtin Type Descriptors
+
+This is the method used by Sun's @code{acc} for defining builtin types.
+These are the type descriptors to define builtin types:
+
+@table @code
+@c FIXME: clean up description of width and offset, once we figure out
+@c what they mean
+@item b @var{signed} @var{char-flag} @var{width} ; @var{offset} ; @var{nbits} ;
+Define an integral type.  @var{signed} is @samp{u} for unsigned or
+@samp{s} for signed.  @var{char-flag} is @samp{c} which indicates this
+is a character type, or is omitted.  I assume this is to distinguish an
+integral type from a character type of the same size, for example it
+might make sense to set it for the C type @code{wchar_t} so the debugger
+can print such variables differently (Solaris does not do this).  Sun
+sets it on the C types @code{signed char} and @code{unsigned char} which
+arguably is wrong.  @var{width} and @var{offset} appear to be for small
+objects stored in larger ones, for example a @code{short} in an
+@code{int} register.  @var{width} is normally the number of bytes in the
+type.  @var{offset} seems to always be zero.  @var{nbits} is the number
+of bits in the type.
+
+Note that type descriptor @samp{b} used for builtin types conflicts with
+its use for Pascal space types (@pxref{Miscellaneous Types}); they can
+be distinguished because the character following the type descriptor
+will be a digit, @samp{(}, or @samp{-} for a Pascal space type, or
+@samp{u} or @samp{s} for a builtin type.
+
+@item w
+Documented by AIX to define a wide character type, but their compiler
+actually uses negative type numbers (@pxref{Negative Type Numbers}).
+
+@item R @var{fp-type} ; @var{bytes} ;
+Define a floating point type.  @var{fp-type} has one of the following values:
+
+@table @code
+@item 1 (NF_SINGLE)
+IEEE 32-bit (single precision) floating point format.
+
+@item 2 (NF_DOUBLE)
+IEEE 64-bit (double precision) floating point format.
+
+@item 3 (NF_COMPLEX)
+@item 4 (NF_COMPLEX16)
+@item 5 (NF_COMPLEX32)
+@c "GDB source" really means @file{include/aout/stab_gnu.h}, but trying
+@c to put that here got an overfull hbox.
+These are for complex numbers.  A comment in the GDB source describes
+them as Fortran @code{complex}, @code{double complex}, and
+@code{complex*16}, respectively, but what does that mean?  (i.e., Single
+precision?  Double precison?).
+
+@item 6 (NF_LDOUBLE)
+Long double.  This should probably only be used for Sun format
+@code{long double}, and new codes should be used for other floating
+point formats (@code{NF_DOUBLE} can be used if a @code{long double} is
+really just an IEEE double, of course).
+@end table
+
+@var{bytes} is the number of bytes occupied by the type.  This allows a
+debugger to perform some operations with the type even if it doesn't
+understand @var{fp-type}.
+
+@item g @var{type-information} ; @var{nbits}
+Documented by AIX to define a floating type, but their compiler actually
+uses negative type numbers (@pxref{Negative Type Numbers}).
+
+@item c @var{type-information} ; @var{nbits}
+Documented by AIX to define a complex type, but their compiler actually
+uses negative type numbers (@pxref{Negative Type Numbers}).
+@end table
+
+The C @code{void} type is defined as a signed integral type 0 bits long:
+@example
+.stabs "void:t19=bs0;0;0",128,0,0,0
+@end example
+The Solaris compiler seems to omit the trailing semicolon in this case.
+Getting sloppy in this way is not a swift move because if a type is
+embedded in a more complex expression it is necessary to be able to tell
+where it ends.
+
+I'm not sure how a boolean type is represented.
+
+@node Negative Type Numbers
+@subsection Negative Type Numbers
+
+This is the method used in XCOFF for defining builtin types.
+Since the debugger knows about the builtin types anyway, the idea of
+negative type numbers is simply to give a special type number which
+indicates the builtin type.  There is no stab defining these types.
+
+There are several subtle issues with negative type numbers.
+
+One is the size of the type.  A builtin type (for example the C types
+@code{int} or @code{long}) might have different sizes depending on
+compiler options, the target architecture, the ABI, etc.  This issue
+doesn't come up for IBM tools since (so far) they just target the
+RS/6000; the sizes indicated below for each size are what the IBM
+RS/6000 tools use.  To deal with differing sizes, either define separate
+negative type numbers for each size (which works but requires changing
+the debugger, and, unless you get both AIX dbx and GDB to accept the
+change, introduces an incompatibility), or use a type attribute
+(@pxref{String Field}) to define a new type with the appropriate size
+(which merely requires a debugger which understands type attributes,
+like AIX dbx or GDB).  For example,
+
+@example
+.stabs "boolean:t10=@@s8;-16",128,0,0,0
+@end example
+
+defines an 8-bit boolean type, and
+
+@example
+.stabs "boolean:t10=@@s64;-16",128,0,0,0
+@end example
+
+defines a 64-bit boolean type.
+
+A similar issue is the format of the type.  This comes up most often for
+floating-point types, which could have various formats (particularly
+extended doubles, which vary quite a bit even among IEEE systems).
+Again, it is best to define a new negative type number for each
+different format; changing the format based on the target system has
+various problems.  One such problem is that the Alpha has both VAX and
+IEEE floating types.  One can easily imagine one library using the VAX
+types and another library in the same executable using the IEEE types.
+Another example is that the interpretation of whether a boolean is true
+or false can be based on the least significant bit, most significant
+bit, whether it is zero, etc., and different compilers (or different
+options to the same compiler) might provide different kinds of boolean.
+
+The last major issue is the names of the types.  The name of a given
+type depends @emph{only} on the negative type number given; these do not
+vary depending on the language, the target system, or anything else.
+One can always define separate type numbers---in the following list you
+will see for example separate @code{int} and @code{integer*4} types
+which are identical except for the name.  But compatibility can be
+maintained by not inventing new negative type numbers and instead just
+defining a new type with a new name.  For example:
+
+@example
+.stabs "CARDINAL:t10=-8",128,0,0,0
+@end example
+
+Here is the list of negative type numbers.  The phrase @dfn{integral
+type} is used to mean twos-complement (I strongly suspect that all
+machines which use stabs use twos-complement; most machines use
+twos-complement these days).
+
+@table @code
+@item -1
+@code{int}, 32 bit signed integral type.
+
+@item -2
+@code{char}, 8 bit type holding a character.   Both GDB and dbx on AIX
+treat this as signed.  GCC uses this type whether @code{char} is signed
+or not, which seems like a bad idea.  The AIX compiler (@code{xlc}) seems to
+avoid this type; it uses -5 instead for @code{char}.
+
+@item -3
+@code{short}, 16 bit signed integral type.
+
+@item -4
+@code{long}, 32 bit signed integral type.
+
+@item -5
+@code{unsigned char}, 8 bit unsigned integral type.
+
+@item -6
+@code{signed char}, 8 bit signed integral type.
+
+@item -7
+@code{unsigned short}, 16 bit unsigned integral type.
+
+@item -8
+@code{unsigned int}, 32 bit unsigned integral type.
+
+@item -9
+@code{unsigned}, 32 bit unsigned integral type.
+
+@item -10
+@code{unsigned long}, 32 bit unsigned integral type.
+
+@item -11
+@code{void}, type indicating the lack of a value.
+
+@item -12
+@code{float}, IEEE single precision.
+
+@item -13
+@code{double}, IEEE double precision.
+
+@item -14
+@code{long double}, IEEE double precision.  The compiler claims the size
+will increase in a future release, and for binary compatibility you have
+to avoid using @code{long double}.  I hope when they increase it they
+use a new negative type number.
+
+@item -15
+@code{integer}.  32 bit signed integral type.
+
+@item -16
+@code{boolean}.  32 bit type.  GDB and GCC assume that zero is false,
+one is true, and other values have unspecified meaning.  I hope this
+agrees with how the IBM tools use the type.
+
+@item -17
+@code{short real}.  IEEE single precision.
+
+@item -18
+@code{real}.  IEEE double precision.
+
+@item -19
+@code{stringptr}.  @xref{Strings}.
+
+@item -20
+@code{character}, 8 bit unsigned character type.
+
+@item -21
+@code{logical*1}, 8 bit type.  This Fortran type has a split
+personality in that it is used for boolean variables, but can also be
+used for unsigned integers.  0 is false, 1 is true, and other values are
+non-boolean.
+
+@item -22
+@code{logical*2}, 16 bit type.  This Fortran type has a split
+personality in that it is used for boolean variables, but can also be
+used for unsigned integers.  0 is false, 1 is true, and other values are
+non-boolean.
+
+@item -23
+@code{logical*4}, 32 bit type.  This Fortran type has a split
+personality in that it is used for boolean variables, but can also be
+used for unsigned integers.  0 is false, 1 is true, and other values are
+non-boolean.
+
+@item -24
+@code{logical}, 32 bit type.  This Fortran type has a split
+personality in that it is used for boolean variables, but can also be
+used for unsigned integers.  0 is false, 1 is true, and other values are
+non-boolean.
+
+@item -25
+@code{complex}.  A complex type consisting of two IEEE single-precision
+floating point values.
+
+@item -26
+@code{complex}.  A complex type consisting of two IEEE double-precision
+floating point values.
+
+@item -27
+@code{integer*1}, 8 bit signed integral type.
+
+@item -28
+@code{integer*2}, 16 bit signed integral type.
+
+@item -29
+@code{integer*4}, 32 bit signed integral type.
+
+@item -30
+@code{wchar}.  Wide character, 16 bits wide, unsigned (what format?
+Unicode?).
+
+@item -31
+@code{long long}, 64 bit signed integral type.
+
+@item -32
+@code{unsigned long long}, 64 bit unsigned integral type.
+
+@item -33
+@code{logical*8}, 64 bit unsigned integral type.
+
+@item -34
+@code{integer*8}, 64 bit signed integral type.
+@end table
+
+@node Miscellaneous Types
+@section Miscellaneous Types
+
+@table @code
+@item b @var{type-information} ; @var{bytes}
+Pascal space type.  This is documented by IBM; what does it mean?
+
+This use of the @samp{b} type descriptor can be distinguished
+from its use for builtin integral types (@pxref{Builtin Type
+Descriptors}) because the character following the type descriptor is
+always a digit, @samp{(}, or @samp{-}.
+
+@item B @var{type-information}
+A volatile-qualified version of @var{type-information}.  This is
+a Sun extension.  References and stores to a variable with a
+volatile-qualified type must not be optimized or cached; they
+must occur as the user specifies them.
+
+@item d @var{type-information}
+File of type @var{type-information}.  As far as I know this is only used
+by Pascal.
+
+@item k @var{type-information}
+A const-qualified version of @var{type-information}.  This is a Sun
+extension.  A variable with a const-qualified type cannot be modified.
+
+@item M @var{type-information} ; @var{length}
+Multiple instance type.  The type seems to composed of @var{length}
+repetitions of @var{type-information}, for example @code{character*3} is
+represented by @samp{M-2;3}, where @samp{-2} is a reference to a
+character type (@pxref{Negative Type Numbers}).  I'm not sure how this
+differs from an array.  This appears to be a Fortran feature.
+@var{length} is a bound, like those in range types; see @ref{Subranges}.
+
+@item S @var{type-information}
+Pascal set type.  @var{type-information} must be a small type such as an
+enumeration or a subrange, and the type is a bitmask whose length is
+specified by the number of elements in @var{type-information}.
+
+In CHILL, if it is a bitstring instead of a set, also use the @samp{S}
+type attribute (@pxref{String Field}).
+
+@item * @var{type-information}
+Pointer to @var{type-information}.
+@end table
+
+@node Cross-References
+@section Cross-References to Other Types
+
+A type can be used before it is defined; one common way to deal with
+that situation is just to use a type reference to a type which has not
+yet been defined.
+
+Another way is with the @samp{x} type descriptor, which is followed by
+@samp{s} for a structure tag, @samp{u} for a union tag, or @samp{e} for
+a enumerator tag, followed by the name of the tag, followed by @samp{:}.
+If the name contains @samp{::} between a @samp{<} and @samp{>} pair (for
+C++ templates), such a @samp{::} does not end the name---only a single
+@samp{:} ends the name; see @ref{Nested Symbols}.
+
+For example, the following C declarations:
+
+@example
+struct foo;
+struct foo *bar;
+@end example
+
+@noindent
+produce:
+
+@example
+.stabs "bar:G16=*17=xsfoo:",32,0,0,0
+@end example
+
+Not all debuggers support the @samp{x} type descriptor, so on some
+machines GCC does not use it.  I believe that for the above example it
+would just emit a reference to type 17 and never define it, but I
+haven't verified that.
+
+Modula-2 imported types, at least on AIX, use the @samp{i} type
+descriptor, which is followed by the name of the module from which the
+type is imported, followed by @samp{:}, followed by the name of the
+type.  There is then optionally a comma followed by type information for
+the type.  This differs from merely naming the type (@pxref{Typedefs}) in
+that it identifies the module; I don't understand whether the name of
+the type given here is always just the same as the name we are giving
+it, or whether this type descriptor is used with a nameless stab
+(@pxref{String Field}), or what.  The symbol ends with @samp{;}.
+
+@node Subranges
+@section Subrange Types
+
+The @samp{r} type descriptor defines a type as a subrange of another
+type.  It is followed by type information for the type of which it is a
+subrange, a semicolon, an integral lower bound, a semicolon, an
+integral upper bound, and a semicolon.  The AIX documentation does not
+specify the trailing semicolon, in an effort to specify array indexes
+more cleanly, but a subrange which is not an array index has always
+included a trailing semicolon (@pxref{Arrays}).
+
+Instead of an integer, either bound can be one of the following:
+
+@table @code
+@item A @var{offset}
+The bound is passed by reference on the stack at offset @var{offset}
+from the argument list.  @xref{Parameters}, for more information on such
+offsets.
+
+@item T @var{offset}
+The bound is passed by value on the stack at offset @var{offset} from
+the argument list.
+
+@item a @var{register-number}
+The bound is pased by reference in register number
+@var{register-number}.
+
+@item t @var{register-number}
+The bound is passed by value in register number @var{register-number}.
+
+@item J
+There is no bound.
+@end table
+
+Subranges are also used for builtin types; see @ref{Traditional Builtin Types}.
+
+@node Arrays
+@section Array Types
+
+Arrays use the @samp{a} type descriptor.  Following the type descriptor
+is the type of the index and the type of the array elements.  If the
+index type is a range type, it ends in a semicolon; otherwise
+(for example, if it is a type reference), there does not
+appear to be any way to tell where the types are separated.  In an
+effort to clean up this mess, IBM documents the two types as being
+separated by a semicolon, and a range type as not ending in a semicolon
+(but this is not right for range types which are not array indexes,
+@pxref{Subranges}).  I think probably the best solution is to specify
+that a semicolon ends a range type, and that the index type and element
+type of an array are separated by a semicolon, but that if the index
+type is a range type, the extra semicolon can be omitted.  GDB (at least
+through version 4.9) doesn't support any kind of index type other than a
+range anyway; I'm not sure about dbx.
+
+It is well established, and widely used, that the type of the index,
+unlike most types found in the stabs, is merely a type definition, not
+type information (@pxref{String Field}) (that is, it need not start with
+@samp{@var{type-number}=} if it is defining a new type).  According to a
+comment in GDB, this is also true of the type of the array elements; it
+gives @samp{ar1;1;10;ar1;1;10;4} as a legitimate way to express a two
+dimensional array.  According to AIX documentation, the element type
+must be type information.  GDB accepts either.
+
+The type of the index is often a range type, expressed as the type
+descriptor @samp{r} and some parameters.  It defines the size of the
+array.  In the example below, the range @samp{r1;0;2;} defines an index
+type which is a subrange of type 1 (integer), with a lower bound of 0
+and an upper bound of 2.  This defines the valid range of subscripts of
+a three-element C array.
+
+For example, the definition:
+
+@example
+char char_vec[3] = @{'a','b','c'@};
+@end example
+
+@noindent
+produces the output:
+
+@example
+.stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
+     .global _char_vec
+     .align 4
+_char_vec:
+     .byte 97
+     .byte 98
+     .byte 99
+@end example
+
+If an array is @dfn{packed}, the elements are spaced more
+closely than normal, saving memory at the expense of speed.  For
+example, an array of 3-byte objects might, if unpacked, have each
+element aligned on a 4-byte boundary, but if packed, have no padding.
+One way to specify that something is packed is with type attributes
+(@pxref{String Field}).  In the case of arrays, another is to use the
+@samp{P} type descriptor instead of @samp{a}.  Other than specifying a
+packed array, @samp{P} is identical to @samp{a}.
+
+@c FIXME-what is it?  A pointer?
+An open array is represented by the @samp{A} type descriptor followed by
+type information specifying the type of the array elements.
+
+@c FIXME: what is the format of this type?  A pointer to a vector of pointers?
+An N-dimensional dynamic array is represented by
+
+@example
+D @var{dimensions} ; @var{type-information}
+@end example
+
+@c Does dimensions really have this meaning?  The AIX documentation
+@c doesn't say.
+@var{dimensions} is the number of dimensions; @var{type-information}
+specifies the type of the array elements.
+
+@c FIXME: what is the format of this type?  A pointer to some offsets in
+@c another array?
+A subarray of an N-dimensional array is represented by
+
+@example
+E @var{dimensions} ; @var{type-information}
+@end example
+
+@c Does dimensions really have this meaning?  The AIX documentation
+@c doesn't say.
+@var{dimensions} is the number of dimensions; @var{type-information}
+specifies the type of the array elements.
+
+@node Strings
+@section Strings
+
+Some languages, like C or the original Pascal, do not have string types,
+they just have related things like arrays of characters.  But most
+Pascals and various other languages have string types, which are
+indicated as follows:
+
+@table @code
+@item n @var{type-information} ; @var{bytes}
+@var{bytes} is the maximum length.  I'm not sure what
+@var{type-information} is; I suspect that it means that this is a string
+of @var{type-information} (thus allowing a string of integers, a string
+of wide characters, etc., as well as a string of characters).  Not sure
+what the format of this type is.  This is an AIX feature.
+
+@item z @var{type-information} ; @var{bytes}
+Just like @samp{n} except that this is a gstring, not an ordinary
+string.  I don't know the difference.
+
+@item N
+Pascal Stringptr.  What is this?  This is an AIX feature.
+@end table
+
+Languages, such as CHILL which have a string type which is basically
+just an array of characters use the @samp{S} type attribute
+(@pxref{String Field}).
+
+@node Enumerations
+@section Enumerations
+
+Enumerations are defined with the @samp{e} type descriptor.
+
+@c FIXME: Where does this information properly go?  Perhaps it is
+@c redundant with something we already explain.
+The source line below declares an enumeration type at file scope.
+The type definition is located after the @code{N_RBRAC} that marks the end of
+the previous procedure's block scope, and before the @code{N_FUN} that marks
+the beginning of the next procedure's block scope.  Therefore it does not
+describe a block local symbol, but a file local one.
+
+The source line:
+
+@example
+enum e_places @{first,second=3,last@};
+@end example
+
+@noindent
+generates the following stab:
+
+@example
+.stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
+@end example
+
+The symbol descriptor (@samp{T}) says that the stab describes a
+structure, enumeration, or union tag.  The type descriptor @samp{e},
+following the @samp{22=} of the type definition narrows it down to an
+enumeration type.  Following the @samp{e} is a list of the elements of
+the enumeration.  The format is @samp{@var{name}:@var{value},}.  The
+list of elements ends with @samp{;}.  The fact that @var{value} is
+specified as an integer can cause problems if the value is large.  GCC
+2.5.2 tries to output it in octal in that case with a leading zero,
+which is probably a good thing, although GDB 4.11 supports octal only in
+cases where decimal is perfectly good.  Negative decimal values are
+supported by both GDB and dbx.
+
+There is no standard way to specify the size of an enumeration type; it
+is determined by the architecture (normally all enumerations types are
+32 bits).  Type attributes can be used to specify an enumeration type of
+another size for debuggers which support them; see @ref{String Field}.
+
+Enumeration types are unusual in that they define symbols for the
+enumeration values (@code{first}, @code{second}, and @code{third} in the
+above example), and even though these symbols are visible in the file as
+a whole (rather than being in a more local namespace like structure
+member names), they are defined in the type definition for the
+enumeration type rather than each having their own symbol.  In order to
+be fast, GDB will only get symbols from such types (in its initial scan
+of the stabs) if the type is the first thing defined after a @samp{T} or
+@samp{t} symbol descriptor (the above example fulfills this
+requirement).  If the type does not have a name, the compiler should
+emit it in a nameless stab (@pxref{String Field}); GCC does this.
+
+@node Structures
+@section Structures
+
+The encoding of structures in stabs can be shown with an example.
+
+The following source code declares a structure tag and defines an
+instance of the structure in global scope. Then a @code{typedef} equates the
+structure tag with a new type.  Seperate stabs are generated for the
+structure tag, the structure @code{typedef}, and the structure instance.  The
+stabs for the tag and the @code{typedef} are emited when the definitions are
+encountered.  Since the structure elements are not initialized, the
+stab and code for the structure variable itself is located at the end
+of the program in the bss section.
+
+@example
+struct s_tag @{
+  int   s_int;
+  float s_float;
+  char  s_char_vec[8];
+  struct s_tag* s_next;
+@} g_an_s;
+
+typedef struct s_tag s_typedef;
+@end example
+
+The structure tag has an @code{N_LSYM} stab type because, like the
+enumeration, the symbol has file scope.  Like the enumeration, the
+symbol descriptor is @samp{T}, for enumeration, structure, or tag type.
+The type descriptor @samp{s} following the @samp{16=} of the type
+definition narrows the symbol type to structure.
+
+Following the @samp{s} type descriptor is the number of bytes the
+structure occupies, followed by a description of each structure element.
+The structure element descriptions are of the form @var{name:type, bit
+offset from the start of the struct, number of bits in the element}.
+
+@c FIXME: phony line break.  Can probably be fixed by using an example
+@c with fewer fields.
+@example
+# @r{128 is N_LSYM}
+.stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;
+        s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
+@end example
+
+In this example, the first two structure elements are previously defined
+types.  For these, the type following the @samp{@var{name}:} part of the
+element description is a simple type reference.  The other two structure
+elements are new types.  In this case there is a type definition
+embedded after the @samp{@var{name}:}.  The type definition for the
+array element looks just like a type definition for a standalone array.
+The @code{s_next} field is a pointer to the same kind of structure that
+the field is an element of.  So the definition of structure type 16
+contains a type definition for an element which is a pointer to type 16.
+
+If a field is a static member (this is a C++ feature in which a single
+variable appears to be a field of every structure of a given type) it
+still starts out with the field name, a colon, and the type, but then
+instead of a comma, bit position, comma, and bit size, there is a colon
+followed by the name of the variable which each such field refers to.
+
+If the structure has methods (a C++ feature), they follow the non-method
+fields; see @ref{Cplusplus}.
+
+@node Typedefs
+@section Giving a Type a Name
+
+@findex N_LSYM, for types
+@findex C_DECL, for types
+To give a type a name, use the @samp{t} symbol descriptor.  The type
+is specified by the type information (@pxref{String Field}) for the stab.
+For example,
+
+@example
+.stabs "s_typedef:t16",128,0,0,0     # @r{128 is N_LSYM}
+@end example
+
+specifies that @code{s_typedef} refers to type number 16.  Such stabs
+have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF).  (The Sun
+documentation mentions using @code{N_GSYM} in some cases).
+
+If you are specifying the tag name for a structure, union, or
+enumeration, use the @samp{T} symbol descriptor instead.  I believe C is
+the only language with this feature.
+
+If the type is an opaque type (I believe this is a Modula-2 feature),
+AIX provides a type descriptor to specify it.  The type descriptor is
+@samp{o} and is followed by a name.  I don't know what the name
+means---is it always the same as the name of the type, or is this type
+descriptor used with a nameless stab (@pxref{String Field})?  There
+optionally follows a comma followed by type information which defines
+the type of this type.  If omitted, a semicolon is used in place of the
+comma and the type information, and the type is much like a generic
+pointer type---it has a known size but little else about it is
+specified.
+
+@node Unions
+@section Unions
+
+@example
+union u_tag @{
+  int  u_int;
+  float u_float;
+  char* u_char;
+@} an_u;
+@end example
+
+This code generates a stab for a union tag and a stab for a union
+variable.  Both use the @code{N_LSYM} stab type.  If a union variable is
+scoped locally to the procedure in which it is defined, its stab is
+located immediately preceding the @code{N_LBRAC} for the procedure's block
+start.
+
+The stab for the union tag, however, is located preceding the code for
+the procedure in which it is defined.  The stab type is @code{N_LSYM}.  This
+would seem to imply that the union type is file scope, like the struct
+type @code{s_tag}.  This is not true.  The contents and position of the stab
+for @code{u_type} do not convey any infomation about its procedure local
+scope.
+
+@c FIXME: phony line break.  Can probably be fixed by using an example
+@c with fewer fields.
+@smallexample
+# @r{128 is N_LSYM}
+.stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
+       128,0,0,0
+@end smallexample
+
+The symbol descriptor @samp{T}, following the @samp{name:} means that
+the stab describes an enumeration, structure, or union tag.  The type
+descriptor @samp{u}, following the @samp{23=} of the type definition,
+narrows it down to a union type definition.  Following the @samp{u} is
+the number of bytes in the union.  After that is a list of union element
+descriptions.  Their format is @var{name:type, bit offset into the
+union, number of bytes for the element;}.
+
+The stab for the union variable is:
+
+@example
+.stabs "an_u:23",128,0,0,-20     # @r{128 is N_LSYM}
+@end example
+
+@samp{-20} specifies where the variable is stored (@pxref{Stack
+Variables}).
+
+@node Function Types
+@section Function Types
+
+Various types can be defined for function variables.  These types are
+not used in defining functions (@pxref{Procedures}); they are used for
+things like pointers to functions.
+
+The simple, traditional, type is type descriptor @samp{f} is followed by
+type information for the return type of the function, followed by a
+semicolon.
+
+This does not deal with functions for which the number and types of the
+parameters are part of the type, as in Modula-2 or ANSI C.  AIX provides
+extensions to specify these, using the @samp{f}, @samp{F}, @samp{p}, and
+@samp{R} type descriptors.
+
+First comes the type descriptor.  If it is @samp{f} or @samp{F}, this
+type involves a function rather than a procedure, and the type
+information for the return type of the function follows, followed by a
+comma.  Then comes the number of parameters to the function and a
+semicolon.  Then, for each parameter, there is the name of the parameter
+followed by a colon (this is only present for type descriptors @samp{R}
+and @samp{F} which represent Pascal function or procedure parameters),
+type information for the parameter, a comma, 0 if passed by reference or
+1 if passed by value, and a semicolon.  The type definition ends with a
+semicolon.
+
+For example, this variable definition:
+
+@example
+int (*g_pf)();
+@end example
+
+@noindent
+generates the following code:
+
+@example
+.stabs "g_pf:G24=*25=f1",32,0,0,0
+    .common _g_pf,4,"bss"
+@end example
+
+The variable defines a new type, 24, which is a pointer to another new
+type, 25, which is a function returning @code{int}.
+
+@node Symbol Tables
+@chapter Symbol Information in Symbol Tables
+
+This chapter describes the format of symbol table entries
+and how stab assembler directives map to them.  It also describes the
+transformations that the assembler and linker make on data from stabs.
+
+@menu
+* Symbol Table Format::
+* Transformations On Symbol Tables::
+@end menu
+
+@node Symbol Table Format
+@section Symbol Table Format
+
+Each time the assembler encounters a stab directive, it puts
+each field of the stab into a corresponding field in a symbol table
+entry of its output file.  If the stab contains a string field, the
+symbol table entry for that stab points to a string table entry
+containing the string data from the stab.  Assembler labels become
+relocatable addresses.  Symbol table entries in a.out have the format:
+
+@c FIXME: should refer to external, not internal.
+@example
+struct internal_nlist @{
+  unsigned long n_strx;         /* index into string table of name */
+  unsigned char n_type;         /* type of symbol */
+  unsigned char n_other;        /* misc info (usually empty) */
+  unsigned short n_desc;        /* description field */
+  bfd_vma n_value;              /* value of symbol */
+@};
+@end example
+
+If the stab has a string, the @code{n_strx} field holds the offset in
+bytes of the string within the string table.  The string is terminated
+by a NUL character.  If the stab lacks a string (for example, it was
+produced by a @code{.stabn} or @code{.stabd} directive), the
+@code{n_strx} field is zero.
+
+Symbol table entries with @code{n_type} field values greater than 0x1f
+originated as stabs generated by the compiler (with one random
+exception).  The other entries were placed in the symbol table of the
+executable by the assembler or the linker.
+
+@node Transformations On Symbol Tables
+@section Transformations on Symbol Tables
+
+The linker concatenates object files and does fixups of externally
+defined symbols.
+
+You can see the transformations made on stab data by the assembler and
+linker by examining the symbol table after each pass of the build.  To
+do this, use @samp{nm -ap}, which dumps the symbol table, including
+debugging information, unsorted.  For stab entries the columns are:
+@var{value}, @var{other}, @var{desc}, @var{type}, @var{string}.  For
+assembler and linker symbols, the columns are: @var{value}, @var{type},
+@var{string}.
+
+The low 5 bits of the stab type tell the linker how to relocate the
+value of the stab.  Thus for stab types like @code{N_RSYM} and
+@code{N_LSYM}, where the value is an offset or a register number, the
+low 5 bits are @code{N_ABS}, which tells the linker not to relocate the
+value.
+
+Where the value of a stab contains an assembly language label,
+it is transformed by each build step.  The assembler turns it into a
+relocatable address and the linker turns it into an absolute address.
+
+@menu
+* Transformations On Static Variables::
+* Transformations On Global Variables::
+* Stab Section Transformations::	   For some object file formats,
+                                           things are a bit different.
+@end menu
+
+@node Transformations On Static Variables
+@subsection Transformations on Static Variables
+
+This source line defines a static variable at file scope:
+
+@example
+static int s_g_repeat
+@end example
+
+@noindent
+The following stab describes the symbol:
+
+@example
+.stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
+@end example
+
+@noindent
+The assembler transforms the stab into this symbol table entry in the
+@file{.o} file.  The location is expressed as a data segment offset.
+
+@example
+00000084 - 00 0000 STSYM s_g_repeat:S1
+@end example
+
+@noindent
+In the symbol table entry from the executable, the linker has made the
+relocatable address absolute.
+
+@example
+0000e00c - 00 0000 STSYM s_g_repeat:S1
+@end example
+
+@node Transformations On Global Variables
+@subsection Transformations on Global Variables
+
+Stabs for global variables do not contain location information. In
+this case, the debugger finds location information in the assembler or
+linker symbol table entry describing the variable.  The source line:
+
+@example
+char g_foo = 'c';
+@end example
+
+@noindent
+generates the stab:
+
+@example
+.stabs "g_foo:G2",32,0,0,0
+@end example
+
+The variable is represented by two symbol table entries in the object
+file (see below).  The first one originated as a stab.  The second one
+is an external symbol.  The upper case @samp{D} signifies that the
+@code{n_type} field of the symbol table contains 7, @code{N_DATA} with
+local linkage.  The stab's value is zero since the value is not used for
+@code{N_GSYM} stabs.  The value of the linker symbol is the relocatable
+address corresponding to the variable.
+
+@example
+00000000 - 00 0000  GSYM g_foo:G2
+00000080 D _g_foo
+@end example
+
+@noindent
+These entries as transformed by the linker.  The linker symbol table
+entry now holds an absolute address:
+
+@example
+00000000 - 00 0000  GSYM g_foo:G2
+@dots{}
+0000e008 D _g_foo
+@end example
+
+@node Stab Section Transformations
+@subsection Transformations of Stabs in separate sections
+
+For object file formats using stabs in separate sections (@pxref{Stab
+Sections}), use @code{objdump --stabs} instead of @code{nm} to show the
+stabs in an object or executable file.  @code{objdump} is a GNU utility;
+Sun does not provide any equivalent.
+
+The following example is for a stab whose value is an address is
+relative to the compilation unit (@pxref{ELF Linker Relocation}).  For
+example, if the source line
+
+@example
+static int ld = 5;
+@end example
+
+appears within a function, then the assembly language output from the
+compiler contains:
+
+@example
+.Ddata.data:
+@dots{}
+        .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data    # @r{0x26 is N_STSYM}
+@dots{}
+.L18:
+        .align 4
+        .word 0x5
+@end example
+
+Because the value is formed by subtracting one symbol from another, the
+value is absolute, not relocatable, and so the object file contains
+
+@example
+Symnum n_type n_othr n_desc n_value  n_strx String
+31     STSYM  0      4      00000004 680    ld:V(0,3)
+@end example
+
+without any relocations, and the executable file also contains
+
+@example
+Symnum n_type n_othr n_desc n_value  n_strx String
+31     STSYM  0      4      00000004 680    ld:V(0,3)
+@end example
+
+@node Cplusplus
+@chapter GNU C++ Stabs
+
+@menu
+* Class Names::			C++ class names are both tags and typedefs.
+* Nested Symbols::		C++ symbol names can be within other types.
+* Basic Cplusplus Types::
+* Simple Classes::
+* Class Instance::
+* Methods::			Method definition
+* Method Type Descriptor::      The @samp{#} type descriptor
+* Member Type Descriptor::      The @samp{@@} type descriptor
+* Protections::
+* Method Modifiers::
+* Virtual Methods::
+* Inheritence::
+* Virtual Base Classes::
+* Static Members::
+@end menu
+
+@node Class Names
+@section C++ Class Names
+
+In C++, a class name which is declared with @code{class}, @code{struct},
+or @code{union}, is not only a tag, as in C, but also a type name.  Thus
+there should be stabs with both @samp{t} and @samp{T} symbol descriptors
+(@pxref{Typedefs}).
+
+To save space, there is a special abbreviation for this case.  If the
+@samp{T} symbol descriptor is followed by @samp{t}, then the stab
+defines both a type name and a tag.
+
+For example, the C++ code
+
+@example
+struct foo @{int x;@};
+@end example
+
+can be represented as either
+
+@example
+.stabs "foo:T19=s4x:1,0,32;;",128,0,0,0       # @r{128 is N_LSYM}
+.stabs "foo:t19",128,0,0,0
+@end example
+
+or
+
+@example
+.stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0
+@end example
+
+@node Nested Symbols
+@section Defining a Symbol Within Another Type
+
+In C++, a symbol (such as a type name) can be defined within another type.
+@c FIXME: Needs example.
+
+In stabs, this is sometimes represented by making the name of a symbol
+which contains @samp{::}.  Such a pair of colons does not end the name
+of the symbol, the way a single colon would (@pxref{String Field}).  I'm
+not sure how consistently used or well thought out this mechanism is.
+So that a pair of colons in this position always has this meaning,
+@samp{:} cannot be used as a symbol descriptor.
+
+For example, if the string for a stab is @samp{foo::bar::baz:t5=*6},
+then @code{foo::bar::baz} is the name of the symbol, @samp{t} is the
+symbol descriptor, and @samp{5=*6} is the type information.
+
+@node Basic Cplusplus Types
+@section Basic Types For C++
+
+<< the examples that follow are based on a01.C >>
+
+
+C++ adds two more builtin types to the set defined for C.  These are
+the unknown type and the vtable record type.  The unknown type, type
+16, is defined in terms of itself like the void type.
+
+The vtable record type, type 17, is defined as a structure type and
+then as a structure tag.  The structure has four fields: delta, index,
+pfn, and delta2.  pfn is the function pointer.
+
+<< In boilerplate $vtbl_ptr_type, what are the fields delta,
+index, and delta2 used for? >>
+
+This basic type is present in all C++ programs even if there are no
+virtual methods defined.
+
+@display
+.stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8)
+        elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16);
+        elem_name(index):type_ref(short int),bit_offset(16),field_bits(16);
+        elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void),
+                                    bit_offset(32),field_bits(32);
+        elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;"
+        N_LSYM, NIL, NIL
+@end display
+
+@smallexample
+.stabs "$vtbl_ptr_type:t17=s8
+        delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;"
+        ,128,0,0,0
+@end smallexample
+
+@display
+.stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL
+@end display
+
+@example
+.stabs "$vtbl_ptr_type:T17",128,0,0,0
+@end example
+
+@node Simple Classes
+@section Simple Class Definition
+
+The stabs describing C++ language features are an extension of the
+stabs describing C.  Stabs representing C++ class types elaborate
+extensively on the stab format used to describe structure types in C.
+Stabs representing class type variables look just like stabs
+representing C language variables.
+
+Consider the following very simple class definition.
+
+@example
+class baseA @{
+public:
+        int Adat;
+        int Ameth(int in, char other);
+@};
+@end example
+
+The class @code{baseA} is represented by two stabs.  The first stab describes
+the class as a structure type.  The second stab describes a structure
+tag of the class type.  Both stabs are of stab type @code{N_LSYM}.  Since the
+stab is not located between an @code{N_FUN} and an @code{N_LBRAC} stab this indicates
+that the class is defined at file scope.  If it were, then the @code{N_LSYM}
+would signify a local variable.
+
+A stab describing a C++ class type is similar in format to a stab
+describing a C struct, with each class member shown as a field in the
+structure.  The part of the struct format describing fields is
+expanded to include extra information relevent to C++ class members.
+In addition, if the class has multiple base classes or virtual
+functions the struct format outside of the field parts is also
+augmented.
+
+In this simple example the field part of the C++ class stab
+representing member data looks just like the field part of a C struct
+stab.  The section on protections describes how its format is
+sometimes extended for member data.
+
+The field part of a C++ class stab representing a member function
+differs substantially from the field part of a C struct stab.  It
+still begins with @samp{name:} but then goes on to define a new type number
+for the member function, describe its return type, its argument types,
+its protection level, any qualifiers applied to the method definition,
+and whether the method is virtual or not.  If the method is virtual
+then the method description goes on to give the vtable index of the
+method, and the type number of the first base class defining the
+method.
+
+When the field name is a method name it is followed by two colons rather
+than one.  This is followed by a new type definition for the method.
+This is a number followed by an equal sign and the type of the method.
+Normally this will be a type declared using the @samp{#} type
+descriptor; see @ref{Method Type Descriptor}; static member functions
+are declared using the @samp{f} type descriptor instead; see
+@ref{Function Types}.
+
+The format of an overloaded operator method name differs from that of
+other methods.  It is @samp{op$::@var{operator-name}.} where
+@var{operator-name} is the operator name such as @samp{+} or @samp{+=}.
+The name ends with a period, and any characters except the period can
+occur in the @var{operator-name} string.
+
+The next part of the method description represents the arguments to the
+method, preceeded by a colon and ending with a semi-colon.  The types of
+the arguments are expressed in the same way argument types are expressed
+in C++ name mangling.  In this example an @code{int} and a @code{char}
+map to @samp{ic}.
+
+This is followed by a number, a letter, and an asterisk or period,
+followed by another semicolon.  The number indicates the protections
+that apply to the member function.  Here the 2 means public.  The
+letter encodes any qualifier applied to the method definition.  In
+this case, @samp{A} means that it is a normal function definition.  The dot
+shows that the method is not virtual.  The sections that follow
+elaborate further on these fields and describe the additional
+information present for virtual methods.
+
+
+@display
+.stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4)
+        field_name(Adat):type(int),bit_offset(0),field_bits(32);
+
+        method_name(Ameth)::type_def(21)=type_desc(method)return_type(int);
+        :arg_types(int char);
+        protection(public)qualifier(normal)virtual(no);;"
+        N_LSYM,NIL,NIL,NIL
+@end display
+
+@smallexample
+.stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0
+
+.stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL
+
+.stabs "baseA:T20",128,0,0,0
+@end smallexample
+
+@node Class Instance
+@section Class Instance
+
+As shown above, describing even a simple C++ class definition is
+accomplished by massively extending the stab format used in C to
+describe structure types.  However, once the class is defined, C stabs
+with no modifications can be used to describe class instances.  The
+following source:
+
+@example
+main () @{
+        baseA AbaseA;
+@}
+@end example
+
+@noindent
+yields the following stab describing the class instance.  It looks no
+different from a standard C stab describing a local variable.
+
+@display
+.stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
+@end display
+
+@example
+.stabs "AbaseA:20",128,0,0,-20
+@end example
+
+@node Methods
+@section Method Definition
+
+The class definition shown above declares Ameth.  The C++ source below
+defines Ameth:
+
+@example
+int
+baseA::Ameth(int in, char other)
+@{
+        return in;
+@};
+@end example
+
+
+This method definition yields three stabs following the code of the
+method.  One stab describes the method itself and following two describe
+its parameters.  Although there is only one formal argument all methods
+have an implicit argument which is the @code{this} pointer.  The @code{this}
+pointer is a pointer to the object on which the method was called.  Note
+that the method name is mangled to encode the class name and argument
+types.  Name mangling is described in the @sc{arm} (@cite{The Annotated
+C++ Reference Manual}, by Ellis and Stroustrup, @sc{isbn}
+0-201-51459-1); @file{gpcompare.texi} in Cygnus GCC distributions
+describes the differences between GNU mangling and @sc{arm}
+mangling.
+@c FIXME: Use @xref, especially if this is generally installed in the
+@c info tree.
+@c FIXME: This information should be in a net release, either of GCC or
+@c GDB.  But gpcompare.texi doesn't seem to be in the FSF GCC.
+
+@example
+.stabs "name:symbol_desriptor(global function)return_type(int)",
+        N_FUN, NIL, NIL, code_addr_of_method_start
+
+.stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic
+@end example
+
+Here is the stab for the @code{this} pointer implicit argument.  The
+name of the @code{this} pointer is always @code{this}.  Type 19, the
+@code{this} pointer is defined as a pointer to type 20, @code{baseA},
+but a stab defining @code{baseA} has not yet been emited.  Since the
+compiler knows it will be emited shortly, here it just outputs a cross
+reference to the undefined symbol, by prefixing the symbol name with
+@samp{xs}.
+
+@example
+.stabs "name:sym_desc(register param)type_def(19)=
+        type_desc(ptr to)type_ref(baseA)=
+        type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number
+
+.stabs "this:P19=*20=xsbaseA:",64,0,0,8
+@end example
+
+The stab for the explicit integer argument looks just like a parameter
+to a C function.  The last field of the stab is the offset from the
+argument pointer, which in most systems is the same as the frame
+pointer.
+
+@example
+.stabs "name:sym_desc(value parameter)type_ref(int)",
+        N_PSYM,NIL,NIL,offset_from_arg_ptr
+
+.stabs "in:p1",160,0,0,72
+@end example
+
+<< The examples that follow are based on A1.C >>
+
+@node Method Type Descriptor
+@section The @samp{#} Type Descriptor
+
+This is used to describe a class method.  This is a function which takes
+an extra argument as its first argument, for the @code{this} pointer.
+
+If the @samp{#} is immediately followed by another @samp{#}, the second
+one will be followed by the return type and a semicolon.  The class and
+argument types are not specified, and must be determined by demangling
+the name of the method if it is available.
+
+Otherwise, the single @samp{#} is followed by the class type, a comma,
+the return type, a comma, and zero or more parameter types separated by
+commas.  The list of arguments is terminated by a semicolon.  In the
+debugging output generated by gcc, a final argument type of @code{void}
+indicates a method which does not take a variable number of arguments.
+If the final argument type of @code{void} does not appear, the method
+was declared with an ellipsis.
+
+Note that although such a type will normally be used to describe fields
+in structures, unions, or classes, for at least some versions of the
+compiler it can also be used in other contexts.
+
+@node Member Type Descriptor
+@section The @samp{@@} Type Descriptor
+
+The @samp{@@} type descriptor is for a member (class and variable) type.
+It is followed by type information for the offset basetype, a comma, and
+type information for the type of the field being pointed to.  (FIXME:
+this is acknowledged to be gibberish.  Can anyone say what really goes
+here?).
+
+Note that there is a conflict between this and type attributes
+(@pxref{String Field}); both use type descriptor @samp{@@}.
+Fortunately, the @samp{@@} type descriptor used in this C++ sense always
+will be followed by a digit, @samp{(}, or @samp{-}, and type attributes
+never start with those things.
+
+@node Protections
+@section Protections
+
+In the simple class definition shown above all member data and
+functions were publicly accessable.  The example that follows
+contrasts public, protected and privately accessable fields and shows
+how these protections are encoded in C++ stabs.
+
+If the character following the @samp{@var{field-name}:} part of the
+string is @samp{/}, then the next character is the visibility.  @samp{0}
+means private, @samp{1} means protected, and @samp{2} means public.
+Debuggers should ignore visibility characters they do not recognize, and
+assume a reasonable default (such as public) (GDB 4.11 does not, but
+this should be fixed in the next GDB release).  If no visibility is
+specified the field is public.  The visibility @samp{9} means that the
+field has been optimized out and is public (there is no way to specify
+an optimized out field with a private or protected visibility).
+Visibility @samp{9} is not supported by GDB 4.11; this should be fixed
+in the next GDB release.
+
+The following C++ source:
+
+@example
+class vis @{
+private:
+        int   priv;
+protected:
+        char  prot;
+public:
+        float pub;
+@};
+@end example
+
+@noindent
+generates the following stab:
+
+@example
+# @r{128 is N_LSYM}
+.stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0
+@end example
+
+@samp{vis:T19=s12} indicates that type number 19 is a 12 byte structure
+named @code{vis} The @code{priv} field has public visibility
+(@samp{/0}), type int (@samp{1}), and offset and size @samp{,0,32;}.
+The @code{prot} field has protected visibility (@samp{/1}), type char
+(@samp{2}) and offset and size @samp{,32,8;}.  The @code{pub} field has
+type float (@samp{12}), and offset and size @samp{,64,32;}.
+
+Protections for member functions are signified by one digit embeded in
+the field part of the stab describing the method.  The digit is 0 if
+private, 1 if protected and 2 if public.  Consider the C++ class
+definition below:
+
+@example
+class all_methods @{
+private:
+        int   priv_meth(int in)@{return in;@};
+protected:
+        char  protMeth(char in)@{return in;@};
+public:
+        float pubMeth(float in)@{return in;@};
+@};
+@end example
+
+It generates the following stab.  The digit in question is to the left
+of an @samp{A} in each case.  Notice also that in this case two symbol
+descriptors apply to the class name struct tag and struct type.
+
+@display
+.stabs "class_name:sym_desc(struct tag&type)type_def(21)=
+        sym_desc(struct)struct_bytes(1)
+        meth_name::type_def(22)=sym_desc(method)returning(int);
+        :args(int);protection(private)modifier(normal)virtual(no);
+        meth_name::type_def(23)=sym_desc(method)returning(char);
+        :args(char);protection(protected)modifier(normal)virual(no);
+        meth_name::type_def(24)=sym_desc(method)returning(float);
+        :args(float);protection(public)modifier(normal)virtual(no);;",
+        N_LSYM,NIL,NIL,NIL
+@end display
+
+@smallexample
+.stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.;
+        pubMeth::24=##12;:f;2A.;;",128,0,0,0
+@end smallexample
+
+@node Method Modifiers
+@section Method Modifiers (@code{const}, @code{volatile}, @code{const volatile})
+
+<< based on a6.C >>
+
+In the class example described above all the methods have the normal
+modifier.  This method modifier information is located just after the
+protection information for the method.  This field has four possible
+character values.  Normal methods use @samp{A}, const methods use
+@samp{B}, volatile methods use @samp{C}, and const volatile methods use
+@samp{D}.  Consider the class definition below:
+
+@example
+class A @{
+public:
+        int ConstMeth (int arg) const @{ return arg; @};
+        char VolatileMeth (char arg) volatile @{ return arg; @};
+        float ConstVolMeth (float arg) const volatile @{return arg; @};
+@};
+@end example
+
+This class is described by the following stab:
+
+@display
+.stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1)
+        meth_name(ConstMeth)::type_def(21)sym_desc(method)
+        returning(int);:arg(int);protection(public)modifier(const)virtual(no);
+        meth_name(VolatileMeth)::type_def(22)=sym_desc(method)
+        returning(char);:arg(char);protection(public)modifier(volatile)virt(no)
+        meth_name(ConstVolMeth)::type_def(23)=sym_desc(method)
+        returning(float);:arg(float);protection(public)modifer(const volatile)
+        virtual(no);;", @dots{}
+@end display
+
+@example
+.stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.;
+             ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0
+@end example
+
+@node Virtual Methods
+@section Virtual Methods
+
+<< The following examples are based on a4.C >>
+
+The presence of virtual methods in a class definition adds additional
+data to the class description.  The extra data is appended to the
+description of the virtual method and to the end of the class
+description.  Consider the class definition below:
+
+@example
+class A @{
+public:
+        int Adat;
+        virtual int A_virt (int arg) @{ return arg; @};
+@};
+@end example
+
+This results in the stab below describing class A.  It defines a new
+type (20) which is an 8 byte structure.  The first field of the class
+struct is @samp{Adat}, an integer, starting at structure offset 0 and
+occupying 32 bits.
+
+The second field in the class struct is not explicitly defined by the
+C++ class definition but is implied by the fact that the class
+contains a virtual method.  This field is the vtable pointer.  The
+name of the vtable pointer field starts with @samp{$vf} and continues with a
+type reference to the class it is part of.  In this example the type
+reference for class A is 20 so the name of its vtable pointer field is
+@samp{$vf20}, followed by the usual colon.
+
+Next there is a type definition for the vtable pointer type (21).
+This is in turn defined as a pointer to another new type (22).
+
+Type 22 is the vtable itself, which is defined as an array, indexed by
+a range of integers between 0 and 1, and whose elements are of type
+17.  Type 17 was the vtable record type defined by the boilerplate C++
+type definitions, as shown earlier.
+
+The bit offset of the vtable pointer field is 32.  The number of bits
+in the field are not specified when the field is a vtable pointer.
+
+Next is the method definition for the virtual member function @code{A_virt}.
+Its description starts out using the same format as the non-virtual
+member functions described above, except instead of a dot after the
+@samp{A} there is an asterisk, indicating that the function is virtual.
+Since is is virtual some addition information is appended to the end
+of the method description.
+
+The first number represents the vtable index of the method.  This is a
+32 bit unsigned number with the high bit set, followed by a
+semi-colon.
+
+The second number is a type reference to the first base class in the
+inheritence hierarchy defining the virtual member function.  In this
+case the class stab describes a base class so the virtual function is
+not overriding any other definition of the method.  Therefore the
+reference is to the type number of the class that the stab is
+describing (20).
+
+This is followed by three semi-colons.  One marks the end of the
+current sub-section, one marks the end of the method field, and the
+third marks the end of the struct definition.
+
+For classes containing virtual functions the very last section of the
+string part of the stab holds a type reference to the first base
+class.  This is preceeded by @samp{~%} and followed by a final semi-colon.
+
+@display
+.stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
+        field_name(Adat):type_ref(int),bit_offset(0),field_bits(32);
+        field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)=
+        sym_desc(array)index_type_ref(range of int from 0 to 1);
+        elem_type_ref(vtbl elem type),
+        bit_offset(32);
+        meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int);
+        :arg_type(int),protection(public)normal(yes)virtual(yes)
+        vtable_index(1);class_first_defining(A);;;~%first_base(A);",
+        N_LSYM,NIL,NIL,NIL
+@end display
+
+@c FIXME: bogus line break.
+@example
+.stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
+        A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
+@end example
+
+@node Inheritence
+@section Inheritence
+
+Stabs describing C++ derived classes include additional sections that
+describe the inheritence hierarchy of the class.  A derived class stab
+also encodes the number of base classes.  For each base class it tells
+if the base class is virtual or not, and if the inheritence is private
+or public.  It also gives the offset into the object of the portion of
+the object corresponding to each base class.
+
+This additional information is embeded in the class stab following the
+number of bytes in the struct.  First the number of base classes
+appears bracketed by an exclamation point and a comma.
+
+Then for each base type there repeats a series: a virtual character, a
+visibilty character, a number, a comma, another number, and a
+semi-colon.
+
+The virtual character is @samp{1} if the base class is virtual and
+@samp{0} if not.  The visibility character is @samp{2} if the derivation
+is public, @samp{1} if it is protected, and @samp{0} if it is private.
+Debuggers should ignore virtual or visibility characters they do not
+recognize, and assume a reasonable default (such as public and
+non-virtual) (GDB 4.11 does not, but this should be fixed in the next
+GDB release).
+
+The number following the virtual and visibility characters is the offset
+from the start of the object to the part of the object pertaining to the
+base class.
+
+After the comma, the second number is a type_descriptor for the base
+type.  Finally a semi-colon ends the series, which repeats for each
+base class.
+
+The source below defines three base classes @code{A}, @code{B}, and
+@code{C} and the derived class @code{D}.
+
+
+@example
+class A @{
+public:
+        int Adat;
+        virtual int A_virt (int arg) @{ return arg; @};
+@};
+
+class B @{
+public:
+        int B_dat;
+        virtual int B_virt (int arg) @{return arg; @};
+@};
+
+class C @{
+public:
+        int Cdat;
+        virtual int C_virt (int arg) @{return arg; @};
+@};
+
+class D : A, virtual B, public C @{
+public:
+        int Ddat;
+        virtual int A_virt (int arg ) @{ return arg+1; @};
+        virtual int B_virt (int arg)  @{ return arg+2; @};
+        virtual int C_virt (int arg)  @{ return arg+3; @};
+        virtual int D_virt (int arg)  @{ return arg; @};
+@};
+@end example
+
+Class stabs similar to the ones described earlier are generated for
+each base class.
+
+@c FIXME!!! the linebreaks in the following example probably make the
+@c examples literally unusable, but I don't know any other way to get
+@c them on the page.
+@c One solution would be to put some of the type definitions into
+@c separate stabs, even if that's not exactly what the compiler actually
+@c emits.
+@smallexample
+.stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
+        A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
+
+.stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1;
+        :i;2A*-2147483647;25;;;~%25;",128,0,0,0
+
+.stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1;
+        :i;2A*-2147483647;28;;;~%28;",128,0,0,0
+@end smallexample
+
+In the stab describing derived class @code{D} below, the information about
+the derivation of this class is encoded as follows.
+
+@display
+.stabs "derived_class_name:symbol_descriptors(struct tag&type)=
+        type_descriptor(struct)struct_bytes(32)!num_bases(3),
+        base_virtual(no)inheritence_public(no)base_offset(0),
+        base_class_type_ref(A);
+        base_virtual(yes)inheritence_public(no)base_offset(NIL),
+        base_class_type_ref(B);
+        base_virtual(no)inheritence_public(yes)base_offset(64),
+        base_class_type_ref(C); @dots{}
+@end display
+
+@c FIXME! fake linebreaks.
+@smallexample
+.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:
+        1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt:
+        :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;
+        28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
+@end smallexample
+
+@node Virtual Base Classes
+@section Virtual Base Classes
+
+A derived class object consists of a concatination in memory of the data
+areas defined by each base class, starting with the leftmost and ending
+with the rightmost in the list of base classes.  The exception to this
+rule is for virtual inheritence.  In the example above, class @code{D}
+inherits virtually from base class @code{B}.  This means that an
+instance of a @code{D} object will not contain its own @code{B} part but
+merely a pointer to a @code{B} part, known as a virtual base pointer.
+
+In a derived class stab, the base offset part of the derivation
+information, described above, shows how the base class parts are
+ordered.  The base offset for a virtual base class is always given as 0.
+Notice that the base offset for @code{B} is given as 0 even though
+@code{B} is not the first base class.  The first base class @code{A}
+starts at offset 0.
+
+The field information part of the stab for class @code{D} describes the field
+which is the pointer to the virtual base class @code{B}. The vbase pointer
+name is @samp{$vb} followed by a type reference to the virtual base class.
+Since the type id for @code{B} in this example is 25, the vbase pointer name
+is @samp{$vb25}.
+
+@c FIXME!! fake linebreaks below
+@smallexample
+.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1,
+       160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i;
+       2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt:
+       :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
+@end smallexample
+
+Following the name and a semicolon is a type reference describing the
+type of the virtual base class pointer, in this case 24.  Type 24 was
+defined earlier as the type of the @code{B} class @code{this} pointer.  The
+@code{this} pointer for a class is a pointer to the class type.
+
+@example
+.stabs "this:P24=*25=xsB:",64,0,0,8
+@end example
+
+Finally the field offset part of the vbase pointer field description
+shows that the vbase pointer is the first field in the @code{D} object,
+before any data fields defined by the class.  The layout of a @code{D}
+class object is a follows, @code{Adat} at 0, the vtable pointer for
+@code{A} at 32, @code{Cdat} at 64, the vtable pointer for C at 96, the
+virtual base pointer for @code{B} at 128, and @code{Ddat} at 160.
+
+
+@node Static Members
+@section Static Members
+
+The data area for a class is a concatenation of the space used by the
+data members of the class.  If the class has virtual methods, a vtable
+pointer follows the class data.  The field offset part of each field
+description in the class stab shows this ordering.
+
+<< How is this reflected in stabs?  See Cygnus bug #677 for some info.  >>
+
+@node Stab Types
+@appendix Table of Stab Types
+
+The following are all the possible values for the stab type field, for
+a.out files, in numeric order.  This does not apply to XCOFF, but
+it does apply to stabs in sections (@pxref{Stab Sections}).  Stabs in
+ECOFF use these values but add 0x8f300 to distinguish them from non-stab
+symbols.
+
+The symbolic names are defined in the file @file{include/aout/stabs.def}.
+
+@menu
+* Non-Stab Symbol Types::	Types from 0 to 0x1f
+* Stab Symbol Types::		Types from 0x20 to 0xff
+@end menu
+
+@node Non-Stab Symbol Types
+@appendixsec Non-Stab Symbol Types
+
+The following types are used by the linker and assembler, not by stab
+directives.  Since this document does not attempt to describe aspects of
+object file format other than the debugging format, no details are
+given.
+
+@c Try to get most of these to fit on a single line.
+@iftex
+@tableindent=1.5in
+@end iftex
+
+@table @code
+@item 0x0     N_UNDF
+Undefined symbol
+
+@item 0x2     N_ABS
+File scope absolute symbol
+
+@item 0x3     N_ABS | N_EXT
+External absolute symbol
+
+@item 0x4     N_TEXT
+File scope text symbol
+
+@item 0x5     N_TEXT | N_EXT
+External text symbol
+
+@item 0x6     N_DATA
+File scope data symbol
+
+@item 0x7     N_DATA | N_EXT
+External data symbol
+
+@item 0x8     N_BSS
+File scope BSS symbol
+
+@item 0x9     N_BSS | N_EXT
+External BSS symbol
+
+@item 0x0c    N_FN_SEQ
+Same as @code{N_FN}, for Sequent compilers
+
+@item 0x0a    N_INDR
+Symbol is indirected to another symbol
+
+@item 0x12    N_COMM
+Common---visible after shared library dynamic link
+
+@item 0x14 N_SETA
+@itemx 0x15 N_SETA | N_EXT
+Absolute set element
+
+@item 0x16 N_SETT
+@itemx 0x17 N_SETT | N_EXT
+Text segment set element
+
+@item 0x18 N_SETD
+@itemx 0x19 N_SETD | N_EXT
+Data segment set element
+
+@item 0x1a N_SETB
+@itemx 0x1b N_SETB | N_EXT
+BSS segment set element
+
+@item 0x1c N_SETV
+@itemx 0x1d N_SETV | N_EXT
+Pointer to set vector
+
+@item 0x1e N_WARNING
+Print a warning message during linking
+
+@item 0x1f    N_FN
+File name of a @file{.o} file
+@end table
+
+@node Stab Symbol Types
+@appendixsec Stab Symbol Types
+
+The following symbol types indicate that this is a stab.  This is the
+full list of stab numbers, including stab types that are used in
+languages other than C.
+
+@table @code
+@item 0x20     N_GSYM
+Global symbol; see @ref{Global Variables}.
+
+@item 0x22     N_FNAME
+Function name (for BSD Fortran); see @ref{Procedures}.
+
+@item 0x24     N_FUN
+Function name (@pxref{Procedures}) or text segment variable
+(@pxref{Statics}).
+
+@item 0x26 N_STSYM
+Data segment file-scope variable; see @ref{Statics}.
+
+@item 0x28 N_LCSYM
+BSS segment file-scope variable; see @ref{Statics}.
+
+@item 0x2a N_MAIN
+Name of main routine; see @ref{Main Program}.
+
+@item 0x2c N_ROSYM
+Variable in @code{.rodata} section; see @ref{Statics}.
+
+@item 0x30     N_PC
+Global symbol (for Pascal); see @ref{N_PC}.
+
+@item 0x32     N_NSYMS
+Number of symbols (according to Ultrix V4.0); see @ref{N_NSYMS}.
+
+@item 0x34     N_NOMAP
+No DST map; see @ref{N_NOMAP}.
+
+@c FIXME: describe this solaris feature in the body of the text (see
+@c comments in include/aout/stab.def).
+@item 0x38 N_OBJ
+Object file (Solaris2).
+
+@c See include/aout/stab.def for (a little) more info.
+@item 0x3c N_OPT
+Debugger options (Solaris2).
+
+@item 0x40     N_RSYM
+Register variable; see @ref{Register Variables}.
+
+@item 0x42     N_M2C
+Modula-2 compilation unit; see @ref{N_M2C}.
+
+@item 0x44     N_SLINE
+Line number in text segment; see @ref{Line Numbers}.
+
+@item 0x46     N_DSLINE
+Line number in data segment; see @ref{Line Numbers}.
+
+@item 0x48     N_BSLINE
+Line number in bss segment; see @ref{Line Numbers}.
+
+@item 0x48     N_BROWS
+Sun source code browser, path to @file{.cb} file; see @ref{N_BROWS}.
+
+@item 0x4a     N_DEFD
+GNU Modula2 definition module dependency; see @ref{N_DEFD}.
+
+@item 0x4c N_FLINE
+Function start/body/end line numbers (Solaris2).
+
+@item 0x50     N_EHDECL
+GNU C++ exception variable; see @ref{N_EHDECL}.
+
+@item 0x50     N_MOD2
+Modula2 info "for imc" (according to Ultrix V4.0); see @ref{N_MOD2}.
+
+@item 0x54     N_CATCH
+GNU C++ @code{catch} clause; see @ref{N_CATCH}.
+
+@item 0x60     N_SSYM
+Structure of union element; see @ref{N_SSYM}.
+
+@item 0x62 N_ENDM
+Last stab for module (Solaris2).
+
+@item 0x64     N_SO
+Path and name of source file; see @ref{Source Files}.
+
+@item 0x80 N_LSYM
+Stack variable (@pxref{Stack Variables}) or type (@pxref{Typedefs}).
+
+@item 0x82     N_BINCL
+Beginning of an include file (Sun only); see @ref{Include Files}.
+
+@item 0x84     N_SOL
+Name of include file; see @ref{Include Files}.
+
+@item 0xa0     N_PSYM
+Parameter variable; see @ref{Parameters}.
+
+@item 0xa2     N_EINCL
+End of an include file; see @ref{Include Files}.
+
+@item 0xa4     N_ENTRY
+Alternate entry point; see @ref{Alternate Entry Points}.
+
+@item 0xc0     N_LBRAC
+Beginning of a lexical block; see @ref{Block Structure}.
+
+@item 0xc2     N_EXCL
+Place holder for a deleted include file; see @ref{Include Files}.
+
+@item 0xc4     N_SCOPE
+Modula2 scope information (Sun linker); see @ref{N_SCOPE}.
+
+@item 0xe0     N_RBRAC
+End of a lexical block; see @ref{Block Structure}.
+
+@item 0xe2     N_BCOMM
+Begin named common block; see @ref{Common Blocks}.
+
+@item 0xe4     N_ECOMM
+End named common block; see @ref{Common Blocks}.
+
+@item 0xe8     N_ECOML
+Member of a common block; see @ref{Common Blocks}.
+
+@c FIXME: How does this really work?  Move it to main body of document.
+@item 0xea N_WITH
+Pascal @code{with} statement: type,,0,0,offset (Solaris2).
+
+@item 0xf0     N_NBTEXT
+Gould non-base registers; see @ref{Gould}.
+
+@item 0xf2     N_NBDATA
+Gould non-base registers; see @ref{Gould}.
+
+@item 0xf4     N_NBBSS
+Gould non-base registers; see @ref{Gould}.
+
+@item 0xf6     N_NBSTS
+Gould non-base registers; see @ref{Gould}.
+
+@item 0xf8     N_NBLCS
+Gould non-base registers; see @ref{Gould}.
+@end table
+
+@c Restore the default table indent
+@iftex
+@tableindent=.8in
+@end iftex
+
+@node Symbol Descriptors
+@appendix Table of Symbol Descriptors
+
+The symbol descriptor is the character which follows the colon in many
+stabs, and which tells what kind of stab it is.  @xref{String Field},
+for more information about their use.
+
+@c Please keep this alphabetical
+@table @code
+@c In TeX, this looks great, digit is in italics.  But makeinfo insists
+@c on putting it in `', not realizing that @var should override @code.
+@c I don't know of any way to make makeinfo do the right thing.  Seems
+@c like a makeinfo bug to me.
+@item @var{digit}
+@itemx (
+@itemx -
+Variable on the stack; see @ref{Stack Variables}.
+
+@item :
+C++ nested symbol; see @xref{Nested Symbols}
+
+@item a
+Parameter passed by reference in register; see @ref{Reference Parameters}.
+
+@item b
+Based variable; see @ref{Based Variables}.
+
+@item c
+Constant; see @ref{Constants}.
+
+@item C
+Conformant array bound (Pascal, maybe other languages); @ref{Conformant
+Arrays}.  Name of a caught exception (GNU C++).  These can be
+distinguished because the latter uses @code{N_CATCH} and the former uses
+another symbol type.
+
+@item d
+Floating point register variable; see @ref{Register Variables}.
+
+@item D
+Parameter in floating point register; see @ref{Register Parameters}.
+
+@item f
+File scope function; see @ref{Procedures}.
+
+@item F
+Global function; see @ref{Procedures}.
+
+@item G
+Global variable; see @ref{Global Variables}.
+
+@item i
+@xref{Register Parameters}.
+
+@item I
+Internal (nested) procedure; see @ref{Nested Procedures}.
+
+@item J
+Internal (nested) function; see @ref{Nested Procedures}.
+
+@item L
+Label name (documented by AIX, no further information known).
+
+@item m
+Module; see @ref{Procedures}.
+
+@item p
+Argument list parameter; see @ref{Parameters}.
+
+@item pP
+@xref{Parameters}.
+
+@item pF
+Fortran Function parameter; see @ref{Parameters}.
+
+@item P
+Unfortunately, three separate meanings have been independently invented
+for this symbol descriptor.  At least the GNU and Sun uses can be
+distinguished by the symbol type.  Global Procedure (AIX) (symbol type
+used unknown); see @ref{Procedures}.  Register parameter (GNU) (symbol
+type @code{N_PSYM}); see @ref{Parameters}.  Prototype of function
+referenced by this file (Sun @code{acc}) (symbol type @code{N_FUN}).
+
+@item Q
+Static Procedure; see @ref{Procedures}.
+
+@item R
+Register parameter; see @ref{Register Parameters}.
+
+@item r
+Register variable; see @ref{Register Variables}.
+
+@item S
+File scope variable; see @ref{Statics}.
+
+@item s
+Local variable (OS9000).
+
+@item t
+Type name; see @ref{Typedefs}.
+
+@item T
+Enumeration, structure, or union tag; see @ref{Typedefs}.
+
+@item v
+Parameter passed by reference; see @ref{Reference Parameters}.
+
+@item V
+Procedure scope static variable; see @ref{Statics}.
+
+@item x
+Conformant array; see @ref{Conformant Arrays}.
+
+@item X
+Function return variable; see @ref{Parameters}.
+@end table
+
+@node Type Descriptors
+@appendix Table of Type Descriptors
+
+The type descriptor is the character which follows the type number and
+an equals sign.  It specifies what kind of type is being defined.
+@xref{String Field}, for more information about their use.
+
+@table @code
+@item @var{digit}
+@itemx (
+Type reference; see @ref{String Field}.
+
+@item -
+Reference to builtin type; see @ref{Negative Type Numbers}.
+
+@item #
+Method (C++); see @ref{Method Type Descriptor}.
+
+@item *
+Pointer; see @ref{Miscellaneous Types}.
+
+@item &
+Reference (C++).
+
+@item @@
+Type Attributes (AIX); see @ref{String Field}.  Member (class and variable)
+type (GNU C++); see @ref{Member Type Descriptor}.
+
+@item a
+Array; see @ref{Arrays}.
+
+@item A
+Open array; see @ref{Arrays}.
+
+@item b
+Pascal space type (AIX); see @ref{Miscellaneous Types}.  Builtin integer
+type (Sun); see @ref{Builtin Type Descriptors}.  Const and volatile
+qualfied type (OS9000).
+
+@item B
+Volatile-qualified type; see @ref{Miscellaneous Types}.
+
+@item c
+Complex builtin type (AIX); see @ref{Builtin Type Descriptors}.
+Const-qualified type (OS9000).
+
+@item C
+COBOL Picture type.  See AIX documentation for details.
+
+@item d
+File type; see @ref{Miscellaneous Types}.
+
+@item D
+N-dimensional dynamic array; see @ref{Arrays}.
+
+@item e
+Enumeration type; see @ref{Enumerations}.
+
+@item E
+N-dimensional subarray; see @ref{Arrays}.
+
+@item f
+Function type; see @ref{Function Types}.
+
+@item F
+Pascal function parameter; see @ref{Function Types}
+
+@item g
+Builtin floating point type; see @ref{Builtin Type Descriptors}.
+
+@item G
+COBOL Group.  See AIX documentation for details.
+
+@item i
+Imported type (AIX); see @ref{Cross-References}.  Volatile-qualified
+type (OS9000).
+
+@item k
+Const-qualified type; see @ref{Miscellaneous Types}.
+
+@item K
+COBOL File Descriptor.  See AIX documentation for details.
+
+@item M
+Multiple instance type; see @ref{Miscellaneous Types}.
+
+@item n
+String type; see @ref{Strings}.
+
+@item N
+Stringptr; see @ref{Strings}.
+
+@item o
+Opaque type; see @ref{Typedefs}.
+
+@item p
+Procedure; see @ref{Function Types}.
+
+@item P
+Packed array; see @ref{Arrays}.
+
+@item r
+Range type; see @ref{Subranges}.
+
+@item R
+Builtin floating type; see @ref{Builtin Type Descriptors} (Sun).  Pascal
+subroutine parameter; see @ref{Function Types} (AIX).  Detecting this
+conflict is possible with careful parsing (hint: a Pascal subroutine
+parameter type will always contain a comma, and a builtin type
+descriptor never will).
+
+@item s
+Structure type; see @ref{Structures}.
+
+@item S
+Set type; see @ref{Miscellaneous Types}.
+
+@item u
+Union; see @ref{Unions}.
+
+@item v
+Variant record.  This is a Pascal and Modula-2 feature which is like a
+union within a struct in C.  See AIX documentation for details.
+
+@item w
+Wide character; see @ref{Builtin Type Descriptors}.
+
+@item x
+Cross-reference; see @ref{Cross-References}.
+
+@item Y
+Used by IBM's xlC C++ compiler (for structures, I think).
+
+@item z
+gstring; see @ref{Strings}.
+@end table
+
+@node Expanded Reference
+@appendix Expanded Reference by Stab Type
+
+@c FIXME: This appendix should go away; see N_PSYM or N_SO for an example.
+
+For a full list of stab types, and cross-references to where they are
+described, see @ref{Stab Types}.  This appendix just covers certain
+stabs which are not yet described in the main body of this document;
+eventually the information will all be in one place.
+
+Format of an entry:
+
+The first line is the symbol type (see @file{include/aout/stab.def}).
+
+The second line describes the language constructs the symbol type
+represents.
+
+The third line is the stab format with the significant stab fields
+named and the rest NIL.
+
+Subsequent lines expand upon the meaning and possible values for each
+significant stab field.
+
+Finally, any further information.
+
+@menu
+* N_PC::			Pascal global symbol
+* N_NSYMS::			Number of symbols
+* N_NOMAP::			No DST map
+* N_M2C::			Modula-2 compilation unit
+* N_BROWS::			Path to .cb file for Sun source code browser
+* N_DEFD::			GNU Modula2 definition module dependency
+* N_EHDECL::			GNU C++ exception variable
+* N_MOD2::			Modula2 information "for imc"
+* N_CATCH::			GNU C++ "catch" clause
+* N_SSYM::			Structure or union element
+* N_SCOPE::			Modula2 scope information (Sun only)
+* Gould::			non-base register symbols used on Gould systems
+* N_LENG::			Length of preceding entry
+@end menu
+
+@node N_PC
+@section N_PC
+
+@deffn @code{.stabs} N_PC
+@findex N_PC
+Global symbol (for Pascal).
+
+@example
+"name" -> "symbol_name"  <<?>>
+value  -> supposedly the line number (stab.def is skeptical)
+@end example
+
+@display
+@file{stabdump.c} says:
+
+global pascal symbol: name,,0,subtype,line
+<< subtype? >>
+@end display
+@end deffn
+
+@node N_NSYMS
+@section N_NSYMS
+
+@deffn @code{.stabn} N_NSYMS
+@findex N_NSYMS
+Number of symbols (according to Ultrix V4.0).
+
+@display
+        0, files,,funcs,lines (stab.def)
+@end display
+@end deffn
+
+@node N_NOMAP
+@section N_NOMAP
+
+@deffn @code{.stabs} N_NOMAP
+@findex N_NOMAP
+No DST map for symbol (according to Ultrix V4.0).  I think this means a
+variable has been optimized out.
+
+@display
+        name, ,0,type,ignored (stab.def)
+@end display
+@end deffn
+
+@node N_M2C
+@section N_M2C
+
+@deffn @code{.stabs} N_M2C
+@findex N_M2C
+Modula-2 compilation unit.
+
+@example
+"string" -> "unit_name,unit_time_stamp[,code_time_stamp]"
+desc   -> unit_number
+value  -> 0 (main unit)
+          1 (any other unit)
+@end example
+
+See @cite{Dbx and Dbxtool Interfaces}, 2nd edition, by Sun, 1988, for
+more information.
+
+@end deffn
+
+@node N_BROWS
+@section N_BROWS
+
+@deffn @code{.stabs} N_BROWS
+@findex N_BROWS
+Sun source code browser, path to @file{.cb} file
+
+<<?>>
+"path to associated @file{.cb} file"
+
+Note: N_BROWS has the same value as N_BSLINE.
+@end deffn
+
+@node N_DEFD
+@section N_DEFD
+
+@deffn @code{.stabn} N_DEFD
+@findex N_DEFD
+GNU Modula2 definition module dependency.
+
+GNU Modula-2 definition module dependency.  The value is the
+modification time of the definition file.  The other field is non-zero
+if it is imported with the GNU M2 keyword @code{%INITIALIZE}.  Perhaps
+@code{N_M2C} can be used if there are enough empty fields?
+@end deffn
+
+@node N_EHDECL
+@section N_EHDECL
+
+@deffn @code{.stabs} N_EHDECL
+@findex N_EHDECL
+GNU C++ exception variable <<?>>.
+
+"@var{string} is variable name"
+
+Note: conflicts with @code{N_MOD2}.
+@end deffn
+
+@node N_MOD2
+@section N_MOD2
+
+@deffn @code{.stab?} N_MOD2
+@findex N_MOD2
+Modula2 info "for imc" (according to Ultrix V4.0)
+
+Note: conflicts with @code{N_EHDECL}  <<?>>
+@end deffn
+
+@node N_CATCH
+@section N_CATCH
+
+@deffn @code{.stabn} N_CATCH
+@findex N_CATCH
+GNU C++ @code{catch} clause
+
+GNU C++ @code{catch} clause.  The value is its address.  The desc field
+is nonzero if this entry is immediately followed by a @code{CAUGHT} stab
+saying what exception was caught.  Multiple @code{CAUGHT} stabs means
+that multiple exceptions can be caught here.  If desc is 0, it means all
+exceptions are caught here.
+@end deffn
+
+@node N_SSYM
+@section N_SSYM
+
+@deffn @code{.stabn} N_SSYM
+@findex N_SSYM
+Structure or union element.
+
+The value is the offset in the structure.
+
+<<?looking at structs and unions in C I didn't see these>>
+@end deffn
+
+@node N_SCOPE
+@section N_SCOPE
+
+@deffn @code{.stab?} N_SCOPE
+@findex N_SCOPE
+Modula2 scope information (Sun linker)
+<<?>>
+@end deffn
+
+@node Gould
+@section Non-base registers on Gould systems
+
+@deffn @code{.stab?} N_NBTEXT
+@deffnx @code{.stab?} N_NBDATA
+@deffnx @code{.stab?} N_NBBSS
+@deffnx @code{.stab?} N_NBSTS
+@deffnx @code{.stab?} N_NBLCS
+@findex N_NBTEXT
+@findex N_NBDATA
+@findex N_NBBSS
+@findex N_NBSTS
+@findex N_NBLCS
+These are used on Gould systems for non-base registers syms.
+
+However, the following values are not the values used by Gould; they are
+the values which GNU has been documenting for these values for a long
+time, without actually checking what Gould uses.  I include these values
+only because perhaps some someone actually did something with the GNU
+information (I hope not, why GNU knowingly assigned wrong values to
+these in the header file is a complete mystery to me).
+
+@example
+240    0xf0     N_NBTEXT  ??
+242    0xf2     N_NBDATA  ??
+244    0xf4     N_NBBSS   ??
+246    0xf6     N_NBSTS   ??
+248    0xf8     N_NBLCS   ??
+@end example
+@end deffn
+
+@node N_LENG
+@section N_LENG
+
+@deffn @code{.stabn} N_LENG
+@findex N_LENG
+Second symbol entry containing a length-value for the preceding entry.
+The value is the length.
+@end deffn
+
+@node Questions
+@appendix Questions and Anomalies
+
+@itemize @bullet
+@item
+@c I think this is changed in GCC 2.4.5 to put the line number there.
+For GNU C stabs defining local and global variables (@code{N_LSYM} and
+@code{N_GSYM}), the desc field is supposed to contain the source
+line number on which the variable is defined.  In reality the desc
+field is always 0.  (This behavior is defined in @file{dbxout.c} and
+putting a line number in desc is controlled by @samp{#ifdef
+WINNING_GDB}, which defaults to false). GDB supposedly uses this
+information if you say @samp{list @var{var}}.  In reality, @var{var} can
+be a variable defined in the program and GDB says @samp{function
+@var{var} not defined}.
+
+@item
+In GNU C stabs, there seems to be no way to differentiate tag types:
+structures, unions, and enums (symbol descriptor @samp{T}) and typedefs
+(symbol descriptor @samp{t}) defined at file scope from types defined locally
+to a procedure or other more local scope.  They all use the @code{N_LSYM}
+stab type.  Types defined at procedure scope are emited after the
+@code{N_RBRAC} of the preceding function and before the code of the
+procedure in which they are defined.  This is exactly the same as
+types defined in the source file between the two procedure bodies.
+GDB overcompensates by placing all types in block #1, the block for
+symbols of file scope.  This is true for default, @samp{-ansi} and
+@samp{-traditional} compiler options. (Bugs gcc/1063, gdb/1066.)
+
+@item
+What ends the procedure scope?  Is it the proc block's @code{N_RBRAC} or the
+next @code{N_FUN}?  (I believe its the first.)
+@end itemize
+
+@node Stab Sections
+@appendix Using Stabs in Their Own Sections
+
+Many object file formats allow tools to create object files with custom
+sections containing any arbitrary data.  For any such object file
+format, stabs can be embedded in special sections.  This is how stabs
+are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs
+are used with COFF.
+
+@menu
+* Stab Section Basics::    How to embed stabs in sections
+* ELF Linker Relocation::  Sun ELF hacks
+@end menu
+
+@node Stab Section Basics
+@appendixsec How to Embed Stabs in Sections
+
+The assembler creates two custom sections, a section named @code{.stab}
+which contains an array of fixed length structures, one struct per stab,
+and a section named @code{.stabstr} containing all the variable length
+strings that are referenced by stabs in the @code{.stab} section.  The
+byte order of the stabs binary data depends on the object file format.
+For ELF, it matches the byte order of the ELF file itself, as determined
+from the @code{EI_DATA} field in the @code{e_ident} member of the ELF
+header.  For SOM, it is always big-endian (is this true??? FIXME).  For
+COFF, it matches the byte order of the COFF headers.  The meaning of the
+fields is the same as for a.out (@pxref{Symbol Table Format}), except
+that the @code{n_strx} field is relative to the strings for the current
+compilation unit (which can be found using the synthetic N_UNDF stab
+described below), rather than the entire string table.
+
+The first stab in the @code{.stab} section for each compilation unit is
+synthetic, generated entirely by the assembler, with no corresponding
+@code{.stab} directive as input to the assembler.  This stab contains
+the following fields:
+
+@table @code
+@item n_strx
+Offset in the @code{.stabstr} section to the source filename.
+
+@item n_type
+@code{N_UNDF}.
+
+@item n_other
+Unused field, always zero.
+This may eventually be used to hold overflows from the count in
+the @code{n_desc} field.
+
+@item n_desc
+Count of upcoming symbols, i.e., the number of remaining stabs for this
+source file.
+
+@item n_value
+Size of the string table fragment associated with this source file, in
+bytes.
+@end table
+
+The @code{.stabstr} section always starts with a null byte (so that string
+offsets of zero reference a null string), followed by random length strings,
+each of which is null byte terminated.
+
+The ELF section header for the @code{.stab} section has its
+@code{sh_link} member set to the section number of the @code{.stabstr}
+section, and the @code{.stabstr} section has its ELF section
+header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a
+string table.  SOM and COFF have no way of linking the sections together
+or marking them as string tables.
+
+For COFF, the @code{.stab} and @code{.stabstr} sections may be simply
+concatenated by the linker.  GDB then uses the @code{n_desc} fields to
+figure out the extent of the original sections.  Similarly, the
+@code{n_value} fields of the header symbols are added together in order
+to get the actual position of the strings in a desired @code{.stabstr}
+section.  Although this design obviates any need for the linker to
+relocate or otherwise manipulate @code{.stab} and @code{.stabstr}
+sections, it also requires some care to ensure that the offsets are
+calculated correctly.  For instance, if the linker were to pad in
+between the @code{.stabstr} sections before concatenating, then the
+offsets to strings in the middle of the executable's @code{.stabstr}
+section would be wrong.
+
+The GNU linker is able to optimize stabs information by merging
+duplicate strings and removing duplicate header file information
+(@pxref{Include Files}).  When some versions of the GNU linker optimize
+stabs in sections, they remove the leading @code{N_UNDF} symbol and
+arranges for all the @code{n_strx} fields to be relative to the start of
+the @code{.stabstr} section.
+
+@node ELF Linker Relocation
+@appendixsec Having the Linker Relocate Stabs in ELF 
+
+This section describes some Sun hacks for Stabs in ELF; it does not
+apply to COFF or SOM.
+
+To keep linking fast, you don't want the linker to have to relocate very
+many stabs.  Making sure this is done for @code{N_SLINE},
+@code{N_RBRAC}, and @code{N_LBRAC} stabs is the most important thing
+(see the descriptions of those stabs for more information).  But Sun's
+stabs in ELF has taken this further, to make all addresses in the
+@code{n_value} field (functions and static variables) relative to the
+source file.  For the @code{N_SO} symbol itself, Sun simply omits the
+address.  To find the address of each section corresponding to a given
+source file, the compiler puts out symbols giving the address of each
+section for a given source file.  Since these are ELF (not stab)
+symbols, the linker relocates them correctly without having to touch the
+stabs section.  They are named @code{Bbss.bss} for the bss section,
+@code{Ddata.data} for the data section, and @code{Drodata.rodata} for
+the rodata section.  For the text section, there is no such symbol (but
+there should be, see below).  For an example of how these symbols work,
+@xref{Stab Section Transformations}.  GCC does not provide these symbols;
+it instead relies on the stabs getting relocated.  Thus addresses which
+would normally be relative to @code{Bbss.bss}, etc., are already
+relocated.  The Sun linker provided with Solaris 2.2 and earlier
+relocates stabs using normal ELF relocation information, as it would do
+for any section.  Sun has been threatening to kludge their linker to not
+do this (to speed up linking), even though the correct way to avoid
+having the linker do these relocations is to have the compiler no longer
+output relocatable values.  Last I heard they had been talked out of the
+linker kludge.  See Sun point patch 101052-01 and Sun bug 1142109.  With
+the Sun compiler this affects @samp{S} symbol descriptor stabs
+(@pxref{Statics}) and functions (@pxref{Procedures}).  In the latter
+case, to adopt the clean solution (making the value of the stab relative
+to the start of the compilation unit), it would be necessary to invent a
+@code{Ttext.text} symbol, analogous to the @code{Bbss.bss}, etc.,
+symbols.  I recommend this rather than using a zero value and getting
+the address from the ELF symbols.
+
+Finding the correct @code{Bbss.bss}, etc., symbol is difficult, because
+the linker simply concatenates the @code{.stab} sections from each
+@file{.o} file without including any information about which part of a
+@code{.stab} section comes from which @file{.o} file.  The way GDB does
+this is to look for an ELF @code{STT_FILE} symbol which has the same
+name as the last component of the file name from the @code{N_SO} symbol
+in the stabs (for example, if the file name is @file{../../gdb/main.c},
+it looks for an ELF @code{STT_FILE} symbol named @code{main.c}).  This
+loses if different files have the same name (they could be in different
+directories, a library could have been copied from one system to
+another, etc.).  It would be much cleaner to have the @code{Bbss.bss}
+symbols in the stabs themselves.  Having the linker relocate them there
+is no more work than having the linker relocate ELF symbols, and it
+solves the problem of having to associate the ELF and stab symbols.
+However, no one has yet designed or implemented such a scheme.
+
+@node Symbol Types Index
+@unnumbered Symbol Types Index
+
+@printindex fn
+
+@contents
+@bye
author	Stan Shebs <shebs@codesourcery.com>	1999-04-16 01:35:26 +0000
committer	Stan Shebs <shebs@codesourcery.com>	1999-04-16 01:35:26 +0000
commit	c906108c21474dfb4ed285bcc0ac6fe02cd400cc (patch)
tree	a0015aa5cedc19ccbab307251353a41722a3ae13 /gdb/doc
parent	cd946cff9ede3f30935803403f06f6ed30cad136 (diff)
download	ppe42-binutils-c906108c21474dfb4ed285bcc0ac6fe02cd400cc.tar.gz ppe42-binutils-c906108c21474dfb4ed285bcc0ac6fe02cd400cc.zip