diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/ChangeLog | 330 | ||||
| -rw-r--r-- | gdb/doc/Makefile.in | 4 | ||||
| -rw-r--r-- | gdb/doc/annotate.texinfo | 12 | ||||
| -rw-r--r-- | gdb/doc/fdl.texi | 372 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 971 | ||||
| -rw-r--r-- | gdb/doc/gdbint.texinfo | 470 | ||||
| -rw-r--r-- | gdb/doc/stabs.texinfo | 101 |
7 files changed, 1516 insertions, 744 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index ce378b425b7..6d70a7e4ddb 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,269 @@ +2004-03-19 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Delete + reference to GDB_TARGET_IS_HPPA. + +2004-03-18 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Coding): Update section on gdbarch_data, + describe pre_init and post_init. + +2004-03-09 Daniel Jacobowitz <drow@mvista.com> + + * gdb.texinfo (Debugging Output): Document values for "set debug + target". + +2004-02-28 Andrew Cagney <cagney@redhat.com> + + * gdb.texinfo (Contributors): Mention GDB 6.1 release engineer. + +2004-02-26 Jeff Johnston <jjohnstn@redhat.com> + + * gdb.texinfo (breakpoints): Add information about the + new "set breakpoint pending" and "show breakpoint pending" + commands. + +2004-02-26 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Coding): Document use of gdbarch_obstack_zalloc + in Per-architecture module data section. + +2004-02-25 Roland McGrath <roland@redhat.com> + + * gdb.texinfo (General Query Packets): Document qPart:... packets. + +2004-02-24 Andrew Cagney <cagney@redhat.com> + + * annotate.texinfo: Wrap fdl.texi include in raise/lower sections. + * gdb.texinfo, gdbint.texinfo, stabs.texinfo: Ditto. + * fdl.texi: Import Version 1.2, November 2002. + +2004-02-17 Andrew Cagney <cagney@redhat.com> + + * gdb.texinfo (Mode Options): Note that "mi1" is deprecated. + +2004-02-16 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Deprecate + FRAMELESS_FUNCTION_INVOCATION. + +2004-02-16 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Coding): Mention -Wunused-function. + +2004-02-14 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Delete + description of DEPRECATED_CALL_DUMMY_STACK_ADJUST. + +2004-02-12 Elena Zannoni <ezannoni@redhat.com> + + * gdb.texinfo: Properly quote the name "C++". + * gdbint.texinfo: Ditto. + * stabs.texinfo: Ditto. + +2004-02-11 Elena Zannoni <ezannoni@redhat.com> + + * gdbint.texinfo (Support Libraries): Add doco about obstacks and + minimal information about libiberty. + +2004-02-06 Michael Chastain <mec.gnu@mindspring.com> + + * gdb.texinfo (Auxiliary Vector): Fix thinko with @value{GDBN}. + +2004-02-04 Roland McGrath <roland@redhat.com> + + * gdb.texinfo (Auxiliary Vector): New node (section). + (Data): Add it to the menu. + +2004-02-02 Jeff Johnston <jjohnstn@redhat.com> + + * gdb.texinfo (Breakpoints): Add information about pending + breakpoint support. + +2004-01-26 Andrew Cagney <cagney@redhat.com> + + * gdb.texinfo (Overview): Delete references to the cisco protocol + including the "N" response. + +2004-01-26 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Rename + EXTRACT_STRUCT_VALUE_ADDRESS to + DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS. + +2004-01-24 Eli Zaretskii <eliz@gnu.org> + + * gdb.texinfo (KOD): Document "show os". Add index entries for + "set/show os" and "info cisco" commands. + +2004-01-21 Eli Zaretskii <eliz@gnu.org> + + * Makefile.in (install-info): Prepend $(DESTDIR) to $(infodir). + +2004-01-19 Michael Chastain <mec.gnu@mindspring.com> + + * gdbint.texinfo: Delete USE_MMALLOC, NO_MMCHECK, MMCHECK_FORCE, + MMAP_BASE_ADDRESS, MMAP_INCREMENT. + +2004-01-19 Nick Roberts <nick@nick.uklinux.net> + + * gdb.texinfo (GDB/MI Stack Manipulation): Describe extension to + -stack-list-locals. + (GDB/MI Variable Objects): Describe extension to + -var-list-children. + +2004-01-17 Daniel Jacobowitz <drow@mvista.com> + + * gdbint.texinfo (DECR_PC_AFTER_HW_BREAK): Don't document. + +2004-01-17 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Delete + documentation on DEPRECATED_NPC_REGNUM. + +2004-01-13 Daniel Jacobowitz <drow@mvista.com> + + * gdb.texinfo: Update copyright year. Mention that set + follow-fork-mode is supported on GNU/Linux. Remove documentation of + "set follow-fork-mode ask". + +2004-01-13 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo: Update copyright year. + (Coding): Add -Wunused-label to list of -Werror warnings. + +2004-01-08 Jason Molenda <jmolenda@apple.com> + Eli Zaretskii <eliz@is.elta.co.il> + + * gdb.texinfo: Update copyright. + (Objective-C): "methodName" typeo fixed. Add @code/@var markup + around names, as appropriate. Minor syntax cleanup of + _NSPrintForDebugger explanation. Two spaces after periods. + GDBN used instead of lit. "gdb". Index entries added for + print-object and _NSPrintForDebugger. @noindent added in one spot. + +2003-11-11 Elena Zannoni <ezannoni@redhat.com> + + * stabs.texinfo: Add dircategory and direntry commands. + * annotate.texinfo: Ditto. + +2003-11-10 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Replace the + return_value method's "inval" and "outval" parameters with + "readbuf" and "writebuf". + +2003-10-28 Jim Blandy <jimb@redhat.com> + + * gdb.texinfo (The F request packet, The F reply packet): Renamed + from "The `F' request packet" and "The `F' reply packet", to make + texi2dvi happy. + (File-I/O remote protocol extension): Update menu entries, too. + +2003-10-26 Michael Chastain <mec@shout.net> + + * gdb.texinfo (Thread Stops): Document the issue with + premature return from system calls in multi-threaded programs. + +2003-10-24 Andrew Cagney <cagney@redhat.com> + + * annotate.texinfo: Fix "fortunatly"[sic]. + +2003-10-23 Kei Sakamoto <sakamoto.kei@renesas.com> + + * gdb.texinfo (Contributors to GDB): Replace "Renesas" + with "Hitachi" and "Mitsubishi". + +2003-10-20 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Document + gdbarch_return_value. Add cross references from + USE_STRUCT_CONVENTION, EXTRACT_RETURN_VALUE, and + STORE_RETURN_VALUE, and from/to EXTRACT_STRUCT_VALUE_ADDRESS. + +2003-10-18 Mark Kettenis <kettenis@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Document + regset_from_core_section. + +2003-10-16 Kei Sakamot Sakamoto <sakamoto.kei@renesas.com> + + * gdb.texinfo (M32R/D): Mention m32rsdi target. + +2003-10-15 Kevin Buettner <kevinb@redhat.com> + + From Anthony Green <green@redhat.com>: + * gdb.texinfo (Breakpoints related warnings): Insert into menu. + +2003-10-14 Kevin Buettner <kevinb@redhat.com> + + * gdb.texinfo (Breakpoint related warnings): New node. + * gdbint.texinfo (ADJUST_BREAKPOINT_ADDRESS): Document. + +2003-10-13 Daniel Jacobowitz <drow@mvista.com> + + * gdb.texinfo (Remote Protocol): Document v and vCont. + +2003-10-10 Kei Sakamoto <sakamoto.kei@renesas.com> + + * gdb.texinfo: Replace "Hitachi" and "Mitsubishi" with "Renesas". + * gdbint.texinfo: Ditto. + +2003-10-09 Andrew Cagney <cagney@redhat.com> + + From 2003-09-18 David Anderson <davea@sgi.com>: + * gdb.texinfo (GDB/MI Symbol Query): Replace "comamnd" with + "command". + +2003-10-03 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Deprecate + IBM6000_TARGET. Mention that it implies an RS/6000 system and not + just target. + +2003-10-02 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Rename + REGISTER_RAW_SIZE to DEPRECATED_REGISTER_RAW_SIZE. + * gdb.texinfo (Packets, Stop Reply Packets): Ditto. + * gdbint.texinfo (Target Architecture Definition): Rename + +2003-09-30 Andrew Cagney <cagney@redhat.com> + + REGISTER_VIRTUAL_SIZE to DEPRECATED_REGISTER_VIRTUAL_SIZE. + (Target Architecture Definition): + + * gdbint.texinfo (Target Architecture Definition): Rename + REGISTER_VIRTUAL_TYPE to DEPRECATED_REGISTER_VIRTUAL_TYPE. + +2003-09-29 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Delete + documentation for NEED_TEXT_START_END. + + * gdbint.texinfo (Target Architecture Definition): Rename + NPC_REGNUM to DEPRECATED_NPC_REGNUM. Add cross reference to + TARGET_WRITE_PC. + +2003-09-22 Michael Chastain <mec@shout.net> + + * gdbint.texinfo (Testsuite Organization): Change gdb.c++ to gdb.cp. + +2003-09-21 Anthony Green <green@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Fix typos. + +2003-09-21 Mark Kettenis <kettenis@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Document + stabs_argument_has_addr. + +2003-09-18 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Delete + documentation on REGISTER_NAMES. + 2003-09-13 Mark Kettenis <kettenis@gnu.org> * gdbint.texinfo (Target Architecture Definition): Replace @@ -253,7 +519,7 @@ 2003-04-02 Bob Rossi <bob_rossi@cox.net> - * gdb.texinfo (GDB/MI Program Control): Add + * gdb.texinfo (GDB/MI Program Control): Add '-file-list-exec-source-file' 2003-03-31 Andrew Cagney <cagney@redhat.com> @@ -265,7 +531,7 @@ * gdbint.texinfo (Target Architecture Definition): Remove reference to TARGET_WRITE_SP. - + 2003-03-27 Andrew Cagney <cagney@redhat.com> * gdbint.texinfo (Target Architecture Definition): Remove @@ -326,7 +592,7 @@ * gdbint.texinfo (Target Architecture Definition): Rename FRAME_SAVED_PC to DEPRECATED_FRAME_SAVED_PC. - + 2003-03-10 Corinna Vinschen <vinschen@redhat.com> * gdb.texinfo: Add File-I/O documentation. @@ -748,7 +1014,7 @@ 2002-08-08 Grace Sainsbury <graces@redhat.com> - From Mark Salter: + From Mark Salter: * gdb.texinfo (Protocol): Document T packet extension to allow watchpoint address reporting. @@ -906,7 +1172,7 @@ From Eli Zaretskii <eliz@is.elta.co.il> * gdb.texinfo (show max-user-call-depth): Correct formatting. - Provide a better explaination of this feature. + Provide a better explaination of this feature. 2002-04-14 Andrew Cagney <ac131313@redhat.com> @@ -947,7 +1213,7 @@ * gdb.texinfo: Change all examples to @smallexample. * gdbint.texinfo: Ditto. - + 2002-03-18 Andrew Cagney <ac131313@redhat.com> * gdbint.texinfo (Releasing GDB): Add section ``Versions and @@ -1189,7 +1455,7 @@ Tue Jan 22 11:57:38 2002 Andrew Cagney <cagney@redhat.com> * gdb.texinfo (maint info sections): Document. - * gdb.texinfo (info proc): Comment out documentation for + * gdb.texinfo (info proc): Comment out documentation for 'info proc' sub-options that are currently not implemented. 2001-12-20 Jim Blandy <jimb@redhat.com> @@ -1251,7 +1517,7 @@ Tue Jan 22 11:57:38 2002 Andrew Cagney <cagney@redhat.com> 2001-11-05 Michael Snyder <msnyder@redhat.com> - * gdb.texinfo (info functions): Document use of backslash to + * gdb.texinfo (info functions): Document use of backslash to quote regexp chars in function names such as "operator*()". 2001-11-01 Fred Fish <fnf@redhat.com> @@ -1317,7 +1583,7 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> * gdbint.texinfo: Add a cautionary note about macro use. 2001-08-02 Corinna Vinschen <vinschen@redhat.com> - + * gdb.texinfo: Explain omitting the hostname in the `target remote' command. @@ -1706,10 +1972,10 @@ Tue Mar 28 18:28:45 2000 Andrew Cagney <cagney@b1.cygnus.com> * gdb.texinfo (Protocol): Replace ``qfThreadExtraInfo'' with qThreadExtraInfo. -2000-03-28 J.T. Conklin <jtc@redback.com> +2000-03-28 J.T. Conklin <jtc@redback.com> - * gdb.texinfo: Clarify which remote debug protocol commands are - required and which are optional. + * gdb.texinfo: Clarify which remote debug protocol commands are + required and which are optional. Tue Mar 28 16:06:22 2000 Andrew Cagney <cagney@b1.cygnus.com> @@ -1743,9 +2009,9 @@ Fri Mar 24 18:06:34 2000 Andrew Cagney <cagney@b1.cygnus.com> * gdb.texinfo: Check for @ifinfo instead of @ifnottex. (rluser.texinfo, inc-hist.texinfo, annotate.texi): Add local @chapter and @node entries. - + * gdb.texinfo: Link all top-level nodes. - + Fri Mar 24 17:56:48 2000 Andrew Cagney <cagney@b1.cygnus.com> * Makefile.in (install-info): Create $(infodir) before installing @@ -1766,7 +2032,7 @@ Fri Mar 24 17:56:48 2000 Andrew Cagney <cagney@b1.cygnus.com> 2000-03-20 Michael Snyder <msnyder@cleaver.cygnus.com> - * gdb.texinfo: Add white space to prevent overprinting in + * gdb.texinfo: Add white space to prevent overprinting in two places. 2000-03-17 Stan Shebs <shebs@apple.com> @@ -1936,8 +2202,8 @@ Wed Aug 11 13:18:14 1999 Andrew Cagney <cagney@amy.cygnus.com> 1999-08-10 Elena Zannoni <ezannoni@kwikemart.cygnus.com> - * Makefile.in: Rename inc-hist.texi to inc-hist.texinfo. - * gdb.texinfo: Ditto. + * Makefile.in: Rename inc-hist.texi to inc-hist.texinfo. + * gdb.texinfo: Ditto. 1999-08-06 Tom Tromey <tromey@cygnus.com> @@ -2042,7 +2308,7 @@ Tue Apr 20 11:59:38 1999 Andrew Cagney <cagney@b1.cygnus.com> LITTLE_BREAKPOINT, LITTLE_REMOTE_BREAKPOINT, BIG_REMOTE_BREAKPOINT): Deprecate in favor of REGISTER_NAME and BREAKPOINT_FROM_PC. - + Mon Apr 12 16:00:44 1999 Andrew Cagney <cagney@b1.cygnus.com> * gdbint.texinfo (CALL_DUMMY_STACK_ADJUST_P, @@ -2098,14 +2364,14 @@ Thu Jan 14 17:10:12 1999 Stan Shebs <shebs@andros.cygnus.com> 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 + * 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) @@ -2118,7 +2384,7 @@ 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. @@ -2167,7 +2433,7 @@ Tue Dec 1 17:45:43 1998 Stan Shebs <shebs@andros.cygnus.com> Mon Nov 30 11:32:21 1998 Andrew Cagney <cagney@chook> - * gdbint.texinfo (FRAME_CHAIN_VALID_ALTERNATE): + * gdbint.texinfo (FRAME_CHAIN_VALID_ALTERNATE): Sat Nov 28 13:45:53 1998 Andrew Cagney <cagney@b1.cygnus.com> @@ -2214,7 +2480,7 @@ 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 @@ -2290,14 +2556,14 @@ Fri Jul 5 15:38:54 1996 Fred Fish <fnf@cygnus.com> 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, + * Makefile.in (srcdir, VPATH, prefix, infodir, INSTALL, INSTALL_PROGRAM, INSTALL_DATA): Use autoconf set values. * configure.in: Rewritten for autoconf. * configure: New. @@ -2315,7 +2581,7 @@ Mon Jun 17 10:43:41 1996 Fred Fish <fnf@cygnus.com> (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 + (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. @@ -2686,7 +2952,7 @@ Sun Nov 28 18:06:25 1993 Roland H. Pesch (pesch@fowanton.cygnus.com) 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 @@ -3002,7 +3268,7 @@ Fri Jul 9 09:47:02 1993 Peter Schauer (pes@regent.e-technik.tu-muenchen.de) 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. + removed from the code by Kingdon. Tue Jul 6 12:24:34 1993 Jim Kingdon (kingdon@lioth.cygnus.com) @@ -3431,7 +3697,7 @@ Mon Aug 24 01:17:55 1992 John Gilmore (gnu@cygnus.com) 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). + examples (not consistent w others). gdb.texinfo: issue disclaimer paragraph on cmdline options only for generic vn of doc @@ -3498,7 +3764,7 @@ 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. + structure (add glob and mmalloc). Update configure doc. Tue Mar 24 23:28:38 1992 K. Richard Pixley (rich@cygnus.com) @@ -3527,7 +3793,7 @@ 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. + standards.text support. Thu Dec 5 22:46:12 1991 K. Richard Pixley (rich at rtl.cygnus.com) diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index a06cc4ac711..90043b7fa51 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -171,8 +171,8 @@ install-info: $(INFO_DEPS) @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ list='$(INFO_DEPS)'; \ for file in $$list; do \ - echo " install-info --info-dir=$(infodir) $(DESTDIR)$(infodir)/$$file";\ - install-info --info-dir=$(infodir) $(DESTDIR)$(infodir)/$$file || :;\ + echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\ + install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\ done; \ else : ; fi diff --git a/gdb/doc/annotate.texinfo b/gdb/doc/annotate.texinfo index 401657d4a96..86b90cc74e7 100644 --- a/gdb/doc/annotate.texinfo +++ b/gdb/doc/annotate.texinfo @@ -1,6 +1,14 @@ \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename annotate.info + +@c This is a dir.info fragment to support semi-automated addition of +@c manuals to an info tree. +@dircategory Programming & development tools. +@direntry +* Annotate: (annotate). The obsolete annotation interface. +@end direntry + @c @include gdb-cfg.texi @c @@ -146,7 +154,7 @@ This chapter discusses the known problems. @section Dependant on @sc{cli} output The annotation interface works by interspersing markups with -@value{GDBN} normal command-line interpreter output. Unfortunatly, this +@value{GDBN} normal command-line interpreter output. Unfortunately, this makes the annotation client dependant on not just the annotations, but also the @sc{cli} output. This is because the client is forced to assume that specific @value{GDBN} commands provide specific information. @@ -812,7 +820,9 @@ 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). +@raisesections @include fdl.texi +@lowersections @ignore @node Index diff --git a/gdb/doc/fdl.texi b/gdb/doc/fdl.texi index f4726b9b149..11737cc89bd 100644 --- a/gdb/doc/fdl.texi +++ b/gdb/doc/fdl.texi @@ -1,28 +1,29 @@ -@c -*-texinfo-*- + @node GNU Free Documentation License +@appendixsec GNU Free Documentation License -@appendix GNU Free Documentation License -@center Version 1.1, March 2000 +@cindex FDL, GNU Free Documentation License +@center Version 1.2, November 2002 @display -Copyright (C) 2000 Free Software Foundation, Inc. -59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @end display -@sp 1 + @enumerate 0 @item PREAMBLE The purpose of this License is to make a manual, textbook, or other -written document ``free'' in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. This License is a kind of ``copyleft'', which means that derivative works of the document must themselves be free in the same sense. It @@ -37,60 +38,72 @@ it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. -@sp 1 @item APPLICABILITY AND DEFINITIONS -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The ``Document'', below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as ``you.'' +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. A ``Modified Version'' of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The ``Invariant Sections'' are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. The ``Cover Texts'' are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. A ``Transparent'' copy of the Document means a machine-readable copy, represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and +general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not ``Transparent'' is called ``Opaque.'' +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML designed for human modification. Opaque formats include -PostScript, PDF, proprietary formats that can be read and edited only -by proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML produced by some word processors for output -purposes only. +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. The ``Title Page'' means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material @@ -98,7 +111,22 @@ this License requires to appear in the title page. For works in formats which do not have any title page as such, ``Title Page'' means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. -@sp 1 + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + @item VERBATIM COPYING @@ -114,13 +142,14 @@ number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. -@sp 1 + @item COPYING IN QUANTITY -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present @@ -138,21 +167,20 @@ pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. -@sp 1 + @item MODIFICATIONS @@ -163,52 +191,85 @@ Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: -A. Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission.@* -B. List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has less than five).@* -C. State on the Title page the name of the publisher of the - Modified Version, as the publisher.@* -D. Preserve all the copyright notices of the Document.@* -E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices.@* -F. Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below.@* -G. Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice.@* -H. Include an unaltered copy of this License.@* -I. Preserve the section entitled ``History'', and its title, and add to - it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled ``History'' in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence.@* -J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the ``History'' section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission.@* -K. In any section entitled ``Acknowledgements'' or ``Dedications'', - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein.@* -L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles.@* -M. Delete any section entitled ``Endorsements.'' Such a section - may not be included in the Modified Version.@* -N. Do not retitle any existing section as ``Endorsements'' - or to conflict in title with any Invariant Section.@* -@sp 1 +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all @@ -216,9 +277,9 @@ of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. -You may add a section entitled ``Endorsements'', provided it contains +You may add a section Entitled ``Endorsements'', provided it contains nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has +parties---for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. @@ -235,7 +296,7 @@ permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. -@sp 1 + @item COMBINING DOCUMENTS @@ -244,7 +305,7 @@ License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its -license notice. +license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single @@ -255,12 +316,12 @@ author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. -In the combination, you must combine any sections entitled ``History'' -in the various original documents, forming one section entitled -``History''; likewise combine any sections entitled ``Acknowledgements'', -and any sections entitled ``Dedications.'' You must delete all sections -entitled ``Endorsements.'' -@sp 1 +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + @item COLLECTIONS OF DOCUMENTS @@ -274,25 +335,27 @@ You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. -@sp 1 + @item AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an ``aggregate'', and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. -@sp 1 +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + @item TRANSLATION @@ -302,11 +365,18 @@ Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. -@sp 1 +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + @item TERMINATION @@ -317,7 +387,7 @@ automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. -@sp 1 + @item FUTURE REVISIONS OF THIS LICENSE @@ -325,7 +395,7 @@ The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See -http://www.gnu.org/copyleft/. +@uref{http://www.gnu.org/copyleft/}. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this @@ -335,10 +405,10 @@ of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. - @end enumerate -@unnumberedsec ADDENDUM: How to use this License for your documents +@page +@appendixsubsec ADDENDUM: How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and @@ -346,23 +416,37 @@ license notices just after the title page: @smallexample @group -Copyright (C) @var{year} @var{your name}. -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 -or any later version published by the Free Software Foundation; -with the Invariant Sections being @var{list their titles}, with the -Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. -A copy of the license is included in the section entitled "GNU -Free Documentation License." + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. @end group @end smallexample -If you have no Invariant Sections, write ``with no Invariant Sections'' -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write ``no Front-Cover Texts'' instead of -``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index cf69fd3e741..dac02de0ef2 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, -@c 1999, 2000, 2001, 2002, 2003 +@c 1999, 2000, 2001, 2002, 2003, 2004 @c Free Software Foundation, Inc. @c @c %**start of header @@ -52,7 +52,7 @@ This is the @value{EDITION} Edition, of @cite{Debugging with Version @value{GDBVN}. Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@* - 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. + 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or @@ -84,7 +84,7 @@ development.'' @vskip 0pt plus 1filll Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, -1996, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. @sp 2 Published by the Free Software Foundation @* 59 Temple Place - Suite 330, @* @@ -115,7 +115,7 @@ This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. This is the @value{EDITION} Edition, for @value{GDBN} Version @value{GDBVN}. -Copyright (C) 1988-2003 Free Software Foundation, Inc. +Copyright (C) 1988-2004 Free Software Foundation, Inc. @menu * Summary:: Summary of @value{GDBN} @@ -192,7 +192,7 @@ Change things in your program, so you can experiment with correcting the effects of one bug and go on to learn about another. @end itemize -You can use @value{GDBN} to debug programs written in C and C++. +You can use @value{GDBN} to debug programs written in C and C@t{++}. For more information, see @ref{Support,,Supported languages}. For more information, see @ref{C,,C and C++}. @@ -347,7 +347,7 @@ omitted from this list, we would like to add your names! So that they may not regard their many labors as thankless, we particularly thank those who shepherded @value{GDBN} through major releases: -Andrew Cagney (releases 6.0, 5.3, 5.2, 5.1 and 5.0); +Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs (release 4.14); @@ -418,12 +418,13 @@ Fred Fish wrote most of the support for Unix System Vr4. He also enhanced the command-completion support to cover C@t{++} overloaded symbols. -Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and -Super-H processors. +Hitachi America (now Renesas 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. +Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D +processors. Toshiba sponsored the support for the TX39 Mips processor. @@ -860,7 +861,7 @@ equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) If the second argument begins with a decimal digit, @value{GDBN} will first attempt to attach to it as a process, and if that fails, attempt to open it as a corefile. If you have a corefile whose name begins with -a digit, you can prevent @value{GDBN} from treating it as a pid by +a digit, you can prevent @value{GDBN} from treating it as a pid by prefixing it with @file{./}, eg. @file{./12345}. If @value{GDBN} has not been configured to included core file support, @@ -900,7 +901,7 @@ file. @itemx -c @var{file} @cindex @code{--core} @cindex @code{-c} -Use file @var{file} as a core dump to examine. +Use file @var{file} as a core dump to examine. @item -c @var{number} @item -pid @var{number} @@ -1111,7 +1112,7 @@ Run using @var{device} for your program's standard input and output. @c resolve the situation of these eventually @item -tui @cindex @code{--tui} -Activate the Terminal User Interface when starting. +Activate the Terminal User Interface when starting. The Terminal User Interface manages several text windows on the terminal, showing source, assembly, registers and @value{GDBN} command outputs (@pxref{TUI, ,@value{GDBN} Text User Interface}). @@ -1134,10 +1135,10 @@ communicate with @value{GDBN} using it as a back end. @samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes @value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, , -The @sc{gdb/mi} Interface}) included in @var{GDBN} version 6.0. The -previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3, -can be selected with @samp{--interpreter=mi1}. Earlier @sc{gdb/mi} -interfaces are not supported. +The @sc{gdb/mi} Interface}) included since @var{GDBN} version 6.0. The +previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and +selected with @samp{--interpreter=mi1}, is deprecated. Earlier +@sc{gdb/mi} interfaces are no longer supported. @item -write @cindex @code{--write} @@ -2288,9 +2289,10 @@ get its process ID. Then tell @value{GDBN} (a new invocation of the child process (@pxref{Attach}). From that point on you can debug the child process just like any other process which you attached to. -On HP-UX (11.x and later only?), @value{GDBN} provides support for -debugging programs that create additional processes using the -@code{fork} or @code{vfork} function. +On some systems, @value{GDBN} provides support for debugging programs that +create additional processes using the @code{fork} or @code{vfork} functions. +Currently, the only platforms with this feature are HP-UX (11.x and later +only?) and GNU/Linux (kernel version 2.5.60 and later). By default, when a program forks, @value{GDBN} will continue to debug the parent process and the child process will run unimpeded. @@ -2314,8 +2316,6 @@ unimpeded. This is the default. 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 @@ -2441,6 +2441,7 @@ all breakpoint in that range are operated on. * Break Commands:: Breakpoint command lists * Breakpoint Menus:: Breakpoint menus * Error in Breakpoints:: ``Cannot insert breakpoints'' +* Breakpoint related warnings:: ``Breakpoint address adjusted...'' @end menu @node Set Breaks @@ -2598,16 +2599,23 @@ Whether the breakpoint is marked to be disabled or deleted when hit. 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. +Where the breakpoint is in your program, as a memory address. If the +breakpoint is pending (see below for details) on a future load of a shared library, the address +will be listed as @samp{<PENDING>}. @item What Where the breakpoint is in the source for your program, as a file and -line number. +line number. For a pending breakpoint, the original string passed to +the breakpoint command will be listed as it cannot be resolved until +the appropriate shared library is loaded in the future. @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. +are listed after that. A pending breakpoint is allowed to have a condition +specified for it. The condition is not parsed for validity until a shared +library is loaded that allows the pending breakpoint to resolve to a +valid location. @noindent @code{info break} with a breakpoint @@ -2630,6 +2638,58 @@ your program. There is nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (@pxref{Conditions, ,Break conditions}). +@cindex pending breakpoints +If a specified breakpoint location cannot be found, it may be due to the fact +that the location is in a shared library that is yet to be loaded. In such +a case, you may want @value{GDBN} to create a special breakpoint (known as +a @dfn{pending breakpoint}) that +attempts to resolve itself in the future when an appropriate shared library +gets loaded. + +Pending breakpoints are useful to set at the start of your +@value{GDBN} session for locations that you know will be dynamically loaded +later by the program being debugged. When shared libraries are loaded, +a check is made to see if the load resolves any pending breakpoint locations. +If a pending breakpoint location gets resolved, +a regular breakpoint is created and the original pending breakpoint is removed. + +@value{GDBN} provides some additional commands for controlling pending +breakpoint support: + +@kindex set breakpoint pending +@kindex show breakpoint pending +@table @code +@item set breakpoint pending auto +This is the default behavior. When @value{GDBN} cannot find the breakpoint +location, it queries you whether a pending breakpoint should be created. + +@item set breakpoint pending on +This indicates that an unrecognized breakpoint location should automatically +result in a pending breakpoint being created. + +@item set breakpoint pending off +This indicates that pending breakpoints are not to be created. Any +unrecognized breakpoint location results in an error. This setting does +not affect any pending breakpoints previously created. + +@item show breakpoint pending +Show the current behavior setting for creating pending breakpoints. +@end table + +@cindex operations allowed on pending breakpoints +Normal breakpoint operations apply to pending breakpoints as well. You may +specify a condition for a pending breakpoint and/or commands to run when the +breakpoint is reached. You can also enable or disable +the pending breakpoint. When you specify a condition for a pending breakpoint, +the parsing of the condition will be deferred until the point where the +pending breakpoint location is resolved. Disabling a pending breakpoint +tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent +shared library load. When a pending breakpoint is re-enabled, +@value{GDBN} checks to see if the location is already resolved. +This is done because any number of shared library loads could have +occurred since the time the breakpoint was disabled and one or more +of these loads could resolve the location. + @cindex negative breakpoint numbers @cindex internal @value{GDBN} breakpoints @value{GDBN} itself sometimes sets breakpoints in your program for @@ -3214,7 +3274,7 @@ end @cindex overloading @cindex symbol overloading -Some programming languages (notably C@t{++} and Objective-C) permit a +Some programming languages (notably C@t{++} and Objective-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, @@ -3309,6 +3369,58 @@ watchpoints it needs to insert. When this message is printed, you need to disable or remove some of the hardware-assisted breakpoints and watchpoints, and then continue. +@node Breakpoint related warnings +@subsection ``Breakpoint address adjusted...'' +@cindex breakpoint address adjusted + +Some processor architectures place constraints on the addresses at +which breakpoints may be placed. For architectures thus constrained, +@value{GDBN} will attempt to adjust the breakpoint's address to comply +with the constraints dictated by the architecture. + +One example of such an architecture is the Fujitsu FR-V. The FR-V is +a VLIW architecture in which a number of RISC-like instructions may be +bundled together for parallel execution. The FR-V architecture +constrains the location of a breakpoint instruction within such a +bundle to the instruction with the lowest address. @value{GDBN} +honors this constraint by adjusting a breakpoint's address to the +first in the bundle. + +It is not uncommon for optimized code to have bundles which contain +instructions from different source statements, thus it may happen that +a breakpoint's address will be adjusted from one source statement to +another. Since this adjustment may significantly alter @value{GDBN}'s +breakpoint related behavior from what the user expects, a warning is +printed when the breakpoint is first set and also when the breakpoint +is hit. + +A warning like the one below is printed when setting a breakpoint +that's been subject to address adjustment: + +@smallexample +warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. +@end smallexample + +Such warnings are printed both for user settable and @value{GDBN}'s +internal breakpoints. If you see one of these warnings, you should +verify that a breakpoint set at the adjusted address will have the +desired affect. If not, the breakpoint in question may be removed and +other breakpoints may be set which will have the desired behavior. +E.g., it may be sufficient to place the breakpoint at a later +instruction. A conditional breakpoint may also be useful in some +cases to prevent the breakpoint from triggering too often. + +@value{GDBN} will also issue a warning when stopping at one of these +adjusted breakpoints: + +@smallexample +warning: Breakpoint 1 address previously adjusted from 0x00010414 +to 0x00010410. +@end smallexample + +When this warning is encountered, it may be too late to take remedial +action except in cases where the breakpoint is hit earlier or more +frequently than expected. @node Continuing and Stepping @section Continuing and stepping @@ -3707,6 +3819,47 @@ allows you to examine the overall state of the program, including switching between threads, without worrying that things may change underfoot. +@cindex thread breakpoints and system calls +@cindex system calls and thread breakpoints +@cindex premature return from system calls +There is an unfortunate side effect. If one thread stops for a +breakpoint, or for some other reason, and another thread is blocked in a +system call, then the system call may return prematurely. This is a +consequence of the interaction between multiple threads and the signals +that @value{GDBN} uses to implement breakpoints and other events that +stop execution. + +To handle this problem, your program should check the return value of +each system call and react appropriately. This is good programming +style anyways. + +For example, do not write code like this: + +@smallexample + sleep (10); +@end smallexample + +The call to @code{sleep} will return early if a different thread stops +at a breakpoint or for some other reason. + +Instead, write this: + +@smallexample + int unslept = 10; + while (unslept > 0) + unslept = sleep (unslept); +@end smallexample + +A system call is allowed to return early, so the system is still +conforming to its specification. But @value{GDBN} does cause your +multi-threaded program to behave differently than it would without +@value{GDBN}. + +Also, @value{GDBN} uses internal breakpoints in the thread library to +monitor certain events such as thread creation and thread destruction. +When such an event happens, a system call in another thread may return +prematurely, even though your program does not appear to stop. + @cindex continuing threads @cindex threads, continuing Conversely, whenever you restart the program, @emph{all} threads start @@ -4590,6 +4743,7 @@ Table}. * Registers:: Registers * Floating Point Hardware:: Floating point hardware * Vector Unit:: Vector Unit +* Auxiliary Vector:: Auxiliary data provided by operating system * Memory Region Attributes:: Memory region attributes * Dump/Restore Files:: Copy between memory and a file * Character Sets:: Debugging programs that use a different @@ -5770,12 +5924,38 @@ Display information about the vector unit. The exact contents and layout vary depending on the hardware. @end table +@node Auxiliary Vector +@section Operating system auxiliary vector +@cindex auxiliary vector +@cindex vector, auxiliary + +Some operating systems supply an @dfn{auxiliary vector} to programs at +startup. This is akin to the arguments and environment that you +specify for a program, but contains a system-dependent variety of +binary values that tell system libraries important details about the +hardware, operating system, and process. Each value's purpose is +identified by an integer tag; the meanings are well-known but system-specific. +Depending on the configuration and operating system facilities, +@value{GDBN} may be able to show you this information. + +@table @code +@kindex info auxv +@item info auxv +Display the auxiliary vector of the inferior, which can be either a +live process or a core dump file. @value{GDBN} prints each tag value +numerically, and also shows names and text descriptions for recognized +tags. Some values in the vector are numbers, some bit masks, and some +pointers to strings or other data. @value{GDBN} displays each value in the +most appropriate form for a recognized tag, and in hexadecimal for +an unrecognized tag. +@end table + @node Memory Region Attributes -@section Memory region attributes +@section Memory region attributes @cindex memory region attributes -@dfn{Memory region attributes} allow you to describe special handling -required by regions of your target's memory. @value{GDBN} uses attributes +@dfn{Memory region attributes} allow you to describe special handling +required by regions of your target's memory. @value{GDBN} uses attributes to determine whether to allow certain types of memory accesses; whether to use specific width accesses; and whether to cache target memory. @@ -5785,7 +5965,7 @@ accessing memory in that region. Similarly, if no memory regions have been defined, @value{GDBN} uses the default attributes when accessing all memory. -When a memory region is defined, it is given a number to identify it; +When a memory region is defined, it is given a number to identify it; to enable, disable, or remove a memory region, you specify that number. @table @code @@ -5803,7 +5983,7 @@ Remove memory regions @var{nums}@dots{}. @kindex disable mem @item disable mem @var{nums}@dots{} Disable memory regions @var{nums}@dots{}. -A disabled memory region is not forgotten. +A disabled memory region is not forgotten. It may be enabled again later. @kindex enable mem @@ -5818,7 +5998,7 @@ for each region. @table @emph @item Memory Region Number @item Enabled or Disabled. -Enabled memory regions are marked with @samp{y}. +Enabled memory regions are marked with @samp{y}. Disabled memory regions are marked with @samp{n}. @item Lo Address @@ -5835,7 +6015,7 @@ The list of attributes set for this memory region. @subsection Attributes -@subsubsection Memory Access Mode +@subsubsection Memory Access Mode The access mode attributes set whether @value{GDBN} may make read or write accesses to a memory region. @@ -5876,7 +6056,7 @@ Use 64 bit memory accesses. @c @c @table @code @c @item hwbreak -@c Always use hardware breakpoints +@c Always use hardware breakpoints @c @item swbreak (default) @c @end table @@ -5889,13 +6069,13 @@ registers. @table @code @item cache -Enable @value{GDBN} to cache target memory. +Enable @value{GDBN} to cache target memory. @item nocache Disable @value{GDBN} from caching target memory. This is the default. @end table @c @subsubsection Memory Write Verification -@c The memory write verification attributes set whether @value{GDBN} +@c The memory write verification attributes set whether @value{GDBN} @c will re-reads data after each write to verify the write was successful. @c @c @table @code @@ -5957,7 +6137,7 @@ Restore the contents of file @var{filename} into memory. The file format, except for raw binary. To restore a raw binary file you must specify the optional keyword @code{binary} after the filename. -If @var{bias} is non-zero, its value will be added to the addresses +If @var{bias} is non-zero, its value will be added to the addresses contained in the file. Binary files always start at address zero, so they will be restored at address @var{bias}. Other bfd files have a built-in location; they will be restored at offset @var{bias} @@ -5965,7 +6145,7 @@ from that location. If @var{start} and/or @var{end} are non-zero, then only data between file offset @var{start} and file offset @var{end} will be restored. -These offsets are relative to the addresses in the file, before +These offsets are relative to the addresses in the file, before the @var{bias} argument is applied. @end table @@ -6036,15 +6216,15 @@ for both host and target. @item show charset @kindex show charset -Show the names of the current host and target charsets. +Show the names of the current host and target charsets. @itemx show host-charset @kindex show host-charset -Show the name of the current host charset. +Show the name of the current host charset. @itemx show target-charset @kindex show target-charset -Show the name of the current target charset. +Show the name of the current target charset. @end table @@ -6111,7 +6291,7 @@ $ gdb -nw charset-test GNU gdb 2001-12-19-cvs Copyright 2001 Free Software Foundation, Inc. @dots{} -(gdb) +(gdb) @end smallexample We can use the @code{show charset} command to see what character sets @@ -6121,7 +6301,7 @@ strings: @smallexample (gdb) show charset The current host and target character set is `ISO-8859-1'. -(gdb) +(gdb) @end smallexample For the sake of printing this manual, let's use @sc{ascii} as our @@ -6130,7 +6310,7 @@ initial character set: (gdb) set charset ASCII (gdb) show charset The current host and target character set is `ASCII'. -(gdb) +(gdb) @end smallexample Let's assume that @sc{ascii} is indeed the correct character set for our @@ -6144,7 +6324,7 @@ them properly. Since our current target character set is also $1 = 0x401698 "Hello, world!\n" (gdb) print ascii_hello[0] $2 = 72 'H' -(gdb) +(gdb) @end smallexample @value{GDBN} uses the target character set for character and string @@ -6153,7 +6333,7 @@ literals you use in expressions: @smallexample (gdb) print '+' $3 = 43 '+' -(gdb) +(gdb) @end smallexample The @sc{ascii} character set uses the number 43 to encode the @samp{+} @@ -6168,7 +6348,7 @@ character set is still @sc{ascii}, we get jibberish: $4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" (gdb) print ibm1047_hello[0] $5 = 200 '\310' -(gdb) +(gdb) @end smallexample If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, @@ -6176,8 +6356,8 @@ If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, @smallexample (gdb) set target-charset -ASCII EBCDIC-US IBM1047 ISO-8859-1 -(gdb) set target-charset +ASCII EBCDIC-US IBM1047 ISO-8859-1 +(gdb) set target-charset @end smallexample We can select @sc{ibm1047} as our target character set, and examine the @@ -6208,7 +6388,7 @@ string literals you use in expressions: @smallexample (gdb) print '+' $10 = 78 '+' -(gdb) +(gdb) @end smallexample The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} @@ -6218,7 +6398,7 @@ character. @node Macros @chapter C Preprocessor Macros -Some languages, such as C and C++, provide a way to define and invoke +Some languages, such as C and C@t{++}, provide a way to define and invoke ``preprocessor macros'' which expand into strings of tokens. @value{GDBN} can evaluate expressions containing macro invocations, show the result of macro expansion, and show a macro's definition, including @@ -6379,7 +6559,7 @@ Defined at /home/jimb/gdb/macros/play/sample.h:1 expands to: (42 + 1) (gdb) macro expand-once ADD(1) expands to: once (M + 1) -(gdb) +(gdb) @end smallexample In the example above, note that @command{macro expand-once} expands only @@ -6394,11 +6574,11 @@ the source line of the current stack frame: (gdb) break main Breakpoint 1 at 0x8048370: file sample.c, line 10. (gdb) run -Starting program: /home/jimb/gdb/macros/play/sample +Starting program: /home/jimb/gdb/macros/play/sample Breakpoint 1, main () at sample.c:10 10 printf ("Hello, world!\n"); -(gdb) +(gdb) @end smallexample At line 10, the definition of the macro @code{N} at line 9 is in force: @@ -6411,7 +6591,7 @@ Defined at /home/jimb/gdb/macros/play/sample.c:9 expands to: 28 < 42 (gdb) print N Q M $1 = 1 -(gdb) +(gdb) @end smallexample As we step over directives that remove @code{N}'s definition, and then @@ -6435,7 +6615,7 @@ Defined at /home/jimb/gdb/macros/play/sample.c:13 expands to: 1729 < 42 (gdb) print N Q M $2 = 0 -(gdb) +(gdb) @end smallexample @@ -6474,9 +6654,9 @@ tracepoints as of this writing. This chapter describes the tracepoint commands and features. @menu -* Set Tracepoints:: -* Analyze Collected Data:: -* Tracepoint Variables:: +* Set Tracepoints:: +* Analyze Collected Data:: +* Tracepoint Variables:: @end menu @node Set Tracepoints @@ -6501,12 +6681,12 @@ This section describes commands to set tracepoints and associated conditions and actions. @menu -* Create and Delete Tracepoints:: -* Enable and Disable Tracepoints:: -* Tracepoint Passcounts:: -* Tracepoint Actions:: -* Listing Tracepoints:: -* Starting and Stopping Trace Experiment:: +* Create and Delete Tracepoints:: +* Enable and Disable Tracepoints:: +* Tracepoint Passcounts:: +* Tracepoint Actions:: +* Listing Tracepoints:: +* Starting and Stopping Trace Experiment:: @end menu @node Create and Delete Tracepoints @@ -6605,7 +6785,7 @@ user. Examples: @smallexample -(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of +(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} (@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the @@ -7317,7 +7497,7 @@ name normally: @smallexample (gdb) overlay list -Section .ov.foo.text, loaded at 0x100000 - 0x100034, +Section .ov.foo.text, loaded at 0x100000 - 0x100034, mapped at 0x1016 - 0x104a (gdb) print foo $6 = @{int (int)@} 0x1016 <foo> @@ -7400,7 +7580,7 @@ will silently set a breakpoint there. If the overlay manager then calls this function whenever it has changed the overlay table, this will enable @value{GDBN} to accurately keep track of which overlays are in program memory, and update any breakpoints that may be set -in overlays. This will allow breakpoints to work even if the +in overlays. This will allow breakpoints to work even if the overlays are kept in ROM or other non-writable memory while they are not being executed. @@ -7832,7 +8012,7 @@ language reference or tutorial. @menu * C:: C and C@t{++} -* Objective-C:: Objective-C +* Objective-C:: Objective-C * Modula-2:: Modula-2 @end menu @@ -8358,8 +8538,8 @@ This section provides information about some commands and command options that are useful for debugging Objective-C code. @menu -* Method Names in Commands:: -* The Print Command with Objective-C:: +* Method Names in Commands:: +* The Print Command with Objective-C:: @end menu @node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C @@ -8387,12 +8567,13 @@ A fully qualified Objective-C method name is specified as -[@var{Class} @var{methodName}] @end smallexample -where the minus sign is used to indicate an instance method and a plus -sign (not shown) is used to indicate a class method. The -class name @var{Class} and method name @var{methoName} are enclosed in -brackets, similar to the way messages are specified in Objective-C source -code. For example, to set a breakpoint at the @code{create} instance method of -class @code{Fruit} in the program currently being debugged, enter: +where the minus sign is used to indicate an instance method and a +plus sign (not shown) is used to indicate a class method. The class +name @var{Class} and method name @var{methodName} are enclosed in +brackets, similar to the way messages are specified in Objective-C +source code. For example, to set a breakpoint at the @code{create} +instance method of class @code{Fruit} in the program currently being +debugged, enter: @smallexample break -[Fruit create] @@ -8405,10 +8586,10 @@ enter: list +[NSText initialize] @end smallexample -In the current version of GDB, the plus or minus sign is required. In -future versions of GDB, the plus or minus sign will be optional, but you -can use it to narrow the search. It is also possible to specify just a -method name: +In the current version of @value{GDBN}, the plus or minus sign is +required. In future versions of @value{GDBN}, the plus or minus +sign will be optional, but you can use it to narrow the search. It +is also possible to specify just a method name: @smallexample break create @@ -8429,20 +8610,24 @@ clear -[NSWindow makeKeyAndOrderFront:] @node The Print Command with Objective-C @subsubsection The Print Command With Objective-C +@kindex print-object +@kindex po @r{(@code{print-object})} -The print command has also been extended to accept methods. For example: +The print command has also been extended to accept methods. For example: @smallexample -print -[object hash] +print -[@var{object} hash] @end smallexample @cindex print an Objective-C object description -will tell gdb to send the -hash message to object and print the -result. Also an additional command has been added, @code{print-object} -or @code{po} for short, which is meant to print the description of an -object. However, this command may only work with certain Objective-C -libraries that have a particular hook function, called -@code{_NSPrintForDebugger} defined. +@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects +@noindent +will tell @value{GDBN} to send the @code{hash} message to @var{object} +and print the result. Also, an additional command has been added, +@code{print-object} or @code{po} for short, which is meant to print +the description of an object. However, this command may only work +with certain Objective-C libraries that have a particular hook +function, @code{_NSPrintForDebugger}, defined. @node Modula-2, , Objective-C, Support @subsection Modula-2 @@ -9086,8 +9271,8 @@ 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}. If a function name contains characters -that conflict with the regular expression language (eg. +start with @code{step}. If a function name contains characters +that conflict with the regular expression language (eg. @samp{operator*()}), they may be quoted with a backslash. @kindex info variables @@ -9218,7 +9403,7 @@ structure in more detail. For example: (@value{GDBP}) maint info psymtabs dwarf2read @{ objfile /home/gnu/build/gdb/gdb ((struct objfile *) 0x82e69d0) - @{ psymtab /home/gnu/src/gdb/dwarf2read.c + @{ psymtab /home/gnu/src/gdb/dwarf2read.c ((struct partial_symtab *) 0x8474b10) readin no fullname (null) @@ -9243,9 +9428,9 @@ read the symtab for the compilation unit containing that function: Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, line 1574. (@value{GDBP}) maint info symtabs -@{ objfile /home/gnu/build/gdb/gdb +@{ objfile /home/gnu/build/gdb/gdb ((struct objfile *) 0x82e69d0) - @{ symtab /home/gnu/src/gdb/dwarf2read.c + @{ symtab /home/gnu/src/gdb/dwarf2read.c ((struct symtab *) 0x86c1f38) dirname (null) fullname (null) @@ -9253,7 +9438,7 @@ line 1574. debugformat DWARF 2 @} @} -(@value{GDBP}) +(@value{GDBP}) @end smallexample @end table @@ -9767,7 +9952,7 @@ Some embedded operating systems, like Sun Chorus and VxWorks, can load relocatable files into an already running program; such systems typically make the requirements above easy to meet. However, it's important to recognize that many native systems use complex link -procedures (@code{.linkonce} section factoring and C++ constructor table +procedures (@code{.linkonce} section factoring and C@t{++} constructor table assembly, for example) that make the requirements difficult to meet. In general, one cannot assume that using @code{add-symbol-file} to read a relocatable object file's symbolic information will have the same effect @@ -10481,7 +10666,7 @@ specifies a fixed address. @cindex choosing target byte order @cindex target byte order -Some types of processors, such as the MIPS, PowerPC, and Hitachi SH, +Some types of processors, such as the MIPS, PowerPC, and Renesas 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 @@ -10533,9 +10718,7 @@ configuration of @value{GDBN}; use @code{help target} to list them. @node KOD @section Kernel Object Display - @cindex kernel object display -@cindex kernel object @cindex KOD Some targets support kernel object display. Using this facility, @@ -10544,6 +10727,7 @@ and can display information about operating system-level objects such as mutexes and other synchronization objects. Exactly which objects can be displayed is determined on a per-OS basis. +@kindex set os Use the @code{set os} command to set the operating system. This tells @value{GDBN} which kernel object display module to initialize: @@ -10551,11 +10735,17 @@ Use the @code{set os} command to set the operating system. This tells (@value{GDBP}) set os cisco @end smallexample +@kindex show os +The associated command @code{show os} displays the operating system +set with the @code{set os} command; if no operating system has been +set, @code{show os} will display an empty string @samp{""}. + If @code{set os} succeeds, @value{GDBN} will display some information about the operating system, and will create a new @code{info} command which can be used to query the target. The @code{info} command is named after the operating system: +@kindex info cisco @smallexample (@value{GDBP}) info cisco List of Cisco Kernel Objects @@ -10566,8 +10756,10 @@ any Any and all objects Further subcommands can be used to query about particular objects known by the kernel. -There is currently no way to determine whether a given operating system -is supported other than to try it. +There is currently no way to determine whether a given operating +system is supported other than to try setting it with @kbd{set os +@var{name}}, where @var{name} is the name of the operating system you +want to try. @node Remote Debugging @@ -10928,9 +11120,9 @@ For Motorola 680x0 architectures. @item sh-stub.c @cindex @file{sh-stub.c} -@cindex Hitachi +@cindex Renesas @cindex SH -For Hitachi SH architectures. +For Renesas SH architectures. @item sparc-stub.c @cindex @file{sparc-stub.c} @@ -11348,10 +11540,10 @@ accepts addresses which may belong to @emph{any} segment. For example, here's how to display the Page Table entry for the page where the variable @code{i} is stored: -@smallexample +@smallexample @exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} @exdent @code{Page Table entry for address 0x11a00d30:} -@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} +@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} @end smallexample @noindent @@ -11420,9 +11612,9 @@ This is a Cygwin specific alias of info shared. This command loads symbols from a dll similarly to add-sym command but without the need to specify a base address. -@kindex set new-console +@kindex set new-console @item set new-console @var{mode} -If @var{mode} is @code{on} the debuggee will +If @var{mode} is @code{on} the debuggee will be started in a new console on next start. If @var{mode} is @code{off}i, the debuggee will be started in the same console as the debugger. @@ -11449,17 +11641,17 @@ This boolean value adds debug output concerning events seen by the debugger. @kindex set debugexec @item set debugexec -This boolean value adds debug output concerning execute events +This boolean value adds debug output concerning execute events seen by the debugger. @kindex set debugexceptions @item set debugexceptions -This boolean value adds debug ouptut concerning exception events +This boolean value adds debug ouptut concerning exception events seen by the debugger. @kindex set debugmemory @item set debugmemory -This boolean value adds debug ouptut concerning memory events +This boolean value adds debug ouptut concerning memory events seen by the debugger. @kindex set shell @@ -11782,15 +11974,15 @@ configurations. @menu * ARM:: ARM -* H8/300:: Hitachi H8/300 -* H8/500:: Hitachi H8/500 -* M32R/D:: Mitsubishi M32R/D +* H8/300:: Renesas H8/300 +* H8/500:: Renesas H8/500 +* M32R/D:: Renesas M32R/D * M68K:: Motorola M68K * MIPS Embedded:: MIPS Embedded * OpenRISC 1000:: OpenRisc 1000 * PA:: HP PA Embedded * PowerPC: PowerPC -* SH:: Hitachi SH +* SH:: Renesas SH * Sparclet:: Tsqware Sparclet * Sparclite:: Fujitsu Sparclite * ST2000:: Tandem ST2000 @@ -11815,50 +12007,50 @@ ARM Demon monitor. @end table @node H8/300 -@subsection Hitachi H8/300 +@subsection Renesas H8/300 @table @code @kindex target hms@r{, with H8/300} @item target hms @var{dev} -A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. +A Renesas SH, H8/300, or H8/500 board, attached via serial line to your host. Use special commands @code{device} and @code{speed} to control the serial line and the communications speed used. @kindex target e7000@r{, with H8/300} @item target e7000 @var{dev} -E7000 emulator for Hitachi H8 and SH. +E7000 emulator for Renesas H8 and SH. @kindex target sh3@r{, with H8/300} @kindex target sh3e@r{, with H8/300} @item target sh3 @var{dev} @itemx target sh3e @var{dev} -Hitachi SH-3 and SH-3E target systems. +Renesas SH-3 and SH-3E target systems. @end table @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, the @code{load} command downloads your program to the Hitachi +@cindex download to Renesas SH +@cindex Renesas SH download +When you select remote debugging to a Renesas SH, H8/300, or H8/500 +board, the @code{load} command downloads your program to the Renesas board and also opens it as the current executable target for @value{GDBN} on your host (like the @code{file} command). @value{GDBN} needs to know these things to talk to your -Hitachi SH, H8/300, or H8/500: +Renesas 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 @value{GDBN} is configured specifically for the Hitachi SH, +for Renesas microprocessors, or @samp{target e7000}, the in-circuit +emulator for the Renesas SH and the Renesas 300H. (@samp{target hms} is +the default when @value{GDBN} is configured specifically for the Renesas SH, H8/300, or H8/500.) @item -what serial device connects your host to your Hitachi board (the first +what serial device connects your host to your Renesas board (the first serial device available on your host is the default). @item @@ -11866,24 +12058,24 @@ what speed to use over the serial device. @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. +* Renesas Boards:: Connecting to Renesas boards. +* Renesas ICE:: Using the E7000 In-Circuit Emulator. +* Renesas Special:: Special @value{GDBN} commands for Renesas micros. @end menu -@node Hitachi Boards -@subsubsection Connecting to Hitachi boards +@node Renesas Boards +@subsubsection Connecting to Renesas boards @c only for Unix hosts @kindex device -@cindex serial device, Hitachi micros +@cindex serial device, Renesas micros Use the special @code{@value{GDBN}} 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 +@cindex serial line speed, Renesas micros @code{@value{GDBN}} 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 @value{GDBN} with @@ -11891,7 +12083,7 @@ the DOS @code{mode} command (for instance, @w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{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 Unix host to debug your Renesas microprocessor programs. If you use a DOS host, @value{GDBN} depends on an auxiliary terminate-and-stay-resident program called @code{asynctsr} to communicate with the development board @@ -11901,7 +12093,7 @@ to set up the serial port on the DOS side. 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. +the Renesas 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 @@ -11934,7 +12126,7 @@ connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with the name of your program as the argument. @code{@value{GDBN}} 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 +cross-debugging to the Renesas 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 @@ -11984,12 +12176,12 @@ to detect program completion. In either case, @value{GDBN} sees the effect of a @sc{reset} on the development board as a ``normal exit'' of your program. -@node Hitachi ICE +@node Renesas ICE @subsubsection Using the E7000 in-circuit emulator -@kindex target e7000@r{, with Hitachi ICE} +@kindex target e7000@r{, with Renesas ICE} 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 +Renesas 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 @@ -12004,8 +12196,8 @@ 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 +@node Renesas Special +@subsubsection Special @value{GDBN} commands for Renesas micros Some @value{GDBN} commands are available only for the H8/300: @@ -12038,13 +12230,17 @@ memory}. The accepted values for @var{mod} are @code{small}, @end table @node M32R/D -@subsection Mitsubishi M32R/D +@subsection Renesas M32R/D @table @code @kindex target m32r @item target m32r @var{dev} -Mitsubishi M32R/D ROM monitor. +Renesas M32R/D ROM monitor. + +@kindex target m32rsdi +@item target m32rsdi @var{dev} +Renesas M32R SDI server, connected via parallel port to the board. @end table @@ -12391,25 +12587,25 @@ W89K monitor, running on a Winbond HPPA board. @end table @node SH -@subsection Hitachi SH +@subsection Renesas SH @table @code -@kindex target hms@r{, with Hitachi SH} +@kindex target hms@r{, with Renesas SH} @item target hms @var{dev} -A Hitachi SH board attached via serial line to your host. Use special +A Renesas SH board attached via serial line to your host. Use special commands @code{device} and @code{speed} to control the serial line and the communications speed used. -@kindex target e7000@r{, with Hitachi SH} +@kindex target e7000@r{, with Renesas SH} @item target e7000 @var{dev} -E7000 emulator for Hitachi SH. +E7000 emulator for Renesas SH. @kindex target sh3@r{, with SH} @kindex target sh3e@r{, with SH} @item target sh3 @var{dev} @item target sh3e @var{dev} -Hitachi SH-3 and SH-3E target systems. +Renesas SH-3 and SH-3E target systems. @end table @@ -13028,7 +13224,7 @@ current ABI. @kindex show osabi One @value{GDBN} configuration can debug binaries for multiple operating -system targets, either via remote debugging or native emulation. +system targets, either via remote debugging or native emulation. @value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use, but you can override its conclusion using the @code{set osabi} command. One example where this is useful is in debugging of binaries which use @@ -13238,7 +13434,9 @@ info. @item set debug target Turns on or off display of @value{GDBN} target debugging info. This info includes what is going on at the target level of GDB, as it happens. The -default is off. +default is 0. Set it to 1 to track events, and to 2 to also track the +value of large memory transfers. Changes to this flag do not take effect +until the next time you connect to a target or use the @code{run} command. @kindex show debug target @item show debug target Displays the current state of displaying @value{GDBN} target debugging @@ -13422,7 +13620,7 @@ end @end smallexample As a further example, to hook at the begining and end of the @code{echo} -command, and to add extra text to the beginning and end of the message, +command, and to add extra text to the beginning and end of the message, you could define: @smallexample @@ -13933,7 +14131,7 @@ key bindings such as @key{C-p}, @key{C-n}, @key{C-b} and @key{C-f}. The TUI provides a @emph{SingleKey} mode in which it installs a particular key binding in the readline keymaps to connect single keys to -some gdb commands. +some gdb commands. @table @kbd @kindex c @r{(SingleKey TUI key)} @@ -14239,7 +14437,7 @@ 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. - + The description given here is for GNU Emacs version 21.3 and a more detailed description of its interaction with @value{GDBN} is given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}). @@ -15879,17 +16077,17 @@ The corresponding @value{GDBN} command is @samp{cd}. Add directories @var{pathdir} to beginning of search path for source files. If the @samp{-r} option is used, the search path is reset to the default -search path. If directories @var{pathdir} are supplied in addition to the +search path. If directories @var{pathdir} are supplied in addition to the @samp{-r} option, the search path is first reset and then addition occurs as normal. -Multiple directories may be specified, separated by blanks. Specifying +Multiple directories may be specified, separated by blanks. Specifying multiple directories in a single command results in the directories added to the beginning of the search path in the same order they were presented in the command. If blanks are needed as part of a directory name, double-quotes should be used around the name. In the command output, the path will show up separated -by the system directory-separator character. The directory-seperator +by the system directory-separator character. The directory-seperator character must not be used in any directory name. If no directories are specified, the current search path is displayed. @@ -15928,18 +16126,18 @@ The corresponding @value{GDBN} command is @samp{dir}. Add directories @var{pathdir} to beginning of search path for object files. If the @samp{-r} option is used, the search path is reset to the original -search path that existed at gdb start-up. If directories @var{pathdir} are -supplied in addition to the +search path that existed at gdb start-up. If directories @var{pathdir} are +supplied in addition to the @samp{-r} option, the search path is first reset and then addition occurs as normal. -Multiple directories may be specified, separated by blanks. Specifying +Multiple directories may be specified, separated by blanks. Specifying multiple directories in a single command results in the directories added to the beginning of the search path in the same order they were presented in the command. If blanks are needed as part of a directory name, double-quotes should be used around the name. In the command output, the path will show up separated -by the system directory-separator character. The directory-seperator +by the system directory-separator character. The directory-seperator character must not be used in any directory name. If no directories are specified, the current path is displayed. @@ -15953,7 +16151,7 @@ The corresponding @value{GDBN} command is @samp{path}. @smallexample (@value{GDBP}) --environment-path +-environment-path ^done,path="/usr/bin" (@value{GDBP}) -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin @@ -16559,7 +16757,7 @@ N.A. -file-list-exec-source-file @end smallexample -List the line number, the current source file, and the absolute path +List the line number, the current source file, and the absolute path to the current source file for the current executable. @subsubheading @value{GDBN} Command @@ -16772,7 +16970,7 @@ information when you start an interactive session. ~Type "show copying" to see the conditions. ~There is absolutely no warranty for GDB. Type "show warranty" for ~ details. -~This GDB was configured as +~This GDB was configured as "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". ^done (@value{GDBP}) @@ -17103,8 +17301,14 @@ Show a single frame: @end smallexample Display the local variable names for the current frame. With an -argument of 0 prints only the names of the variables, with argument of 1 -prints also their values. +argument of 0 or @code{--no-values}, prints only the names of the variables. +With argument of 1 or @code{--all-values}, prints also their values. With +argument of 2 or @code{--simple-values}, prints the name, type and value for +simple data types and the name and type for arrays, structures and +unions. In this last case, the idea is that the user can see the +value of simple data types immediately and he can create variable +objects for other data types if he wishes to explore their values in +more detail. @subsubheading @value{GDBN} Command @@ -17117,9 +17321,12 @@ prints also their values. -stack-list-locals 0 ^done,locals=[name="A",name="B",name="C"] (@value{GDBP}) --stack-list-locals 1 +-stack-list-locals --all-values ^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, - @{name="C",value="3"@}] + @{name="C",value="@{1, 2, 3@}"@}] +-stack-list-locals --simple-values +^done,locals=[@{name="A",type="int",value="1"@}, + @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}] (@value{GDBP}) @end smallexample @@ -17226,7 +17433,7 @@ Show the core addresses of the code for a source line. @subsubheading @value{GDBN} Command -The corresponding @value{GDBN} comamnd is @samp{info line}. +The corresponding @value{GDBN} command is @samp{info line}. @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. @subsubheading Example @@ -18063,14 +18270,26 @@ Returns the number of children of a variable object @var{name}: @subsubheading Synopsis @smallexample - -var-list-children @var{name} + -var-list-children [@var{print-values}] @var{name} @end smallexample -Returns a list of the children of the specified variable object: +Returns a list of the children of the specified variable object. With +just the variable object name as an argument or with an optional +preceding argument of 0 or @code{--no-values}, prints only the names of the +variables. With an optional preceding argument of 1 or @code{--all-values}, +also prints their values. + +@subsubheading Example @smallexample +(@value{GDBP}) + -var-list-children n numchild=@var{n},children=[@{name=@var{name}, numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] +(@value{GDBP}) + -var-list-children --all-values n + numchild=@var{n},children=[@{name=@var{name}, + numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}] @end smallexample @@ -18159,7 +18378,7 @@ before the value of a child variable can be evaluated. Assigns the value of @var{expression} to the variable object specified by @var{name}. The object must be @samp{editable}. If the variable's -value is altered by the assign, the variable will show up in any +value is altered by the assign, the variable will show up in any subsequent @code{-var-update} list. @subsubheading Example @@ -18259,12 +18478,12 @@ for details. This GDB was configured as "i386-pc-linux-gnu" ^Z^Zpre-prompt -(gdb) +(gdb) ^Z^Zprompt @kbd{quit} ^Z^Zpost-prompt -$ +$ @end smallexample Here @samp{quit} is input to @value{GDBN}; the rest is output from @@ -18414,13 +18633,13 @@ deleted a breakpoint. @findex starting @findex stopping When the program starts executing due to a @value{GDBN} command such as -@code{step} or @code{continue}, +@code{step} or @code{continue}, @smallexample ^Z^Zstarting @end smallexample -is output. When the program stops, +is output. When the program stops, @smallexample ^Z^Zstopped @@ -19177,7 +19396,7 @@ A problem internal to GDB has been detected. Further debugging may prove unreliable. Quit this debugging session? (y or n) @kbd{n} Create a core file? (y or n) @kbd{n} -(gdb) +(gdb) @end smallexample Takes an optional parameter that is used as the text of the error or @@ -19200,7 +19419,7 @@ The program being debugged stopped while in a function called from GDB. 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@} call_lo=0x01014000 call_hi=0x01014001 -(gdb) +(gdb) @end smallexample Takes an optional file parameter. @@ -19232,14 +19451,14 @@ Takes an optional file parameter. @smallexample (gdb) @kbd{maint print reggroups} - Group Type - general user - float user - all user - vector user - system user - save internal - restore internal + Group Type + general user + float user + all user + vector user + system user + save internal + restore internal @end smallexample @kindex maint set profile @@ -19258,7 +19477,7 @@ if you use profiling, @value{GDBN} will overwrite the profiling log file data in a @file{gmon.out} file, be sure to move it to a safe location. Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be -compiled with the @samp{-pg} compiler option. +compiled with the @samp{-pg} compiler option. @end table @@ -19357,10 +19576,6 @@ where @code{n >=3} (which is where rle starts to win). The printable characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric value greater than 126 should not be used. -Some remote systems have used a different run-length encoding mechanism -loosely refered to as the cisco encoding. Following the @samp{*} -character are two hex digits that indicate the size of the packet. - So: @smallexample "@code{0* }" @@ -19376,8 +19591,8 @@ For any @var{command} not supported by the stub, an empty response protocol. A newer @value{GDBN} can tell if a packet is supported based on that response. -A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, -@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are +A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, +@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are optional. @node Packets @@ -19517,9 +19732,9 @@ Reply: Each byte of register data is described by two hex digits. The bytes with the register are transmitted in target byte order. The size of each register and their position within the @samp{g} @var{packet} are -determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} -and @var{REGISTER_NAME} macros. The specification of several standard -@code{g} packets is specified below. +determined by the @value{GDBN} internal macros +@var{DEPRECATED_REGISTER_RAW_SIZE} and @var{REGISTER_NAME} macros. The +specification of several standard @code{g} packets is specified below. @item E@var{NN} for an error. @end table @@ -19542,7 +19757,7 @@ for an error Reserved for future use. -@item @code{H}@var{c}@var{t@dots{}} --- set thread +@item @code{H}@var{c}@var{t@dots{}} --- set thread @cindex @code{H} packet Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, @@ -19753,7 +19968,7 @@ Like @samp{C} but step not continue. Reply: @xref{Stop Reply Packets}, for the reply specifications. -@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search +@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search @cindex @code{t} packet Search backwards starting at address @var{addr} for a match with pattern @@ -19781,9 +19996,51 @@ Reserved for future use. Reserved for future use. -@item @code{v} --- reserved +@item @code{v} --- verbose packet prefix -Reserved for future use. +Packets starting with @code{v} are identified by a multi-letter name, +up to the first @code{;} or @code{?} (or the end of the packet). + +@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume +@cindex @code{vCont} packet + +Resume the inferior. Different actions may be specified for each thread. +If an action is specified with no @var{tid}, then it is applied to any +threads that don't have a specific action specified; if no default action is +specified then other threads should remain stopped. Specifying multiple +default actions is an error; specifying no actions is also an error. +Thread IDs are specified in hexadecimal. Currently supported actions are: + +@table @code +@item c +Continue. +@item C@var{sig} +Continue with signal @var{sig}. @var{sig} should be two hex digits. +@item s +Step. +@item S@var{sig} +Step with signal @var{sig}. @var{sig} should be two hex digits. +@end table + +The optional @var{addr} argument normally associated with these packets is +not supported in @code{vCont}. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item @code{vCont?} --- extended resume query +@cindex @code{vCont?} packet + +Query support for the @code{vCont} packet. + +Reply: +@table @samp +@item @code{vCont}[;@var{action}]... +The @code{vCont} packet is supported. Each @var{action} is a supported +command in the @code{vCont} packet. +@item +The @code{vCont} packet is not supported. +@end table @item @code{V} --- reserved @@ -19971,12 +20228,13 @@ conventions is used. @var{AA} = two hex digit signal number; @var{n...} = register number (hex), @var{r...} = target byte ordered register contents, size defined -by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} = -thread process ID, this is a hex integer; @var{n...} = (@samp{watch} | -@samp{rwatch} | @samp{awatch}, @var{r...} = data address, this is a hex -integer; @var{n...} = other string not starting with valid hex digit. -@value{GDBN} should ignore this @var{n...}, @var{r...} pair and go on -to the next. This way we can extend the protocol. +by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, +@var{r...} = thread process ID, this is a hex integer; @var{n...} = +(@samp{watch} | @samp{rwatch} | @samp{awatch}, @var{r...} = data +address, this is a hex integer; @var{n...} = other string not starting +with valid hex digit. @value{GDBN} should ignore this @var{n...}, +@var{r...} pair and go on to the next. This way we can extend the +protocol. @item W@var{AA} @@ -19987,15 +20245,6 @@ applicable to certain targets. The process terminated with signal @var{AA}. -@item N@var{AA};@var{t@dots{}};@var{d@dots{}};@var{b@dots{}} @strong{(obsolete)} - -@var{AA} = signal number; @var{t@dots{}} = address of symbol -@code{_start}; @var{d@dots{}} = base of data section; @var{b@dots{}} = -base of bss section. @emph{Note: only used by Cisco Systems targets. -The difference between this reply and the @samp{qOffsets} query is that -the @samp{N} packet may arrive spontaneously whereas the @samp{qOffsets} -is a query initiated by the host debugger.} - @item O@var{XX@dots{}} @var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at @@ -20202,6 +20451,82 @@ encoded). @value{GDBN} will continue to supply the values of symbols (if available), until the target ceases to request them. @end table +@item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data + +Read uninterpreted bytes from the target's special data area +identified by the keyword @code{object}. +Request @var{length} bytes starting at @var{offset} bytes into the data. +The content and encoding of @var{annex} is specific to the object; +it can supply additional details about what data to access. + +Here are the specific requests of this form defined so far. +All @samp{@code{qPart}:@var{object}:@code{read}:@dots{}} +requests use the same reply formats, listed below. + +@table @asis +@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length} +Access the target's @dfn{auxiliary vector}. @xref{Auxiliary Vector}. +Note @var{annex} must be empty. +@end table + +Reply: +@table @asis +@item @code{OK} +The @var{offset} in the request is at the end of the data. +There is no more data to be read. + +@item @var{XX@dots{}} +Hex encoded data bytes read. +This may be fewer bytes than the @var{length} in the request. + +@item @code{E00} +The request was malformed, or @var{annex} was invalid. + +@item @code{E}@var{nn} +The offset was invalid, or there was an error encountered reading the data. +@var{nn} is a hex-encoded @code{errno} value. + +@item @code{""} (empty) +An empty reply indicates the @var{object} or @var{annex} string was not +recognized by the stub. +@end table + +@item @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}} + +Write uninterpreted bytes into the target's special data area +identified by the keyword @code{object}, +starting at @var{offset} bytes into the data. +@var{data@dots{}} is the hex-encoded data to be written. +The content and encoding of @var{annex} is specific to the object; +it can supply additional details about what data to access. + +No requests of this form are presently in use. This specification +serves as a placeholder to document the common format that new +specific request specifications ought to use. + +Reply: +@table @asis +@item @var{nn} +@var{nn} (hex encoded) is the number of bytes written. +This may be fewer bytes than supplied in the request. + +@item @code{E00} +The request was malformed, or @var{annex} was invalid. + +@item @code{E}@var{nn} +The offset was invalid, or there was an error encountered writing the data. +@var{nn} is a hex-encoded @code{errno} value. + +@item @code{""} (empty) +An empty reply indicates the @var{object} or @var{annex} string was not +recognized by the stub, or that the object does not support writing. +@end table + +@item @code{qPart}:@var{object}:@var{operation}:@dots{} +Requests of this form may be added in the future. When a stub does +not recognize the @var{object} keyword, or its support for +@var{object} does not recognize the @var{operation} keyword, +the stub must respond with an empty packet. @end table @node Register Packet Format @@ -20269,8 +20594,8 @@ Example sequence of a target being stepped by a single instruction: @menu * File-I/O Overview:: * Protocol basics:: -* The `F' request packet:: -* The `F' reply packet:: +* The F request packet:: +* The F reply packet:: * Memory transfer:: * The Ctrl-C message:: * Console I/O:: @@ -20332,20 +20657,20 @@ system are not supported by this protocol. The File-I/O protocol uses the @code{F} packet, as request as well as as reply packet. Since a File-I/O system call can only occur when -@value{GDBN} is waiting for the continuing or stepping target, the +@value{GDBN} is waiting for the continuing or stepping target, the File-I/O request is a reply that @value{GDBN} has to expect as a result of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. This @code{F} packet contains all information needed to allow @value{GDBN} to call the appropriate host system call: @itemize @bullet -@item +@item A unique identifier for the requested system call. @item All parameters to the system call. Pointers are given as addresses in the target memory address space. Pointers to strings are given as -pointer/length pair. Numerical values are given as they are. +pointer/length pair. Numerical values are given as they are. Numerical control values are given in a protocol specific representation. @end itemize @@ -20353,7 +20678,7 @@ Numerical control values are given in a protocol specific representation. At that point @value{GDBN} has to perform the following actions. @itemize @bullet -@item +@item If parameter pointer values are given, which point to data needed as input to a system call, @value{GDBN} requests this data from the target with a standard @code{m} packet request. This additional communication has to be @@ -20397,7 +20722,7 @@ Return value. After having done the needed type and value coercion, the target continues the latest continue or step action. -@node The `F' request packet +@node The F request packet @subsection The @code{F} request packet @cindex file-i/o request packet @cindex @code{F} request packet @@ -20415,7 +20740,7 @@ This is just the name of the function. @var{parameter@dots{}} are the parameters to the system call. -@end table +@end table Parameters are hexadecimal integer values, either the real values in case of scalar datatypes, as pointers to target buffer space in case of compound @@ -20424,7 +20749,7 @@ of string parameters. These are appended to the call-id, each separated from its predecessor by a comma. All values are transmitted in ASCII string representation, pointer/length pairs separated by a slash. -@node The `F' reply packet +@node The F reply packet @subsection The @code{F} reply packet @cindex file-i/o reply packet @cindex @code{F} reply packet @@ -20482,7 +20807,7 @@ reply packet. In this case the target should behave, as if it had gotten a break message. The meaning for the target is ``system call interupted by @code{SIGINT}''. Consequentially, the target should actually stop (as with a break message) and return to @value{GDBN} with a @code{T02} -packet. In this case, it's important for the target to know, in which +packet. In this case, it's important for the target to know, in which state the system call was interrupted. Since this action is by design not an atomic operation, we have to differ between two cases: @@ -20567,7 +20892,7 @@ in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists entirely of the exit status of the called command. Due to security concerns, the @code{system} call is refused to be called -by @value{GDBN} by default. The user has to allow this call explicitly by +by @value{GDBN} by default. The user has to allow this call explicitly by entering @table @samp @@ -20616,7 +20941,7 @@ The current setting is shown by typing int open(const char *pathname, int flags); int open(const char *pathname, int flags, mode_t mode); -@exdent Request: +@exdent Request: Fopen,pathptr/len,flags,mode @end smallexample @@ -20624,30 +20949,30 @@ Fopen,pathptr/len,flags,mode @code{flags} is the bitwise or of the following values: @table @code -@item O_CREAT +@item O_CREAT If the file does not exist it will be created. The host rules apply as far as file ownership and time stamps are concerned. -@item O_EXCL +@item O_EXCL When used with O_CREAT, if the file already exists it is an error and open() fails. -@item O_TRUNC +@item O_TRUNC If the file already exists and the open mode allows writing (O_RDWR or O_WRONLY is given) it will be truncated to length 0. -@item O_APPEND +@item O_APPEND The file is opened in append mode. -@item O_RDONLY +@item O_RDONLY The file is opened for reading only. -@item O_WRONLY +@item O_WRONLY The file is opened for writing only. -@item O_RDWR +@item O_RDWR The file is opened for reading and writing. @noindent @@ -20659,22 +20984,22 @@ Each other bit is silently ignored. @code{mode} is the bitwise or of the following values: @table @code -@item S_IRUSR +@item S_IRUSR User has read permission. -@item S_IWUSR +@item S_IWUSR User has write permission. -@item S_IRGRP +@item S_IRGRP Group has read permission. -@item S_IWGRP +@item S_IWGRP Group has write permission. -@item S_IROTH +@item S_IROTH Others have read permission. -@item S_IWOTH +@item S_IWOTH Others have write permission. @noindent @@ -20691,42 +21016,42 @@ occured. @end smallexample @table @code -@item EEXIST +@item EEXIST pathname already exists and O_CREAT and O_EXCL were used. -@item EISDIR +@item EISDIR pathname refers to a directory. -@item EACCES +@item EACCES The requested access is not allowed. @item ENAMETOOLONG pathname was too long. -@item ENOENT +@item ENOENT A directory component in pathname does not exist. -@item ENODEV +@item ENODEV pathname refers to a device, pipe, named pipe or socket. -@item EROFS +@item EROFS pathname refers to a file on a read-only filesystem and write access was requested. -@item EFAULT +@item EFAULT pathname is an invalid pointer value. -@item ENOSPC +@item ENOSPC No space on device to create the file. -@item EMFILE +@item EMFILE The process already has the maximum number of files open. -@item ENFILE +@item ENFILE The limit on the total number of files open on the system has been reached. -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -20735,10 +21060,10 @@ The call was interrupted by the user. @cindex close, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: int close(int fd); -@exdent Request: +@exdent Request: Fclose,fd @exdent Return value: @@ -20748,10 +21073,10 @@ close returns zero on success, or -1 if an error occurred. @end smallexample @table @code -@item EBADF +@item EBADF fd isn't a valid open file descriptor. -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -20760,29 +21085,29 @@ The call was interrupted by the user. @cindex read, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: int read(int fd, void *buf, unsigned int count); -@exdent Request: +@exdent Request: Fread,fd,bufptr,count @exdent Return value: On success, the number of bytes read is returned. Zero indicates end of file. If count is zero, read -returns zero as well. On error, -1 is returned. +returns zero as well. On error, -1 is returned. @exdent Errors: @end smallexample @table @code -@item EBADF +@item EBADF fd is not a valid file descriptor or is not open for reading. -@item EFAULT +@item EFAULT buf is an invalid pointer value. -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -20791,10 +21116,10 @@ The call was interrupted by the user. @cindex write, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: int write(int fd, const void *buf, unsigned int count); -@exdent Request: +@exdent Request: Fwrite,fd,bufptr,count @exdent Return value: @@ -20806,21 +21131,21 @@ is returned. @end smallexample @table @code -@item EBADF +@item EBADF fd is not a valid file descriptor or is not open for writing. -@item EFAULT +@item EFAULT buf is an invalid pointer value. -@item EFBIG +@item EFBIG An attempt was made to write a file that exceeds the host specific maximum file size allowed. -@item ENOSPC +@item ENOSPC No space on device to write the data. -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -20829,24 +21154,24 @@ The call was interrupted by the user. @cindex lseek, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: long lseek (int fd, long offset, int flag); -@exdent Request: +@exdent Request: Flseek,fd,offset,flag @end smallexample @code{flag} is one of: @table @code -@item SEEK_SET +@item SEEK_SET The offset is set to offset bytes. -@item SEEK_CUR +@item SEEK_CUR The offset is set to its current location plus offset bytes. -@item SEEK_END +@item SEEK_END The offset is set to the size of the file plus offset bytes. @end table @@ -20861,16 +21186,16 @@ value of -1 is returned. @end smallexample @table @code -@item EBADF +@item EBADF fd is not a valid open file descriptor. -@item ESPIPE +@item ESPIPE fd is associated with the @value{GDBN} console. -@item EINVAL +@item EINVAL flag is not a proper value. -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -20879,10 +21204,10 @@ The call was interrupted by the user. @cindex rename, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: int rename(const char *oldpath, const char *newpath); -@exdent Request: +@exdent Request: Frename,oldpathptr/len,newpathptr/len @exdent Return value: @@ -20892,47 +21217,47 @@ On success, zero is returned. On error, -1 is returned. @end smallexample @table @code -@item EISDIR +@item EISDIR newpath is an existing directory, but oldpath is not a directory. -@item EEXIST +@item EEXIST newpath is a non-empty directory. -@item EBUSY +@item EBUSY oldpath or newpath is a directory that is in use by some process. -@item EINVAL +@item EINVAL An attempt was made to make a directory a subdirectory of itself. -@item ENOTDIR +@item ENOTDIR A component used as a directory in oldpath or new path is not a directory. Or oldpath is a directory and newpath exists but is not a directory. -@item EFAULT +@item EFAULT oldpathptr or newpathptr are invalid pointer values. -@item EACCES +@item EACCES No access to the file or the path of the file. @item ENAMETOOLONG - + oldpath or newpath was too long. -@item ENOENT +@item ENOENT A directory component in oldpath or newpath does not exist. -@item EROFS +@item EROFS The file is on a read-only filesystem. -@item ENOSPC +@item ENOSPC The device containing the file has no room for the new directory entry. -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -20941,10 +21266,10 @@ The call was interrupted by the user. @cindex unlink, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: int unlink(const char *pathname); -@exdent Request: +@exdent Request: Funlink,pathnameptr/len @exdent Return value: @@ -20954,32 +21279,32 @@ On success, zero is returned. On error, -1 is returned. @end smallexample @table @code -@item EACCES +@item EACCES No access to the file or the path of the file. -@item EPERM +@item EPERM The system does not allow unlinking of directories. -@item EBUSY +@item EBUSY The file pathname cannot be unlinked because it's being used by another process. -@item EFAULT +@item EFAULT pathnameptr is an invalid pointer value. @item ENAMETOOLONG pathname was too long. -@item ENOENT +@item ENOENT A directory component in pathname does not exist. -@item ENOTDIR +@item ENOTDIR A component of the path is not a directory. -@item EROFS +@item EROFS The file is on a read-only filesystem. -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -20989,11 +21314,11 @@ The call was interrupted by the user. @cindex stat, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: int stat(const char *pathname, struct stat *buf); int fstat(int fd, struct stat *buf); -@exdent Request: +@exdent Request: Fstat,pathnameptr/len,bufptr Ffstat,fd,bufptr @@ -21004,26 +21329,26 @@ On success, zero is returned. On error, -1 is returned. @end smallexample @table @code -@item EBADF +@item EBADF fd is not a valid open file. -@item ENOENT +@item ENOENT A directory component in pathname does not exist or the path is an empty string. -@item ENOTDIR +@item ENOTDIR A component of the path is not a directory. -@item EFAULT +@item EFAULT pathnameptr is an invalid pointer value. -@item EACCES +@item EACCES No access to the file or the path of the file. @item ENAMETOOLONG pathname was too long. -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -21032,10 +21357,10 @@ The call was interrupted by the user. @cindex gettimeofday, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: int gettimeofday(struct timeval *tv, void *tz); -@exdent Request: +@exdent Request: Fgettimeofday,tvptr,tzptr @exdent Return value: @@ -21045,10 +21370,10 @@ On success, 0 is returned, -1 otherwise. @end smallexample @table @code -@item EINVAL +@item EINVAL tz is a non-NULL pointer. -@item EFAULT +@item EFAULT tvptr and/or tzptr is an invalid pointer value. @end table @@ -21057,10 +21382,10 @@ tvptr and/or tzptr is an invalid pointer value. @cindex isatty, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: int isatty(int fd); -@exdent Request: +@exdent Request: Fisatty,fd @exdent Return value: @@ -21070,7 +21395,7 @@ Returns 1 if fd refers to the @value{GDBN} console, 0 otherwise. @end smallexample @table @code -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -21079,10 +21404,10 @@ The call was interrupted by the user. @cindex system, file-i/o system call @smallexample -@exdent Synopsis: +@exdent Synopsis: int system(const char *command); -@exdent Request: +@exdent Request: Fsystem,commandptr/len @exdent Return value: @@ -21096,7 +21421,7 @@ In case /bin/sh could not be executed, 127 is returned. @end smallexample @table @code -@item EINTR +@item EINTR The call was interrupted by the user. @end table @@ -21124,8 +21449,8 @@ int@r{,} unsigned int@r{,} long@r{,} unsigned long@r{,} mode_t @r{and} time_t @code{Int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are implemented as 32 bit values in this protocol. -@code{Long} and @code{unsigned long} are implemented as 64 bit types. - +@code{Long} and @code{unsigned long} are implemented as 64 bit types. + @xref{Limits}, for corresponding MIN and MAX values (similar to those in @file{limits.h}) to allow range checking on host and target. @@ -21233,7 +21558,7 @@ The buffer of type struct timeval used by the target and @value{GDBN} is defined as follows: @smallexample -struct timeval @{ +struct timeval @{ time_t tv_sec; /* second */ long tv_usec; /* microsecond */ @}; @@ -21409,7 +21734,9 @@ host is called: @include gpl.texi +@raisesections @include fdl.texi +@lowersections @node Index @unnumbered Index diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 3ed887b36df..a474015783b 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -8,7 +8,7 @@ @ifinfo This file documents the internals of the GNU debugger @value{GDBN}. -Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003 +Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc. Contributed by Cygnus Solutions. Written by John Gilmore. Second Edition by Stan Shebs. @@ -38,7 +38,7 @@ Free Documentation License''. @page @tex \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 1.161 $} % For use in headers, footers too +\xdef\manvers{\$Revision: 1.161.2.1 $} % For use in headers, footers too {\parskip=0pt \hfill Cygnus Solutions\par \hfill \manvers\par @@ -48,7 +48,7 @@ Free Documentation License''. @vskip 0pt plus 1filll Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001, - 2002, 2003 Free Software Foundation, Inc. + 2002, 2003, 2004 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or @@ -480,13 +480,6 @@ two macros can use them for their internal purposes. If the inferior has some watchpoint that triggered, return the address associated with that watchpoint. Otherwise, return zero. -@findex DECR_PC_AFTER_HW_BREAK -@item DECR_PC_AFTER_HW_BREAK -If defined, @value{GDBN} decrements the program counter by the value -of @code{DECR_PC_AFTER_HW_BREAK} after a hardware break-point. This -overrides the value of @code{DECR_PC_AFTER_BREAK} when a breakpoint -that breaks is a hardware-assisted breakpoint. - @findex HAVE_STEPPABLE_WATCHPOINT @item HAVE_STEPPABLE_WATCHPOINT If defined to a non-zero value, it is not necessary to disable a @@ -2245,12 +2238,6 @@ This macro is used as the argument to @code{lseek} (or, most commonly, @code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead, which is the POSIX equivalent. -@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 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 @@ -2264,37 +2251,6 @@ 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 -@findex mmalloc -@value{GDBN} 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 @code{mmalloc} library. This -define is set when you configure with @samp{--with-mmalloc}. - -@item NO_MMCHECK -@findex 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 @code{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 @code{mmalloc}, but must define -@code{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, @value{GDBN} will issue a -warning. This is currently defined if you configure using -@samp{--with-mmalloc}. - @item NO_SIGINTERRUPT @findex siginterrupt Define this to indicate that @code{siginterrupt} is not available. @@ -2505,7 +2461,7 @@ However, architectures with smaller word sizes are often cramped for address space, so they may choose a pointer representation that breaks this identity, and allows a larger code address space. -For example, the Mitsubishi D10V is a 16-bit VLIW processor whose +For example, the Renesas D10V is a 16-bit VLIW processor whose instructions are 32 bits long@footnote{Some D10V instructions are actually pairs of 16-bit sub-instructions. However, since you can't jump into the middle of such a pair, code addresses can only refer to @@ -2766,19 +2722,19 @@ You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register unless this macro returns a non-zero value for that register. @end deftypefn -@deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg}) +@deftypefn {Target Macro} int DEPRECATED_REGISTER_RAW_SIZE (int @var{reg}) The size of register number @var{reg}'s raw value. This is the number of bytes the register will occupy in @code{registers}, or in a @value{GDBN} remote protocol packet. @end deftypefn -@deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg}) +@deftypefn {Target Macro} int DEPRECATED_REGISTER_VIRTUAL_SIZE (int @var{reg}) The size of register number @var{reg}'s value, in its virtual format. This is the size a @code{struct value}'s buffer will have, holding that register's value. @end deftypefn -@deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg}) +@deftypefn {Target Macro} struct type *DEPRECATED_REGISTER_VIRTUAL_TYPE (int @var{reg}) This is the type of the virtual representation of register number @var{reg}. Note that there is no need for a macro giving a type for the register's raw form; once the register's value has been obtained, @value{GDBN} @@ -2787,7 +2743,7 @@ always uses the virtual form. @deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to}) Convert the value of register number @var{reg} to @var{type}, which -should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer +should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer at @var{from} holds the register's value in raw format; the macro should convert the value to virtual format, and place it at @var{to}. @@ -2802,7 +2758,7 @@ value. @deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to}) Convert the value of register number @var{reg} to @var{type}, which -should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer +should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer at @var{from} holds the register's value in raw format; the macro should convert the value to virtual format, and place it at @var{to}. @@ -3052,6 +3008,39 @@ custom breakpoint insertion and removal routines if @code{BREAKPOINT_FROM_PC} needs to read the target's memory for some reason. +@item ADJUST_BREAKPOINT_ADDRESS (@var{address}) +@findex ADJUST_BREAKPOINT_ADDRESS +@cindex breakpoint address adjusted +Given an address at which a breakpoint is desired, return a breakpoint +address adjusted to account for architectural constraints on +breakpoint placement. This method is not needed by most targets. + +The FR-V target (see @file{frv-tdep.c}) requires this method. +The FR-V is a VLIW architecture in which a number of RISC-like +instructions are grouped (packed) together into an aggregate +instruction or instruction bundle. When the processor executes +one of these bundles, the component instructions are executed +in parallel. + +In the course of optimization, the compiler may group instructions +from distinct source statements into the same bundle. The line number +information associated with one of the latter statements will likely +refer to some instruction other than the first one in the bundle. So, +if the user attempts to place a breakpoint on one of these latter +statements, @value{GDBN} must be careful to @emph{not} place the break +instruction on any instruction other than the first one in the bundle. +(Remember though that the instructions within a bundle execute +in parallel, so the @emph{first} instruction is the instruction +at the lowest address and has nothing to do with execution order.) + +The FR-V's @code{ADJUST_BREAKPOINT_ADDRESS} method will adjust a +breakpoint's address by scanning backwards for the beginning of +the bundle, returning the address of the bundle. + +Since the adjustment of a breakpoint may significantly alter a user's +expectation, @value{GDBN} prints a warning when an adjusted breakpoint +is initially set and each time that that breakpoint is hit. + @item DEPRECATED_CALL_DUMMY_WORDS @findex DEPRECATED_CALL_DUMMY_WORDS Pointer to an array of @code{LONGEST} words of data containing @@ -3088,12 +3077,6 @@ See the file @file{inferior.h}. This method has been replaced by @code{push_dummy_code} (@pxref{push_dummy_code}). -@item DEPRECATED_CALL_DUMMY_STACK_ADJUST -@findex DEPRECATED_CALL_DUMMY_STACK_ADJUST -Stack adjustment needed when performing an inferior function call. This -function is no longer needed. @xref{push_dummy_call}, which can handle -all alignment directly. - @item CANNOT_FETCH_REGISTER (@var{regno}) @findex CANNOT_FETCH_REGISTER A C expression that should be nonzero if @var{regno} cannot be fetched @@ -3128,10 +3111,6 @@ 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 @code{BREAKPOINT}, though not always. For most targets this value will be 0. -@item DECR_PC_AFTER_HW_BREAK -@findex DECR_PC_AFTER_HW_BREAK -Similarly, for hardware breakpoints. - @item DISABLE_UNSETTABLE_BREAK (@var{addr}) @findex DISABLE_UNSETTABLE_BREAK If defined, this should evaluate to 1 if @var{addr} is in a shared @@ -3186,17 +3165,21 @@ 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(@var{regbuf}) -@findex EXTRACT_STRUCT_VALUE_ADDRESS +This method has been deprecated in favour of @code{gdbarch_return_value} +(@pxref{gdbarch_return_value}). + +@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf}) +@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS +@anchor{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS} When defined, extract from the array @var{regbuf} (containing the raw register state) the @code{CORE_ADDR} at which a function should return its structure value. -If not defined, @code{EXTRACT_RETURN_VALUE} is used. +@xref{gdbarch_return_value}. -@item EXTRACT_STRUCT_VALUE_ADDRESS_P() -@findex EXTRACT_STRUCT_VALUE_ADDRESS_P -Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}. +@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P() +@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P +Predicate for @code{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}. @item DEPRECATED_FP_REGNUM @findex DEPRECATED_FP_REGNUM @@ -3206,8 +3189,8 @@ macro to be the number (greater than or equal to zero) of that register. This should only need to be defined if @code{DEPRECATED_TARGET_READ_FP} is not defined. -@item FRAMELESS_FUNCTION_INVOCATION(@var{fi}) -@findex FRAMELESS_FUNCTION_INVOCATION +@item DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(@var{fi}) +@findex DEPRECATED_FRAMELESS_FUNCTION_INVOCATION Define this to an expression that returns 1 if the function invocation represented by @var{fi} does not have a stack frame associated with it. Otherwise return 0. @@ -3382,9 +3365,9 @@ pointer. It examines the current state of the machine as needed. Define this if you need to supply your own definition for the function @code{DEPRECATED_GET_SAVED_REGISTER}. -@item IBM6000_TARGET -@findex IBM6000_TARGET -Shows that we are configured for an IBM RS/6000 target. This +@item DEPRECATED_IBM6000_TARGET +@findex DEPRECATED_IBM6000_TARGET +Shows that we are configured for an IBM RS/6000 system. This conditional should be eliminated (FIXME) and replaced by feature-specific macros. It was introduced in a haste and we are repenting at leisure. @@ -3483,11 +3466,6 @@ method like @code{INTEGER_TO_ADDRESS} certainly makes it possible for @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. -@item NEED_TEXT_START_END -@findex NEED_TEXT_START_END -Define this if @value{GDBN} should determine the start and end addresses of the -text section. (Seems dubious.) - @item NO_HIF_SUPPORT @findex NO_HIF_SUPPORT (Specific to the a29k.) @@ -3510,8 +3488,8 @@ Convert the raw contents of register @var{regnum} into a value of type @var{type}. @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. -@item REGISTER_RAW_SIZE (@var{reg}) -@findex REGISTER_RAW_SIZE +@item DEPRECATED_REGISTER_RAW_SIZE (@var{reg}) +@findex DEPRECATED_REGISTER_RAW_SIZE Return the raw size of @var{reg}; defaults to the size of the register's virtual type. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. @@ -3538,14 +3516,14 @@ floating-point. @samp{float_reggroup}. Any register with a valid name. @end table -@item REGISTER_VIRTUAL_SIZE (@var{reg}) -@findex REGISTER_VIRTUAL_SIZE +@item DEPRECATED_REGISTER_VIRTUAL_SIZE (@var{reg}) +@findex DEPRECATED_REGISTER_VIRTUAL_SIZE Return the virtual size of @var{reg}; defaults to the size of the register's virtual type. Return the virtual size of @var{reg}. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. -@item REGISTER_VIRTUAL_TYPE (@var{reg}) +@item DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg}) @findex REGISTER_VIRTUAL_TYPE Return the virtual type of @var{reg}. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. @@ -3553,7 +3531,7 @@ Return the virtual type of @var{reg}. @item struct type *register_type (@var{gdbarch}, @var{reg}) @findex register_type If defined, return the type of register @var{reg}. This function -superseeds @code{REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture +superseeds @code{DEPRECATED_REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. @item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to}) @@ -3568,6 +3546,12 @@ Convert the value of register @var{reg} from its virtual form to its raw form. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. +@item const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size}) +@findex regset_from_core_section +Return the appropriate register set for a core file section with name +@var{sect_name} and size @var{sect_size}. + + @item RETURN_VALUE_ON_STACK(@var{type}) @findex RETURN_VALUE_ON_STACK @cindex returning structures by value @@ -3677,15 +3661,21 @@ be the number (greater than or equal to zero) of that register. This should only need to be defined if @code{TARGET_READ_PC} and @code{TARGET_WRITE_PC} are not defined. -@item NPC_REGNUM -@findex NPC_REGNUM -The number of the ``next program counter'' register, if defined. - @item PARM_BOUNDARY @findex PARM_BOUNDARY If non-zero, round arguments to a boundary of this many bits before pushing them on the stack. +@item stabs_argument_has_addr (@var{gdbarch}, @var{type}) +@findex stabs_argument_has_addr +@findex DEPRECATED_REG_STRUCT_HAS_ADDR +@anchor{stabs_argument_has_addr} Define this to return nonzero if a +function argument of type @var{type} is passed by reference instead of +value. + +This method replaces @code{DEPRECATED_REG_STRUCT_HAS_ADDR} +(@pxref{DEPRECATED_REG_STRUCT_HAS_ADDR}). + @item PROCESS_LINENUMBER_HOOK @findex PROCESS_LINENUMBER_HOOK A hook defined for XCOFF reading. @@ -3735,7 +3725,6 @@ reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}. This method replaces @code{DEPRECATED_CALL_DUMMY_WORDS}, @code{DEPRECATED_SIZEOF_CALL_DUMMY_WORDS}, @code{CALL_DUMMY}, @code{CALL_DUMMY_LOCATION}, @code{DEPRECATED_REGISTER_SIZE}, -@code{GDB_TARGET_IS_HPPA}, @code{DEPRECATED_CALL_DUMMY_BREAKPOINT_OFFSET}, and @code{DEPRECATED_FIX_CALL_DUMMY}. @@ -3756,14 +3745,13 @@ register buffer at run-time. Return the name of register @var{i} as a string. May return @code{NULL} or @code{NUL} to indicate that register @var{i} is not valid. -@item REGISTER_NAMES -@findex REGISTER_NAMES -Deprecated in favor of @code{REGISTER_NAME}. - @item DEPRECATED_REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type}) @findex DEPRECATED_REG_STRUCT_HAS_ADDR -Define this to return 1 if the given type will be passed by pointer -rather than directly. +@anchor{DEPRECATED_REG_STRUCT_HAS_ADDR}Define this to return 1 if the +given type will be passed by pointer rather than directly. + +This method has been replaced by @code{stabs_argument_has_addr} +(@pxref{stabs_argument_has_addr}). @item SAVE_DUMMY_FRAME_TOS (@var{sp}) @findex SAVE_DUMMY_FRAME_TOS @@ -3778,6 +3766,48 @@ allocated on the stack. @xref{unwind_dummy_id}. Define this to convert sdb register numbers into @value{GDBN} regnums. If not defined, no conversion will be done. +@item enum return_value_convention gdbarch_return_value (struct gdbarch *@var{gdbarch}, struct type *@var{valtype}, struct regcache *@var{regcache}, void *@var{readbuf}, const void *@var{writebuf}) +@findex gdbarch_return_value +@anchor{gdbarch_return_value} Given a function with a return-value of +type @var{rettype}, return which return-value convention that function +would use. + +@value{GDBN} currently recognizes two function return-value conventions: +@code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found +in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return +value is found in memory and the address of that memory location is +passed in as the function's first parameter. + +If the register convention is being used, and @var{writebuf} is +non-@code{NULL}, also copy the return-value in @var{writebuf} into +@var{regcache}. + +If the register convention is being used, and @var{readbuf} is +non-@code{NULL}, also copy the return value from @var{regcache} into +@var{readbuf} (@var{regcache} contains a copy of the registers from the +just returned function). + +@xref{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}, for a description of how +return-values that use the struct convention are handled. + +@emph{Maintainer note: This method replaces separate predicate, extract, +store methods. By having only one method, the logic needed to determine +the return-value convention need only be implemented in one place. If +@value{GDBN} were written in an @sc{oo} language, this method would +instead return an object that knew how to perform the register +return-value extract and store.} + +@emph{Maintainer note: This method does not take a @var{gcc_p} +parameter, and such a parameter should not be added. If an architecture +that requires per-compiler or per-function information be identified, +then the replacement of @var{rettype} with @code{struct value} +@var{function} should be persued.} + +@emph{Maintainer note: The @var{regcache} parameter limits this methods +to the inner most frame. While replacing @var{regcache} with a +@code{struct frame_info} @var{frame} parameter would remove that +limitation there has yet to be a demonstrated need for such a change.} + @item SKIP_PERMANENT_BREAKPOINT @findex SKIP_PERMANENT_BREAKPOINT Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally @@ -3836,6 +3866,9 @@ A C expression that writes the function return value, found in @var{valbuf}, into the @var{regcache}. @var{type} is the type of the value that is to be returned. +This method has been deprecated in favour of @code{gdbarch_return_value} +(@pxref{gdbarch_return_value}). + @item SUN_FIXED_LBRAC_BUG @findex SUN_FIXED_LBRAC_BUG (Used only for Sun-3 and Sun-4 targets.) @@ -3909,6 +3942,7 @@ Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. @findex TARGET_READ_PC @itemx TARGET_WRITE_PC (@var{val}, @var{pid}) @findex TARGET_WRITE_PC +@anchor{TARGET_WRITE_PC} @itemx TARGET_READ_SP @findex TARGET_READ_SP @itemx TARGET_READ_FP @@ -3970,6 +4004,9 @@ 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. +This method has been deprecated in favour of @code{gdbarch_return_value} +(@pxref{gdbarch_return_value}). + @item VALUE_TO_REGISTER(@var{type}, @var{regnum}, @var{from}, @var{to}) @findex VALUE_TO_REGISTER Convert a value of type @var{type} into the raw contents of register @@ -4634,6 +4671,66 @@ library because it's also used in binutils, for @file{objdump}). @section mmalloc @section libiberty +@cindex @code{libiberty} library + +The @code{libiberty} library provides a set of functions and features +that integrate and improve on functionality found in modern operating +systems. Broadly speaking, such features can be divided into three +groups: supplemental functions (functions that may be missing in some +environments and operating systems), replacement functions (providing +a uniform and easier to use interface for commonly used standard +functions), and extensions (which provide additional functionality +beyond standard functions). + +@value{GDBN} uses various features provided by the @code{libiberty} +library, for instance the C@t{++} demangler, the @acronym{IEEE} +floating format support functions, the input options parser +@samp{getopt}, the @samp{obstack} extension, and other functions. + +@subsection @code{obstacks} in @value{GDBN} +@cindex @code{obstacks} + +The obstack mechanism provides a convenient way to allocate and free +chunks of memory. Each obstack is a pool of memory that is managed +like a stack. Objects (of any nature, size and alignment) are +allocated and freed in a @acronym{LIFO} fashion on an obstack (see +@code{libiberty}'s documenatation for a more detailed explanation of +@code{obstacks}). + +The most noticeable use of the @code{obstacks} in @value{GDBN} is in +object files. There is an obstack associated with each internal +representation of an object file. Lots of things get allocated on +these @code{obstacks}: dictionary entries, blocks, blockvectors, +symbols, minimal symbols, types, vectors of fundamental types, class +fields of types, object files section lists, object files section +offets lists, line tables, symbol tables, partial symbol tables, +string tables, symbol table private data, macros tables, debug +information sections and entries, import and export lists (som), +unwind information (hppa), dwarf2 location expressions data. Plus +various strings such as directory names strings, debug format strings, +names of types. + +An essential and convenient property of all data on @code{obstacks} is +that memory for it gets allocated (with @code{obstack_alloc}) at +various times during a debugging sesssion, but it is released all at +once using the @code{obstack_free} function. The @code{obstack_free} +function takes a pointer to where in the stack it must start the +deletion from (much like the cleanup chains have a pointer to where to +start the cleanups). Because of the stack like structure of the +@code{obstacks}, this allows to free only a top portion of the +obstack. There are a few instances in @value{GDBN} where such thing +happens. Calls to @code{obstack_free} are done after some local data +is allocated to the obstack. Only the local data is deleted from the +obstack. Of course this assumes that nothing between the +@code{obstack_alloc} and the @code{obstack_free} allocates anything +else on the same obstack. For this reason it is best and safest to +use temporary @code{obstacks}. + +Releasing the whole obstack is also not safe per se. It is safe only +under the condition that we know the @code{obstacks} memory is no +longer needed. In @value{GDBN} we get rid of the @code{obstacks} only +when we get rid of the whole objfile(s), for instance upon reading a +new symbol file. @section gnu-regex @cindex regular expressions library @@ -4774,138 +4871,104 @@ functions, since they might never return to your code (they @cindex multi-arch data @cindex data-pointer, per-architecture/per-module -The multi-arch framework includes a mechanism for adding module specific -per-architecture data-pointers to the @code{struct gdbarch} architecture -object. +The multi-arch framework includes a mechanism for adding module +specific per-architecture data-pointers to the @code{struct gdbarch} +architecture object. -A module registers one or more per-architecture data-pointers using the -function @code{register_gdbarch_data}: +A module registers one or more per-architecture data-pointers using: -@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free}) +@deftypefun struct gdbarch_data *gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *@var{pre_init}) +@var{pre_init} is used to, on-demand, allocate an initial value for a +per-architecture data-pointer using the architecture's obstack (passed +in as a parameter). Since @var{pre_init} can be called during +architecture creation, it is not parameterized with the architecture. +and must not call modules that use per-architecture data. +@end deftypefun -The @var{init} function is used to obtain an initial value for a -per-architecture data-pointer. The function is called, after the -architecture has been created, when the data-pointer is still -uninitialized (@code{NULL}) and its value has been requested via a call -to @code{gdbarch_data}. A data-pointer can also be initialize -explicitly using @code{set_gdbarch_data}. +@deftypefun struct gdbarch_data *gdbarch_data_register_post_init (gdbarch_data_post_init_ftype *@var{post_init}) +@var{post_init} is used to obtain an initial value for a +per-architecture data-pointer @emph{after}. Since @var{post_init} is +always called after architecture creation, it both receives the fully +initialized architecture and is free to call modules that use +per-architecture data (care needs to be taken to ensure that those +other modules do not try to call back to this module as that will +create in cycles in the initialization call graph). +@end deftypefun -The @var{free} function is called when a data-pointer needs to be -destroyed. This occurs when either the corresponding @code{struct -gdbarch} object is being destroyed or when @code{set_gdbarch_data} is -overriding a non-@code{NULL} data-pointer value. +These functions return a @code{struct gdbarch_data} that is used to +identify the per-architecture data-pointer added for that module. -The function @code{register_gdbarch_data} returns a @code{struct -gdbarch_data} that is used to identify the data-pointer that was added -to the module. +The per-architecture data-pointer is accessed using the function: +@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle}) +Given the architecture @var{arch} and module data handle +@var{data_handle} (returned by @code{gdbarch_data_register_pre_init} +or @code{gdbarch_data_register_post_init}), this function returns the +current value of the per-architecture data-pointer. If the data +pointer is @code{NULL}, it is first initialized by calling the +corresponding @var{pre_init} or @var{post_init} method. @end deftypefun -A typical module has @code{init} and @code{free} functions of the form: +The examples below assume the following definitions: @smallexample +struct nozel @{ int total; @}; static struct gdbarch_data *nozel_handle; -static void * -nozel_init (struct gdbarch *gdbarch) -@{ - struct nozel *data = XMALLOC (struct nozel); - @dots{} - return data; -@} -@dots{} -static void -nozel_free (struct gdbarch *gdbarch, void *data) -@{ - xfree (data); -@} @end smallexample -Since uninitialized (@code{NULL}) data-pointers are initialized -on-demand, an @code{init} function is free to call other modules that -use data-pointers. Those modules data-pointers will be initialized as -needed. Care should be taken to ensure that the @code{init} call graph -does not contain cycles. +A module can extend the architecture vector, adding additional +per-architecture data, using the @var{pre_init} method. The module's +per-architecture data is then initialized during architecture +creation. -The data-pointer is registered with the call: +In the below, the module's per-architecture @emph{nozel} is added. An +architecture can specify its nozel by calling @code{set_gdbarch_nozel} +from @code{gdbarch_init}. @smallexample -void -_initialize_nozel (void) +static void * +nozel_pre_init (struct obstack *obstack) @{ - nozel_handle = register_gdbarch_data (nozel_init, nozel_free); -@dots{} + struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel); + return data; +@} @end smallexample -The per-architecture data-pointer is accessed using the function: - -@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle}) -Given the architecture @var{arch} and module data handle -@var{data_handle} (returned by @code{register_gdbarch_data}, this -function returns the current value of the per-architecture data-pointer. -@end deftypefun - -The non-@code{NULL} data-pointer returned by @code{gdbarch_data} should -be saved in a local variable and then used directly: - @smallexample -int -nozel_total (struct gdbarch *gdbarch) +extern void +set_gdbarch_nozel (struct gdbarch *gdbarch, int total) @{ - int total; struct nozel *data = gdbarch_data (gdbarch, nozel_handle); - @dots{} - return total; + data->total = nozel; @} @end smallexample -It is also possible to directly initialize the data-pointer using: +A module can on-demand create architecture dependant data structures +using @code{post_init}. -@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer}) -Update the data-pointer corresponding to @var{handle} with the value of -@var{pointer}. If the previous data-pointer value is non-NULL, then it -is freed using data-pointers @var{free} function. -@end deftypefun - -This function is used by modules that require a mechanism for explicitly -setting the per-architecture data-pointer during architecture creation: +In the below, the nozel's total is computed on-demand by +@code{nozel_post_init} using information obtained from the +architecture. @smallexample -/* Called during architecture creation. */ -extern void -set_gdbarch_nozel (struct gdbarch *gdbarch, - int total) -@{ - struct nozel *data = XMALLOC (struct nozel); - @dots{} - set_gdbarch_data (gdbarch, nozel_handle, nozel); -@} -@end smallexample - -@smallexample -/* Default, called when nozel not set by set_gdbarch_nozel(). */ static void * -nozel_init (struct gdbarch *gdbarch) +nozel_post_init (struct gdbarch *gdbarch) @{ - struct nozel *default_nozel = XMALLOC (struc nozel); - @dots{} - return default_nozel; + struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel); + nozel->total = gdbarch@dots{} (gdbarch); + return data; @} @end smallexample @smallexample -void -_initialize_nozel (void) +extern int +nozel_total (struct gdbarch *gdbarch) @{ - nozel_handle = register_gdbarch_data (nozel_init, NULL); - @dots{} + struct nozel *data = gdbarch_data (gdbarch, nozel_handle); + return data->total; +@} @end smallexample -@noindent -Note that an @code{init} function still needs to be registered. It is -used to initialize the data-pointer when the architecture creation phase -fail to set an initial value. - - @section Wrapping Output Lines @cindex line wrap in output @@ -5033,6 +5096,25 @@ This warning includes uses of the assignment operator within an @item -Wpointer-arith @item -Wuninitialized + +@item -Wunused-label +This warning has the additional benefit of detecting the absence of the +@code{case} reserved word in a switch statement: +@smallexample +enum @{ FD_SCHEDULED, NOTHING_SCHEDULED @} sched; +@dots{} +switch (sched) + @{ + case FD_SCHEDULED: + @dots{}; + break; + NOTHING_SCHEDULED: + @dots{}; + break; + @} +@end smallexample + +@item -Wunused-function @end table @emph{Pragmatics: Due to the way that @value{GDBN} is implemented most @@ -6376,12 +6458,12 @@ intelligibility. This is the base testsuite. The tests in it should apply to all configurations of @value{GDBN} (but generic native-only tests may live here). The test programs should be in the subset of C that is valid K&R, -ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance +ANSI/ISO, and C@t{++} (@code{#ifdef}s are allowed if necessary, for instance for prototypes). @item gdb.@var{lang} Language-specific tests for any language @var{lang} besides C. Examples are -@file{gdb.c++} and @file{gdb.java}. +@file{gdb.cp} and @file{gdb.java}. @item gdb.@var{platform} Non-portable tests. The tests are specific to a specific configuration @@ -6632,7 +6714,9 @@ is so old that it has never been converted to use BFD. Now that's old! @end table @include observer.texi +@raisesections @include fdl.texi +@lowersections @node Index @unnumbered Index diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo index 3fcfc0a079a..b61acadb256 100644 --- a/gdb/doc/stabs.texinfo +++ b/gdb/doc/stabs.texinfo @@ -3,13 +3,12 @@ @c @finalout -@ifinfo -@format -START-INFO-DIR-ENTRY -* Stabs: (stabs). The "stabs" debugging information format. -END-INFO-DIR-ENTRY -@end format -@end ifinfo +@c This is a dir.info fragment to support semi-automated addition of +@c manuals to an info tree. +@dircategory Programming & development tools. +@direntry +* Stabs: (stabs). The "stabs" debugging information format. +@end direntry @ifinfo This document describes the stabs debugging symbol tables. @@ -36,7 +35,7 @@ Free Documentation License''. @page @tex \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 1.11 $} % For use in headers, footers too +\xdef\manvers{\$Revision: 1.11.4.1 $} % For use in headers, footers too {\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par @@ -253,10 +252,10 @@ 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++ +of dbx may not do this. Because of a conflict with C@t{++} (@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: +those from the C@t{++} type descriptor @samp{@@}. The attributes are: @table @code @item a@var{boundary} @@ -431,7 +430,7 @@ 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 +from the @code{cfront} C@t{++} 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. @@ -1766,7 +1765,7 @@ 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 +C@t{++} 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: @@ -2063,13 +2062,13 @@ 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 +If a field is a static member (this is a C@t{++} 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 +If the structure has methods (a C@t{++} feature), they follow the non-method fields; see @ref{Cplusplus}. @node Typedefs @@ -2390,7 +2389,7 @@ Symnum n_type n_othr n_desc n_value n_strx String @end example @node Cplusplus -@chapter GNU C++ Stabs +@chapter GNU C@t{++} Stabs @menu * Class Names:: C++ class names are both tags and typedefs. @@ -2410,9 +2409,9 @@ Symnum n_type n_othr n_desc n_value n_strx String @end menu @node Class Names -@section C++ Class Names +@section C@t{++} Class Names -In C++, a class name which is declared with @code{class}, @code{struct}, +In C@t{++}, 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}). @@ -2421,7 +2420,7 @@ 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 +For example, the C@t{++} code @example struct foo @{int x;@}; @@ -2443,7 +2442,7 @@ or @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. +In C@t{++}, 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 @@ -2458,12 +2457,12 @@ 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++ +@section Basic Types For C@t{++} << the examples that follow are based on a01.C >> -C++ adds two more builtin types to the set defined for C. These are +C@t{++} 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. @@ -2474,7 +2473,7 @@ 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 +This basic type is present in all C@t{++} programs even if there are no virtual methods defined. @display @@ -2504,8 +2503,8 @@ virtual methods defined. @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 +The stabs describing C@t{++} language features are an extension of the +stabs describing C. Stabs representing C@t{++} 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. @@ -2527,20 +2526,20 @@ stab is not located between an @code{N_FUN} and an @code{N_LBRAC} stab this indi 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 +A stab describing a C@t{++} 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 relevant to C++ class members. +expanded to include extra information relevant to C@t{++} 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 +In this simple example the field part of the C@t{++} 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 +The field part of a C@t{++} 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, @@ -2567,7 +2566,7 @@ occur in the @var{operator-name} string. The next part of the method description represents the arguments to the method, preceded 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} +in C@t{++} 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, @@ -2601,7 +2600,7 @@ information present for virtual methods. @node Class Instance @section Class Instance -As shown above, describing even a simple C++ class definition is +As shown above, describing even a simple C@t{++} 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 @@ -2628,7 +2627,7 @@ different from a standard C stab describing a local variable. @node Methods @section Method Definition -The class definition shown above declares Ameth. The C++ source below +The class definition shown above declares Ameth. The C@t{++} source below defines Ameth: @example @@ -2724,7 +2723,7 @@ descriptor for a pointer-to-non-static-member-data type. It is followed by type information for the class (or union), a comma, and type information for the member data. -The following C++ source: +The following C@t{++} source: @smallexample typedef int A::*int_in_a; @@ -2738,7 +2737,7 @@ generates the following stab: 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 +Fortunately, the @samp{@@} type descriptor used in this C@t{++} sense always will be followed by a digit, @samp{(}, or @samp{-}, and type attributes never start with those things. @@ -2748,7 +2747,7 @@ never start with those things. In the simple class definition shown above all member data and functions were publicly accessible. The example that follows contrasts public, protected and privately accessible fields and shows -how these protections are encoded in C++ stabs. +how these protections are encoded in C@t{++} 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} @@ -2762,7 +2761,7 @@ 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: +The following C@t{++} source: @example class vis @{ @@ -2792,7 +2791,7 @@ type float (@samp{12}), and offset and size @samp{,64,32;}. Protections for member functions are signified by one digit embedded 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 +private, 1 if protected and 2 if public. Consider the C@t{++} class definition below: @example @@ -2890,7 +2889,7 @@ 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 +C@t{++} 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 @@ -2902,7 +2901,7 @@ 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++ +17. Type 17 was the vtable record type defined by the boilerplate C@t{++} type definitions, as shown earlier. The bit offset of the vtable pointer field is 32. The number of bits @@ -2956,7 +2955,7 @@ class. This is preceded by @samp{~%} and followed by a final semi-colon. @node Inheritance @section Inheritance -Stabs describing C++ derived classes include additional sections that +Stabs describing C@t{++} derived classes include additional sections that describe the inheritance 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 inheritance is private @@ -3287,13 +3286,13 @@ GNU Modula2 definition module dependency; see @ref{N_DEFD}. Function start/body/end line numbers (Solaris2). @item 0x50 N_EHDECL -GNU C++ exception variable; see @ref{N_EHDECL}. +GNU C@t{++} 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}. +GNU C@t{++} @code{catch} clause; see @ref{N_CATCH}. @item 0x60 N_SSYM Structure of union element; see @ref{N_SSYM}. @@ -3387,7 +3386,7 @@ for more information about their use. Variable on the stack; see @ref{Stack Variables}. @item : -C++ nested symbol; see @xref{Nested Symbols}. +C@t{++} nested symbol; see @xref{Nested Symbols}. @item a Parameter passed by reference in register; see @ref{Reference Parameters}. @@ -3400,7 +3399,7 @@ 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 +Arrays}. Name of a caught exception (GNU C@t{++}). These can be distinguished because the latter uses @code{N_CATCH} and the former uses another symbol type. @@ -3501,17 +3500,17 @@ Type reference; see @ref{String Field}. Reference to builtin type; see @ref{Negative Type Numbers}. @item # -Method (C++); see @ref{Method Type Descriptor}. +Method (C@t{++}); see @ref{Method Type Descriptor}. @item * Pointer; see @ref{Miscellaneous Types}. @item & -Reference (C++). +Reference (C@t{++}). @item @@ Type Attributes (AIX); see @ref{String Field}. Member (class and variable) -type (GNU C++); see @ref{Member Type Descriptor}. +type (GNU C@t{++}); see @ref{Member Type Descriptor}. @item a Array; see @ref{Arrays}. @@ -3616,7 +3615,7 @@ Wide character; see @ref{Builtin Type Descriptors}. Cross-reference; see @ref{Cross-References}. @item Y -Used by IBM's xlC C++ compiler (for structures, I think). +Used by IBM's xlC C@t{++} compiler (for structures, I think). @item z gstring; see @ref{Strings}. @@ -3758,7 +3757,7 @@ if it is imported with the GNU M2 keyword @code{%INITIALIZE}. Perhaps @deffn @code{.stabs} N_EHDECL @findex N_EHDECL -GNU C++ exception variable <<?>>. +GNU C@t{++} exception variable <<?>>. "@var{string} is variable name" @@ -3780,9 +3779,9 @@ Note: conflicts with @code{N_EHDECL} <<?>> @deffn @code{.stabn} N_CATCH @findex N_CATCH -GNU C++ @code{catch} clause +GNU C@t{++} @code{catch} clause -GNU C++ @code{catch} clause. The value is its address. The desc field +GNU C@t{++} @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 @@ -4027,7 +4026,9 @@ 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. +@raisesections @include fdl.texi +@lowersections @node Symbol Types Index @unnumbered Symbol Types Index |