diff options
Diffstat (limited to 'gnu/usr.bin/binutils/gdb/doc')
| -rw-r--r-- | gnu/usr.bin/binutils/gdb/doc/ChangeLog | 361 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/gdb/doc/agentexpr.texi | 2 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/gdb/doc/gdb.texinfo | 938 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/gdb/doc/gdbint.texinfo | 643 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/gdb/doc/stabs.texinfo | 34 |
5 files changed, 1309 insertions, 669 deletions
diff --git a/gnu/usr.bin/binutils/gdb/doc/ChangeLog b/gnu/usr.bin/binutils/gdb/doc/ChangeLog index b5834f430f4..c46594bddb9 100644 --- a/gnu/usr.bin/binutils/gdb/doc/ChangeLog +++ b/gnu/usr.bin/binutils/gdb/doc/ChangeLog @@ -1,3 +1,259 @@ +2004-10-12 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Versions and Branches): New chapter. + (Releasing GDB): Delete "Versions and Branches" section. + (Top): Add "Versions and Branches". + +2004-10-08 Eli Zaretskii <eliz@gnu.org> + + * gdb.texinfo (Editing, History): Add cross-references to the + included Readline and History user documentation. Remove + references to the symbol have-readline-appendices which is unused + and undefined. + (History): Fix indexing. + +2004-10-08 Jeff Johnston <jjohnstn@redhat.com> + + * gdbint.texinfo (target_stopped_data_address): Update to + new prototype. + (i386_stopped_data_address): Update prototype and description. + (i386_stopped_by_watchpoint): New function and description. + +2004-10-03 Paul N. Hilfinger <hilfinger@gnat.com> + + * gdb.texinfo (Filenames): Add Ada suffixes. + (Ada) New section. + +2004-09-27 Andrew Cagney <cagney@gnu.org> + Robert Picco <Robert.Picco@hp.com> + + * gdb.texinfo (Packets): Document the "p" packet. + +2004-09-21 Jason Molenda (jmolenda@apple.com) + + * gdb.texinfo (Paths and Names of the Source Files): Document the + meaning of values in the 'desc' field of a SO stab. + +2004-09-20 Daniel Jacobowitz <dan@debian.org> + + * gdb.texinfo (Maintenance Commands): Document "maint set dwarf2 + max-cache-age" and "maint show dwarf2 max-cache-age". + +2004-09-16 Eli Zaretskii <eliz@gnu.org> + + * gdb.texinfo (Set Breaks): Add index entry for setting + breakpoints on overloaded C++ functions that are not members of + any classes. Add an example and an index entry for setting + breakpoints on all program functions. + (Character Sets, Macros, Overlay Commands) + (Non-debug DLL symbols, GDB/MI Output Syntax) + (Annotations Overview, Maintenance Commands, File-I/O Overview): + Use "(@value{GDBP})" instead of a literal "(gdb)". + +2004-09-12 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Native Debugging): Delete description of + FILES_INFO_HOOK. + +2004-09-11 Paul Hilfinger <hilfinger@gnat.com> + + * gdbint.texinfo (User Interface): Change local_hex_string_custom + to hex_string_custom (not historically correct, but more + understandable, given the current code). + +2004-09-03 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Native Debugging): Delete SVR4_SHARED_LIBS. + +2004-09-01 Jeff Johnston <jjohnstn@redhat.com> + + * observer.texi (solib_unloaded): New observer. + +2004-08-24 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Add missing + comma. + +2004-08-20 Michael Chastain <mec.gnu@mindspring.com> + + * (Using the Testsuite): build != host is supported, + but some test scripts do not support build != host. + +2004-08-14 Mark Kettenis <kettenis@gnu.org> + + * gdbint.texinfo (Host Definition): Delete description of + FCLOSE_PROVIDED and GETENV_PROVIDED. + +2004-08-05 Mark Kettenis <kettenis@chello.nl> + + * gdbint.texinfo (Host Definition): Delete description of + NO_SYS_FILE. + (Native Debugging): Delete description of KERNEL_U_ADDR_BSD and + PTRACE_FP_BUG. + +2004-08-05 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Delete + reference to deprecated_read_fp. + +2004-08-02 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Delete + description of DEPRECATED_REGISTER_BYTES. + +2004-07-30 Baurjan Ismagulov <ibr@ata.cs.hun.edu.tr> + + * gdb.texinfo (Source Path): Document the new behavior of + searching for the source files. + +2004-07-17 Eli Zaretskii <eliz@gnu.org> + + * gdb.texinfo (Edit): Fix markup of EDITOR and improve wording. + (Search, Expressions, Arrays, Variables, Data, Machine Code) + (Auto Display): Improve indexing. + +2004-07-16 Andrew Cagney <cagney@gnu.org> + + * gdb.texinfo (Mode Options): Delete documentation on "-async" and + "-noasync". + +2004-07-09 Eli Zaretskii <eliz@gnu.org> + + * gdb.texinfo: Fix @kindex entries so that multiple commands that + have the same prefix have only their prefix in the index. + +2004-07-03 Mark Kettenis <kettenis@gnu.org> + + * gdb.texinfo (BSD libkvm Interface): New node (section) + (Native): Add it to the menu. + +2004-07-01 Mark Kettenis <kettenis@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Remove + PCC_SOL_BROKEN. + +2004-06-24 Mark Kettenis <kettenis@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Remove + SUN_FIXED_LBRAC_BUG. + +2004-06-26 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Coding): Replace xasprintf with xstrprintf. + +2004-06-20 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Deprecate + USE_STRUCT_CONVENTION. + +2004-06-19 Michael Chastain <mec.gnu@mindspring.com> + + gdb.texinfo (Bug Reporting): Mention session recording, + with the script command or Emacs. + +2004-06-18 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Deprecate + FUNCTION_START_OFFSET. + +2004-06-14 Andrew Cagney <cagney@gnu.org> + + Based on changes from Karl Berry. + * gdb.texinfo: Do not use @sc in a direntry. + * stabs.texinfo: Change @dircateogry to "Software development". + * gdbint.texinfo, gdb.texinfo, annotate.texinfo: Ditto. + +2004-06-13 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Target Architecture Definition): Delete + description of RETURN_VALUE_ON_STACK. + +2004-06-09 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Native Debugging): Restore "@table @code" + deleted by previous patch. + +2004-06-08 Andrew Cagney <cagney@gnu.org> + + * gdbint.texinfo (Native Debugging): Delete documentation on + ATTACH_DETACH. + +2004-06-06 Randolph Chung <tausq@debian.org> + + * gdb.texinfo (push_dummy_call): Use @code{struct value}. + +2004-06-06 Randolph Chung <tausq@debian.org> + + * gdb.texinfo (push_dummy_call): Update argument list to match + the new push_dummy_call method signature. Describe the function + argument. + +2004-05-24 Joel Brobecker <brobecker@gnat.com> + + * gdb.texinfo (Starting): Document new start command. + +2004-05-21 Andrew Cagney <cagney@redhat.com> + + * observer.texi (GDB Observers): Document "inferior_created". + +2004-05-08 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Delete + description of DO_DEFERRED_STORES. + + * gdbint.texinfo (Target Architecture Definition): Delete + references to DEPRECATED_FIX_CALL_DUMMY. + + * gdbint.texinfo (Target Architecture Definition): Delete + description of DEPRECATED_CALL_DUMMY_WORDS, + DEPRECATED_SIZEOF_CALL_DUMMY_WORDS, and CALL_DUMMY. + + * gdbint.texinfo (Target Architecture Definition): Delete + description of DEPRECATED_PUSH_DUMMY_FRAME. + + * gdbint.texinfo (Target Architecture Definition): Delete + reference to DEPRECATED_CALL_DUMMY_BREAKPOINT_OFFSET. + +2004-05-07 Andrew Cagney <cagney@redhat.com> + + * observer.texi (GDB Observers): Add "Debugging" section. Include + cross reference to "set/show debug observer". + * gdb.texinfo (Debugging Output): Document "set/show debug + observer". + +2004-05-01 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Delete + description of DEPRECATED_PC_IN_SIGTRAMP. + +2004-04-30 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Delete + documentation for BELIEVE_PCC_PROMOTION_TYPE, no longer defined. + +2004-04-30 Orjan Friberg <orjanf@axis.com> + + * observer.texi (GDB Observers): Correct spelling. + +2004-04-26 Orjan Friberg <orjanf@axis.com> + + * observer.texi (GDB Observers): Add target_changed event. + +2004-04-08 Andrew Cagney <cagney@redhat.com> + + * observer.texi (GDB Observers): Rework, provide generic observer + definitions and then a list of observable events. + +2004-04-04 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Host Definition): Delete reference to + NO_SIGINTERRUPT. + +2004-04-02 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Delete + reference to DEPRECATED_CALL_DUMMY_LENGTH. + 2004-03-28 Stephane Carrez <stcarrez@nerim.fr> * gdb.texinfo (TUI Commands): Document tui reg commands. @@ -9,6 +265,31 @@ (Mode Options): Mention "gdbtui". Use "Text" not "Terminal". (Contributors): Mention both Text and Terminal User Interface. +2004-03-23 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Deprecate + references to SIGTRAMP_START and SIGTRAMP_END. + +2004-03-23 Andrew Cagney <cagney@redhat.com> + + * gdbint.texinfo (Target Architecture Definition): Deprecate + references to PC_IN_SIGTRAMP. + +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. @@ -130,7 +411,7 @@ (Coding): Add -Wunused-label to list of -Werror warnings. 2004-01-08 Jason Molenda <jmolenda@apple.com> - Eli Zaretskii <eliz@is.elta.co.il> + Eli Zaretskii <eliz@gnu.org> * gdb.texinfo: Update copyright. (Objective-C): "methodName" typeo fixed. Add @code/@var markup @@ -888,7 +1169,7 @@ 2002-09-20 Kevin Buettner <kevinb@redhat.com> - From Eli Zaretskii <eliz@is.elta.co.il>: + From Eli Zaretskii <eliz@gnu.org>: * gdb.texinfo (Character Sets): Use @smallexample instead of @example. Use GNU/Linux instead of Linux. @@ -1159,14 +1440,14 @@ * gdbint.texinfo (Target Architecture Definition): Delete definition of HAVE_REGISTER_WINDOWS. -2002-04-19 Eli Zaretskii <eliz@is.elta.co.il> +2002-04-19 Eli Zaretskii <eliz@gnu.org> * gdbint.texinfo (Releasing GDB, Coding): Fix typos. Reported by "Theodore A. Roth" <troth@verinet.com>. 2002-04-15 Don Howard <dhoward@redhat.com> - From Eli Zaretskii <eliz@is.elta.co.il> + From Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (show max-user-call-depth): Correct formatting. Provide a better explaination of this feature. @@ -1270,7 +1551,7 @@ '_ovly_debug_event', which allows GDB to keep better track of overlays. -2002-02-03 Eli Zaretskii <eliz@is.elta.co.il> +2002-02-03 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Memory Region Attributes): Fix the wording. Suggested by Dmitry Sivachenko. @@ -1295,7 +1576,7 @@ * gdbint.texinfo (Target Architecture Definition): Delete description of TARGET_BYTE_ORDER_DEFAULT. -2002-01-27 Eli Zaretskii <eliz@is.elta.co.il> +2002-01-27 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo: Fix typos and markup. From Dmitry Sivachenko <mitya@cavia.pp.ru>. @@ -1353,7 +1634,7 @@ Tue Jan 22 11:57:38 2002 Andrew Cagney <cagney@redhat.com> * gdbint.texinfo (Target Architecture Definition): Remove definition of IEEE_FLOAT. -2002-01-20 Eli Zaretskii <eliz@is.elta.co.il> +2002-01-20 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo: Beautify copyright years; fix a typo. (DJGPP Native): Fix overfull hboxes in examples. From Brian Youmans @@ -1379,7 +1660,7 @@ Tue Jan 22 11:57:38 2002 Andrew Cagney <cagney@redhat.com> * fdl.texi: Remove next/prev from @node. -2002-01-17 Eli Zaretskii <eliz@is.elta.co.il> +2002-01-17 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo: @include fdl.texi. Fixes for overfull hboxes and for monstrous @multitable (from Brian Youmans). @@ -1411,7 +1692,7 @@ Tue Jan 22 11:57:38 2002 Andrew Cagney <cagney@redhat.com> * gdb.texinfo (--pid): Document new command line option (attach). -2002-01-07 Eli Zaretskii <eliz@is.elta.co.il> +2002-01-07 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Tracepoints): Clarify that tracepoints need support in the stub. @@ -1435,7 +1716,7 @@ Tue Jan 22 11:57:38 2002 Andrew Cagney <cagney@redhat.com> * gdb.texinfo (Free Software): New section ``Free Software Needs Free Documentation''. -2001-12-30 Eli Zaretskii <eliz@is.elta.co.il> +2001-12-30 Eli Zaretskii <eliz@gnu.org> * stabs.texinfo: * gdb.texinfo: @@ -1482,7 +1763,7 @@ Tue Jan 22 11:57:38 2002 Andrew Cagney <cagney@redhat.com> * gdb.texinfo (Options): Eliminate attempt to explain .gdbinit/gdb.ini use since it is described in the referenced section. - From Eli Zaretskii <eliz@is.elta.co.il> + From Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Command Files): Reword to make gdb.ini requirement clearer when using DJGPP. @@ -1596,7 +1877,7 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> * gdbint.texinfo (libgdb): Rewrite. -2001-07-26 Eli Zaretskii <eliz@is.elta.co.il> +2001-07-26 Eli Zaretskii <eliz@gnu.org> * Makefile.in (gdbgui.dvi, gdb-gui, gdbgui.info): Targets deleted. @@ -1610,7 +1891,7 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> * gdbint.texinfo (Host Definition): Remove description of NEED_POSIX_SETPGID. -2001-07-23 Eli Zaretskii <eliz@is.elta.co.il> +2001-07-23 Eli Zaretskii <eliz@gnu.org> * gdb.tex (DJGPP Native): New node, with descriptions of DJGPP-specific commands. @@ -1649,7 +1930,7 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> EXTRACT_STRUCT_VALUE_ADDRESS and EXTRACT_STRUCT_VALUE_ADDRESS_P. The latter has been changed to a true predicate. -2001-06-17 Eli Zaretskii <eliz@is.elta.co.il> +2001-06-17 Eli Zaretskii <eliz@gnu.org> * annotate.texi: Add @noindent where needed. From Dmitry Sivachenko <dima@Chg.RU>. @@ -1668,7 +1949,7 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> * gdb.texinfo (Protocol): Add doc for new packet "qSymbol:". -2001-06-13 Eli Zaretskii <eliz@is.elta.co.il> +2001-06-13 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Signals): Clarify the default setting of signal handling. @@ -1682,20 +1963,20 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> * Makefile.in (GDBvn.texi): Set GDBVN from ../version.in. -2001-05-10 Eli Zaretskii <eliz@is.elta.co.il> +2001-05-10 Eli Zaretskii <eliz@gnu.org> * gdbint.texinfo (Clean Design and Portable Implementation): Renamed from "Clean Design". (Clean Design and Portable Implementation): Document portable methods of handling file names, and the associated macros. -2001-04-02 Eli Zaretskii <eliz@is.elta.co.il> +2001-04-02 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Tracepoint Actions): Mention the "info scope" command and provide a cross-reference to its description. (Symbols): Note that "info scope" is useful for trace experiments. -2001-04-01 Eli Zaretskii <eliz@is.elta.co.il> +2001-04-01 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Symbols): Document "info scope". (Tracepoints): New chapter. @@ -1707,7 +1988,7 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> * stabs.texinfo: Change Permissions to GFDL. Update Copyright. -2001-03-26 Eli Zaretskii <eliz@is.elta.co.il> +2001-03-26 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo: Change Permissions to GFDL. Update Copyright. @@ -1722,7 +2003,7 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> a cross-reference to its description. (Symbols): Document "info symbol". -2001-03-21 Eli Zaretskii <eliz@is.elta.co.il> +2001-03-21 Eli Zaretskii <eliz@gnu.org> * gdbint.texinfo (Algorithms): New section "Watchpoints" and new subsection "x86 Watchpoints". @@ -1741,11 +2022,11 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> * Makefile.in, all-cfg.texi, annotate.texi, gdb.texinfo, gdbint.texinfo, refcard.tex: Update/correct copyright notices. -2001-02-21 Eli Zaretskii <eliz@is.elta.co.il> +2001-02-21 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Signals): Document "ignore", "noignore", and "all". -2001-02-11 Eli Zaretskii <eliz@is.elta.co.il> +2001-02-11 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Environment): Document that `path' does not change the value of PATH in GDB's own environment (it did in the past, @@ -1764,7 +2045,7 @@ Wed Aug 15 10:47:28 2001 Christopher Faylor <cgf@cygnus.com> * gdbint.texinfo (POP_FRAME): Document use by return_command. -2000-12-25 Eli Zaretskii <eliz@is.elta.co.il> +2000-12-25 Eli Zaretskii <eliz@gnu.org> * refcard.tex: Version and copyright fixed. From Phil Edwards <pedwards@disaster.jaj.com>. @@ -1779,7 +2060,7 @@ Mon Nov 20 21:29:35 2000 Andrew Cagney <cagney@b1.cygnus.com> * gdbint.texinfo (Coding): Update current value of --enable-build-warnings. Mention --enable-gdb-build-warnings. -2000-11-19 Eli Zaretskii <eliz@is.elta.co.il> +2000-11-19 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Continuing and Stepping): Fixed markup and typos, as suggested by Dmitry Sivachenko <dima@Chg.RU>. @@ -1788,12 +2069,12 @@ Mon Nov 20 21:29:35 2000 Andrew Cagney <cagney@b1.cygnus.com> * gdb.texinfo: Document new 'set step-mode' command. -2000-10-16 Eli Zaretskii <eliz@is.elta.co.il> +2000-10-16 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Contributors, MIPS Embedded): Minor spelling changes from Dmitry Sivachenko <dima@Chg.RU>. -2000-09-26 Eli Zaretskii <eliz@is.elta.co.il> +2000-09-26 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Hooks): Document the new post-hook functionality. From Steven Johnson <sbjohnson@ozemail.com.au>. @@ -1802,7 +2083,7 @@ Mon Nov 20 21:29:35 2000 Andrew Cagney <cagney@b1.cygnus.com> * gdbint.texinfo (Overall Structure): Spelling fix. -2000-08-10 Eli Zaretskii <eliz@is.elta.co.il> +2000-08-10 Eli Zaretskii <eliz@gnu.org> * gdbint.texinfo (Target Architecture Definition): Document that REGISTER_CONVERT_TO_VIRTUAL should only be called on a register @@ -1818,12 +2099,12 @@ Mon Nov 20 21:29:35 2000 Andrew Cagney <cagney@b1.cygnus.com> * stabs.texinfo: Fix spelling errors. (String Field): FILE-NUMBER starts from 0, not 1. -2000-07-05 Eli Zaretskii <eliz@is.elta.co.il> +2000-07-05 Eli Zaretskii <eliz@gnu.org> * refcard.tex: Remove \centerline from the blurb. Patch from Brian Youmans. -2000-06-25 Eli Zaretskii <eliz@is.elta.co.il> +2000-06-25 Eli Zaretskii <eliz@gnu.org> * Makefile.in (install-info): Support installation from outside of the source directory. Reported by Mark Harig @@ -1842,7 +2123,7 @@ Fri May 26 15:55:33 2000 Andrew Cagney <cagney@b1.cygnus.com> (gdb.texinfo, gdbint.texinfo, stabs.texinfo): When TeX insert the @contents at the start. -2000-05-24 Eli Zaretskii <eliz@is.elta.co.il> +2000-05-24 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo: Remove duplicate @syncodeindex. From Brian Youmans. @@ -1861,7 +2142,7 @@ Tue May 23 22:57:41 2000 Andrew Cagney <cagney@b1.cygnus.com> * configure: Regenerate. -2000-05-17 Eli Zaretskii <eliz@is.elta.co.il> +2000-05-17 Eli Zaretskii <eliz@gnu.org> * Makefile.in (install-info): Run install-info on installed Info files. @@ -1871,7 +2152,7 @@ Fri May 12 20:18:04 2000 Andrew Cagney <cagney@b1.cygnus.com> * gdb.texinfo: Add Stan Shebs, et.al. as authors. Mention Andrew Cagney. -2000-05-09 Eli Zaretskii <eliz@is.elta.co.il> +2000-05-09 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo: Proofreading changes from Brian Youmans. @@ -1880,7 +2161,7 @@ Fri May 12 20:18:04 2000 Andrew Cagney <cagney@b1.cygnus.com> * gdb.texinfo (Command Files): Mention -x, use @enumerate for startup sequence, minor edits. -2000-05-01 Eli Zaretskii <eliz@is.elta.co.il> +2000-05-01 Eli Zaretskii <eliz@gnu.org> * annotate.texi: Remove "@syncodeindex fn cp", it causes grief in TeX. @@ -1894,7 +2175,7 @@ Sat Apr 29 17:01:04 2000 Andrew Cagney <cagney@b1.cygnus.com> * gdbint.texinfo (Hints): Do not use @value{GDBN in @nodes. -2000-04-23 Eli Zaretskii <eliz@is.elta.co.il> +2000-04-23 Eli Zaretskii <eliz@gnu.org> * Makefile.in (GDBMI_DIR): New variable. (SET_TEXINPUTS): Add $(GDBMI_DIR). @@ -1913,19 +2194,19 @@ Sat Apr 29 17:01:04 2000 Andrew Cagney <cagney@b1.cygnus.com> * gdb.texinfo (Files): Update description of add-symbol-file command. -2000-04-17 Eli Zaretskii <eliz@is.elta.co.il> +2000-04-17 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Porting GDB): Don't use @value in the node name, it prevents the build (and is generally a Bad Idea). -2000-04-17 Eli Zaretskii <eliz@is.elta.co.il> +2000-04-17 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Protocol): Prevent makeinfo from complaining about a comma inside @var. (Command Files): Index markup changes from Dmitry Sivachenko <dima@Chg.RU>. -2000-04-16 Eli Zaretskii <eliz@is.elta.co.il> +2000-04-16 Eli Zaretskii <eliz@gnu.org> * Makefile.in (LN_S): Define. (gdb-cfg.texi, gdb.dvi, links2roff, inc-hist.texinfo): Don't @@ -2037,7 +2318,7 @@ Fri Mar 24 17:56:48 2000 Andrew Cagney <cagney@b1.cygnus.com> <dima@Chg.RU>, also clarification of allowed content for string constants. -2000-03-16 Eli Zaretskii <eliz@is.elta.co.il> +2000-03-16 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (main menu): Add Annotations. (File Options): Add @cindex entries for each command-line option. @@ -2126,7 +2407,7 @@ Thu Oct 14 21:17:17 1999 Andrew Cagney <cagney@b1.cygnus.com> * gdb.texinfo: Fix uses of @multitable. - From Eli Zaretskii <eliz@is.elta.co.il>: + From Eli Zaretskii <eliz@gnu.org>: * gdb.texinfo: Include details specific to DOS host, clarify some confusing language, fix @ref/@xref/@pxref usages, add comments about using with optimization, add more indexing, @@ -2183,7 +2464,7 @@ Wed Aug 25 10:47:03 1999 Andrew Cagney <cagney@b1.cygnus.com> * gdbint.texinfo (Breakpoint Handling): Add missing words. -1999-08-10 Eli Zaretskii <eliz@is.elta.co.il> +1999-08-10 Eli Zaretskii <eliz@gnu.org> * gdb.texinfo (Set Watchpoints): Explain some subtleties about watch, awatch, and rwatch. Explain why the latter two cannot be diff --git a/gnu/usr.bin/binutils/gdb/doc/agentexpr.texi b/gnu/usr.bin/binutils/gdb/doc/agentexpr.texi index 6dbbdf483ab..152f148fa84 100644 --- a/gnu/usr.bin/binutils/gdb/doc/agentexpr.texi +++ b/gnu/usr.bin/binutils/gdb/doc/agentexpr.texi @@ -5,7 +5,7 @@ @c @setchapternewpage off @c %**end of header -@c Revision: $Id: agentexpr.texi,v 1.2 2004/05/21 20:23:27 kettenis Exp $ +@c Revision: $Id: agentexpr.texi,v 1.3 2004/12/27 14:00:51 kettenis Exp $ @node Agent Expressions @appendix The GDB Agent Expression Mechanism diff --git a/gnu/usr.bin/binutils/gdb/doc/gdb.texinfo b/gnu/usr.bin/binutils/gdb/doc/gdb.texinfo index 8e131520d68..6af8d37896b 100644 --- a/gnu/usr.bin/binutils/gdb/doc/gdb.texinfo +++ b/gnu/usr.bin/binutils/gdb/doc/gdb.texinfo @@ -38,9 +38,9 @@ @c This is a dir.info fragment to support semi-automated addition of @c manuals to an info tree. -@dircategory Programming & development tools. +@dircategory Software development @direntry -* Gdb: (gdb). The @sc{gnu} debugger. +* Gdb: (gdb). The GNU debugger. @end direntry @ifinfo @@ -1065,30 +1065,6 @@ that control @value{GDBN}, and level 2 has been deprecated. The annotation mechanism has largely been superseeded by @sc{gdb/mi} (@pxref{GDB/MI}). -@item -async -@cindex @code{--async} -Use the asynchronous event loop for the command-line interface. -@value{GDBN} processes all events, such as user keyboard input, via a -special event loop. This allows @value{GDBN} to accept and process user -commands in parallel with the debugged process being -run@footnote{@value{GDBN} built with @sc{djgpp} tools for -MS-DOS/MS-Windows supports this mode of operation, but the event loop is -suspended when the debuggee runs.}, so you don't need to wait for -control to return to @value{GDBN} before you type the next command. -(@emph{Note:} as of version 5.1, the target side of the asynchronous -operation is not yet in place, so @samp{-async} does not work fully -yet.) -@c FIXME: when the target side of the event loop is done, the above NOTE -@c should be removed. - -When the standard input is connected to a terminal device, @value{GDBN} -uses the asynchronous event loop by default, unless disabled by the -@samp{-noasync} option. - -@item -noasync -@cindex @code{--noasync} -Disable the asynchronous event loop for the command-line interface. - @item --args @cindex @code{--args} Change interpretation of command line so that arguments following the @@ -1685,6 +1661,7 @@ Some things do not work as well with @samp{-g -O} as with just @samp{-g}, particularly on machines with instruction scheduling. If in doubt, recompile with @samp{-g} alone, and if this fixes the problem, please report it to us as a bug (including a test case!). +@xref{Variables}, for more information about debugging optimized code. Older versions of the @sc{gnu} C compiler permitted a variant option @w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this @@ -1768,6 +1745,42 @@ time @value{GDBN} read its symbols, @value{GDBN} discards its symbol table, and reads it again. When it does this, @value{GDBN} tries to retain your current breakpoints. +@table @code +@kindex start +@item start +@cindex run to main procedure +The name of the main procedure can vary from language to language. +With C or C@t{++}, the main procedure name is always @code{main}, but +other languages such as Ada do not require a specific name for their +main procedure. The debugger provides a convenient way to start the +execution of the program and to stop at the beginning of the main +procedure, depending on the language used. + +The @samp{start} command does the equivalent of setting a temporary +breakpoint at the beginning of the main procedure and then invoking +the @samp{run} command. + +Some programs contain an elaboration phase where some startup code is +executed before the main program is called. This depends on the +languages used to write your program. In C@t{++} for instance, +constructors for static and global objects are executed before +@code{main} is called. It is therefore possible that the debugger stops +before reaching the main procedure. However, the temporary breakpoint +will remain to halt execution. + +Specify the arguments to give to your program as arguments to the +@samp{start} command. These arguments will be given verbatim to the +underlying @samp{run} command. Note that the same arguments will be +reused if no argument is provided during subsequent calls to +@samp{start} or @samp{run}. + +It is sometimes necessary to debug the program during elaboration. In +these cases, using the @code{start} command would stop the execution of +your program too late, as the program would have already completed the +elaboration phase. Under these circumstances, insert breakpoints in your +elaboration code before running your program. +@end table + @node Arguments @section Your program's arguments @@ -2162,8 +2175,8 @@ For example, On HP-UX systems: -@cindex thread number -@cindex thread identifier (GDB) +@cindex debugging multithreaded programs (on HP-UX) +@cindex thread identifier (GDB), on HP-UX For debugging purposes, @value{GDBN} associates its own thread number---a small integer assigned in thread-creation order---with each thread in your program. @@ -2187,7 +2200,7 @@ HP-UX, you see when @value{GDBN} notices a new thread. @table @code -@kindex info threads +@kindex info threads (HP-UX) @item info threads Display a summary of all threads currently in your program. @value{GDBN} displays for each thread (in this order): @@ -2239,7 +2252,6 @@ As with the @samp{[New @dots{}]} message, the form of the text after @samp{Switching to} depends on your system's conventions for identifying threads. -@kindex thread apply @item thread apply [@var{threadno}] [@var{all}] @var{args} The @code{thread apply} command allows you to apply a command to one or more threads. Specify the numbers of the threads that you want affected @@ -2578,10 +2590,19 @@ an @code{fo} followed by zero or more @code{o}s. There is an implicit @code{.*} leading and trailing the regular expression you supply, so to match only functions that begin with @code{foo}, use @code{^foo}. +@cindex non-member C@t{++} functions, set breakpoint in When debugging C@t{++} programs, @code{rbreak} is useful for setting breakpoints on overloaded functions that are not members of any special classes. +@cindex set breakpoints on all functions +The @code{rbreak} command can be used to set breakpoints in +@strong{all} the functions in a program, like this: + +@smallexample +(@value{GDBP}) rbreak . +@end smallexample + @kindex info breakpoints @cindex @code{$_} and @code{info breakpoints} @item info breakpoints @r{[}@var{n}@r{]} @@ -2862,34 +2883,30 @@ shared library. Use the @code{catch} command to set a catchpoint. Stop when @var{event} occurs. @var{event} can be any of the following: @table @code @item throw -@kindex catch throw +@cindex stop on C@t{++} exceptions The throwing of a C@t{++} exception. @item catch -@kindex catch catch The catching of a C@t{++} exception. @item exec -@kindex catch exec +@cindex break on fork/exec A call to @code{exec}. This is currently only available for HP-UX. @item fork -@kindex catch fork A call to @code{fork}. This is currently only available for HP-UX. @item vfork -@kindex catch vfork A call to @code{vfork}. This is currently only available for HP-UX. @item load @itemx load @var{libname} -@kindex catch load +@cindex break on load/unload of shared library The dynamic loading of any shared library, or the loading of the library @var{libname}. This is currently only available for HP-UX. @item unload @itemx unload @var{libname} -@kindex catch unload The unloading of any dynamically loaded shared library, or the unloading of the library @var{libname}. This is currently only available for HP-UX. @end table @@ -3002,8 +3019,7 @@ confirm off}). You can abbreviate this command as @code{d}. @node Disabling @subsection Disabling breakpoints -@kindex disable breakpoints -@kindex enable breakpoints +@cindex enable/disable a breakpoint Rather than deleting a breakpoint, watchpoint, or catchpoint, you might prefer to @dfn{disable} it. This makes the breakpoint inoperative as if it had been deleted, but remembers the information on the breakpoint so @@ -3037,7 +3053,6 @@ You can use the following commands to enable or disable breakpoints, watchpoints, and catchpoints: @table @code -@kindex disable breakpoints @kindex disable @kindex dis @r{(@code{disable})} @item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} @@ -3047,7 +3062,6 @@ options such as ignore-counts, conditions and commands are remembered in case the breakpoint is enabled again later. You may abbreviate @code{disable} as @code{dis}. -@kindex enable breakpoints @kindex enable @item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} Enable the specified breakpoints (or all defined breakpoints). They @@ -4046,7 +4060,6 @@ Similar, but print only the outermost @var{n} frames. @kindex where @kindex info stack -@kindex info s @r{(@code{info stack})} The names @code{where} and @code{info stack} (abbreviated @code{info s}) are additional aliases for @code{backtrace}. @@ -4076,11 +4089,6 @@ The display for frame zero does not begin with a program counter value, indicating that your program has stopped at the beginning of the code for line @code{993} of @code{builtin.c}. -@kindex set backtrace past-main -@kindex show backtrace past-main -@kindex set backtrace limit -@kindex show backtrace limit - Most programs have a standard user entry point---a place where system libraries and startup code transition into user code. For C this is @code{main}. When @value{GDBN} finds the entry function in a backtrace @@ -4093,6 +4101,7 @@ in a backtrace, you can change this behavior: @table @code @item set backtrace past-main @itemx set backtrace past-main on +@kindex set backtrace Backtraces will continue past the user entry point. @item set backtrace past-main off @@ -4100,6 +4109,7 @@ Backtraces will stop when they encounter the user entry point. This is the default. @item show backtrace past-main +@kindex show backtrace Display the current user entry point backtrace policy. @item set backtrace limit @var{n} @@ -4464,25 +4474,26 @@ following command-line syntax: @smallexample ex +@var{number} file @end smallexample -The optional numeric value +@var{number} designates the active line in -the file.}. By default, it is @value{EDITOR}, but you can change this +The optional numeric value +@var{number} specifies the number of the line in +the file where to start editing.}. +By default, it is @file{@value{EDITOR}}, but you can change this by setting the environment variable @code{EDITOR} before using @value{GDBN}. For example, to configure @value{GDBN} to use the @code{vi} editor, you could use these commands with the @code{sh} shell: @smallexample EDITOR=/usr/bin/vi export EDITOR -gdb ... +gdb @dots{} @end smallexample or in the @code{csh} shell, @smallexample setenv EDITOR /usr/bin/vi -gdb ... +gdb @dots{} @end smallexample @node Search @section Searching source files -@cindex searching +@cindex searching source files @kindex reverse-search There are two commands for searching through the current source file for a @@ -4517,16 +4528,30 @@ the directories could be moved between the compilation and your debugging session. @value{GDBN} has a list of directories to search for source files; this is called the @dfn{source path}. Each time @value{GDBN} wants a source file, it tries all the directories in the list, in the order they are present -in the list, until it finds a file with the desired name. Note that -the executable search path is @emph{not} used for this purpose. Neither is -the current working directory, unless it happens to be in the source -path. - -If @value{GDBN} cannot find a source file in the source path, and the -object program records a directory, @value{GDBN} tries that directory -too. If the source path is empty, and there is no record of the -compilation directory, @value{GDBN} looks in the current directory as a -last resort. +in the list, until it finds a file with the desired name. + +For example, suppose an executable references the file +@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is +@file{/mnt/cross}. The file is first looked up literally; if this +fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this +fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error +message is printed. @value{GDBN} does not look up the parts of the +source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}. +Likewise, the subdirectories of the source path are not searched: if +the source path is @file{/mnt/cross}, and the binary refers to +@file{foo.c}, @value{GDBN} would not find it under +@file{/mnt/cross/usr/src/foo-1.0/lib}. + +Plain file names, relative file names with leading directories, file +names containing dots, etc.@: are all treated as described above; for +instance, if the source path is @file{/mnt/cross}, and the source file +is recorded as @file{../lib/foo.c}, @value{GDBN} would first try +@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after +that---@file{/mnt/cross/foo.c}. + +Note that the executable search path is @emph{not} used to locate the +source files. Neither is the current working directory, unless it +happens to be in the source path. Whenever you reset or rearrange the source path, @value{GDBN} clears out any information it has cached about where source files are found and where @@ -4591,6 +4616,7 @@ directories in one command. @node Machine Code @section Source and machine code +@cindex source line and its code address You can use the command @code{info line} to map source lines to program addresses (and vice versa), and the command @code{disassemble} to display @@ -4620,6 +4646,7 @@ Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. @end smallexample @noindent +@cindex code address and its source line We can also inquire (using @code{*@var{addr}} as the form for @var{linespec}) what source line covers a particular address: @smallexample @@ -4628,6 +4655,7 @@ Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. @end smallexample @cindex @code{$_} and @code{info line} +@cindex @code{x} command, default address @kindex x@r{(examine), and} info line After @code{info line}, the default address for the @code{x} command is changed to the starting address of the line, so that @samp{x/i} is @@ -4673,10 +4701,6 @@ mnemonics or other syntax. @table @code @kindex set disassembly-flavor -@cindex assembly instructions -@cindex instructions, assembly -@cindex machine instructions -@cindex listing machine instructions @cindex Intel disassembly flavor @cindex AT&T disassembly flavor @item set disassembly-flavor @var{instruction-set} @@ -4717,6 +4741,7 @@ formats}. @item print @itemx print /@var{f} +@cindex reprint the last value If you omit @var{expr}, @value{GDBN} displays the last value again (from the @dfn{value history}; @pxref{Value History, ,Value history}). This allows you to conveniently inspect the same value in an alternative format. @@ -4763,6 +4788,7 @@ casts, and string constants. It also includes preprocessor macros, if you compiled your program to include this information; see @ref{Compilation}. +@cindex arrays in expressions @value{GDBN} supports array constants in expressions input by the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, you can use the command @code{print @{1, 2, 3@}} to build up an array in @@ -4776,6 +4802,7 @@ languages. In this section, we discuss operators that you can use in @value{GDBN} expressions regardless of your programming language. +@cindex casts, in expressions Casts are supported in all languages, not just in C, because it is so useful to cast a number into a pointer in order to examine a structure at that address in memory. @@ -4854,7 +4881,7 @@ in this file. But it is possible to have more than one such variable or function with the same name (in different source files). If that happens, referring to that name has unpredictable effects. If you wish, you can specify a static variable in a particular function or file, -using the colon-colon notation: +using the colon-colon (@code{::}) notation: @cindex colon-colon, context for variables/functions @iftex @@ -4885,6 +4912,8 @@ scope resolution operator in @value{GDBN} expressions. @cindex wrong values @cindex variable values, wrong +@cindex function entry/exit, wrong values of variables +@cindex optimized code, wrong values of variables @quotation @emph{Warning:} Occasionally, a local variable may appear to have the wrong value at certain points in a function---just after entry to a new @@ -4917,18 +4946,20 @@ No symbol "foo" in current context. To solve such problems, either recompile without optimizations, or use a different debug info format, if the compiler supports several such -formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler +formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler, usually supports the @option{-gstabs+} option. @option{-gstabs+} produces debug info in a format that is superior to formats such as COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also an effective form for debug info. @xref{Debugging Options,,Options for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}. - +@xref{C, , Debugging C++}, for more info about debug info formats +that are best suited to C@t{++} programs. @node Arrays @section Artificial arrays @cindex artificial array +@cindex arrays @kindex @@@r{, referencing memory as an array} It is often useful to print out several successive objects of the same type in memory; a section of an array, or an array of @@ -5261,6 +5292,7 @@ It also includes expressions which would not be displayed right now because they refer to automatic variables not currently available. @end table +@cindex display disabled out of scope If a display expression refers to local variables, then it does not make sense outside the lexical context for which it was set up. Such an expression is disabled when execution enters a context where one of its @@ -5284,9 +5316,10 @@ and symbols are printed. These settings are useful for debugging programs in any language: @table @code -@kindex set print address +@kindex set print @item set print address @itemx set print address on +@cindex print/don't print memory addresses @value{GDBN} prints memory addresses showing the location of stack traces, structure values, pointer values, breakpoints, and so forth, even when it also displays the contents of those addresses. The default @@ -5320,7 +5353,7 @@ dependent displays from the @value{GDBN} interface. For example, with @code{print address off}, you should get the same text for backtraces on all machines---whether or not they involve pointer arguments. -@kindex show print address +@kindex show print @item show print address Show whether or not addresses are to be printed. @end table @@ -5334,8 +5367,8 @@ you can set @value{GDBN} to print the source file and line number when it prints a symbolic address: @table @code -@kindex set print symbol-filename @item set print symbol-filename on +@cindex closest symbol and offset for an address Tell @value{GDBN} to print the source file name and line number of a symbol in the symbolic form of an address. @@ -5343,7 +5376,6 @@ symbol in the symbolic form of an address. Do not print source file name and line number of a symbol. This is the default. -@kindex show print symbol-filename @item show print symbol-filename Show whether or not @value{GDBN} will print the source file name and line number of a symbol in the symbolic form of an address. @@ -5357,14 +5389,13 @@ Also, you may wish to see the symbolic form only if the address being printed is reasonably close to the closest earlier symbol: @table @code -@kindex set print max-symbolic-offset @item set print max-symbolic-offset @var{max-offset} +@cindex maximum value for offset of closest symbol Tell @value{GDBN} to only display the symbolic form of an address if the offset between the closest earlier symbol and the address is less than @var{max-offset}. The default is 0, which tells @value{GDBN} to always print the symbolic form of an address if any symbol precedes it. -@kindex show print max-symbolic-offset @item show print max-symbolic-offset Ask how large the maximum offset is that @value{GDBN} prints in a symbolic address. @@ -5394,22 +5425,21 @@ the appropriate @code{set print} options turned on. Other settings control how different kinds of objects are printed: @table @code -@kindex set print array @item set print array @itemx set print array on +@cindex pretty print arrays Pretty print arrays. This format is more convenient to read, but uses more space. The default is off. @item set print array off Return to compressed format for arrays. -@kindex show print array @item show print array Show whether compressed or pretty format is selected for displaying arrays. -@kindex set print elements @item set print elements @var{number-of-elements} +@cindex number of array elements to print Set a limit on how many elements of an array @value{GDBN} will print. If @value{GDBN} is printing a large array, it stops printing after it has printed the number of elements set by the @code{set print elements} command. @@ -5417,19 +5447,17 @@ This limit also applies to the display of strings. When @value{GDBN} starts, this limit is set to 200. Setting @var{number-of-elements} to zero means that the printing is unlimited. -@kindex show print elements @item show print elements Display the number of elements of a large array that @value{GDBN} will print. If the number is 0, then the printing is unlimited. -@kindex set print null-stop @item set print null-stop +@cindex @sc{null} elements in arrays Cause @value{GDBN} to stop printing the characters of an array when the first @sc{null} is encountered. This is useful when large arrays actually contain only short strings. The default is off. -@kindex set print pretty @item set print pretty on Cause @value{GDBN} to print structures in an indented format with one member per line, like this: @@ -5460,12 +5488,12 @@ meat = 0x54 "Pork"@} @noindent This is the default format. -@kindex show print pretty @item show print pretty Show which format @value{GDBN} is using to print structures. -@kindex set print sevenbit-strings @item set print sevenbit-strings on +@cindex eight-bit characters in strings +@cindex octal escapes in strings Print using only seven-bit characters; if this option is set, @value{GDBN} displays any eight-bit characters (in strings or character values) using the notation @code{\}@var{nnn}. This setting is @@ -5476,19 +5504,17 @@ high-order bit of characters as a marker or ``meta'' bit. Print full eight-bit characters. This allows the use of more international character sets, and is the default. -@kindex show print sevenbit-strings @item show print sevenbit-strings Show whether or not @value{GDBN} is printing only seven-bit characters. -@kindex set print union @item set print union on +@cindex unions in structures, printing Tell @value{GDBN} to print unions which are contained in structures. This is the default setting. @item set print union off Tell @value{GDBN} not to print unions which are contained in structures. -@kindex show print union @item show print union Ask @value{GDBN} whether or not it will print unions which are contained in structures. @@ -5532,31 +5558,26 @@ $1 = @{it = Tree, form = @{...@}@} These settings are of interest when debugging C@t{++} programs: @table @code -@cindex demangling -@kindex set print demangle +@cindex demangling C@t{++} names @item set print demangle @itemx set print demangle on Print C@t{++} names in their source form rather than in the encoded (``mangled'') form passed to the assembler and linker for type-safe linkage. The default is on. -@kindex show print demangle @item show print demangle Show whether C@t{++} names are printed in mangled or demangled form. -@kindex set print asm-demangle @item set print asm-demangle @itemx set print asm-demangle on Print C@t{++} names in their source form rather than their mangled form, even in assembler code printouts such as instruction disassemblies. The default is off. -@kindex show print asm-demangle @item show print asm-demangle Show whether C@t{++} names in assembly listings are printed in mangled or demangled form. -@kindex set demangle-style @cindex C@t{++} symbol decoding style @cindex symbol decoding style, C@t{++} @item set demangle-style @var{style} @@ -5586,13 +5607,12 @@ require further enhancement to permit that. @end table If you omit @var{style}, you will see a list of possible formats. -@kindex show demangle-style @item show demangle-style Display the encoding style currently in use for decoding C@t{++} symbols. -@kindex set print object @item set print object @itemx set print object on +@cindex derived type of an object, printing When displaying a pointer to an object, identify the @emph{actual} (derived) type of the object rather than the @emph{declared} type, using the virtual function table. @@ -5601,26 +5621,24 @@ the virtual function table. Display only the declared type of objects, without reference to the virtual function table. This is the default setting. -@kindex show print object @item show print object Show whether actual, or declared, object types are displayed. -@kindex set print static-members @item set print static-members @itemx set print static-members on +@cindex static members of C@t{++} objects Print static members when displaying a C@t{++} object. The default is on. @item set print static-members off Do not print static members when displaying a C@t{++} object. -@kindex show print static-members @item show print static-members Show whether C@t{++} static members are printed, or not. @c These don't work with HP ANSI C++ yet. -@kindex set print vtbl @item set print vtbl @itemx set print vtbl on +@cindex pretty print C@t{++} virtual function tables Pretty print C@t{++} virtual function tables. The default is off. (The @code{vtbl} commands do not work on programs compiled with the HP ANSI C@t{++} compiler (@code{aCC}).) @@ -5628,7 +5646,6 @@ ANSI C@t{++} compiler (@code{aCC}).) @item set print vtbl off Do not pretty print C@t{++} virtual function tables. -@kindex show print vtbl @item show print vtbl Show whether C@t{++} virtual function tables are pretty printed, or not. @end table @@ -6292,7 +6309,7 @@ $ gdb -nw charset-test GNU gdb 2001-12-19-cvs Copyright 2001 Free Software Foundation, Inc. @dots{} -(gdb) +(@value{GDBP}) @end smallexample We can use the @code{show charset} command to see what character sets @@ -6300,18 +6317,18 @@ We can use the @code{show charset} command to see what character sets strings: @smallexample -(gdb) show charset +(@value{GDBP}) show charset The current host and target character set is `ISO-8859-1'. -(gdb) +(@value{GDBP}) @end smallexample For the sake of printing this manual, let's use @sc{ascii} as our initial character set: @smallexample -(gdb) set charset ASCII -(gdb) show charset +(@value{GDBP}) set charset ASCII +(@value{GDBP}) show charset The current host and target character set is `ASCII'. -(gdb) +(@value{GDBP}) @end smallexample Let's assume that @sc{ascii} is indeed the correct character set for our @@ -6321,20 +6338,20 @@ them properly. Since our current target character set is also @sc{ascii}, the contents of @code{ascii_hello} print legibly: @smallexample -(gdb) print ascii_hello +(@value{GDBP}) print ascii_hello $1 = 0x401698 "Hello, world!\n" -(gdb) print ascii_hello[0] +(@value{GDBP}) print ascii_hello[0] $2 = 72 'H' -(gdb) +(@value{GDBP}) @end smallexample @value{GDBN} uses the target character set for character and string literals you use in expressions: @smallexample -(gdb) print '+' +(@value{GDBP}) print '+' $3 = 43 '+' -(gdb) +(@value{GDBP}) @end smallexample The @sc{ascii} character set uses the number 43 to encode the @samp{+} @@ -6345,20 +6362,20 @@ target program uses. If we print @code{ibm1047_hello} while our target character set is still @sc{ascii}, we get jibberish: @smallexample -(gdb) print ibm1047_hello +(@value{GDBP}) print ibm1047_hello $4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" -(gdb) print ibm1047_hello[0] +(@value{GDBP}) print ibm1047_hello[0] $5 = 200 '\310' -(gdb) +(@value{GDBP}) @end smallexample If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} tells us the character sets it supports: @smallexample -(gdb) set target-charset +(@value{GDBP}) set target-charset ASCII EBCDIC-US IBM1047 ISO-8859-1 -(gdb) set target-charset +(@value{GDBP}) set target-charset @end smallexample We can select @sc{ibm1047} as our target character set, and examine the @@ -6368,28 +6385,28 @@ target character set, @sc{ibm1047}, to the host character set, @sc{ascii}, and they display correctly: @smallexample -(gdb) set target-charset IBM1047 -(gdb) show charset +(@value{GDBP}) set target-charset IBM1047 +(@value{GDBP}) show charset The current host character set is `ASCII'. The current target character set is `IBM1047'. -(gdb) print ascii_hello +(@value{GDBP}) print ascii_hello $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" -(gdb) print ascii_hello[0] +(@value{GDBP}) print ascii_hello[0] $7 = 72 '\110' -(gdb) print ibm1047_hello +(@value{GDBP}) print ibm1047_hello $8 = 0x4016a8 "Hello, world!\n" -(gdb) print ibm1047_hello[0] +(@value{GDBP}) print ibm1047_hello[0] $9 = 200 'H' -(gdb) +(@value{GDBP}) @end smallexample As above, @value{GDBN} uses the target character set for character and string literals you use in expressions: @smallexample -(gdb) print '+' +(@value{GDBP}) print '+' $10 = 78 '+' -(gdb) +(@value{GDBP}) @end smallexample The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} @@ -6439,9 +6456,9 @@ Show the results of expanding all preprocessor macro invocations in not parse the result, @var{expression} need not be a valid expression; it can be any string of tokens. -@kindex macro expand-once @item macro expand-once @var{expression} @itemx macro exp1 @var{expression} +@cindex expand macro once @i{(This command is not yet implemented.)} Show the results of expanding those preprocessor macro invocations that appear explicitly in @var{expression}. Macro invocations appearing in that expansion are @@ -6530,7 +6547,7 @@ $ gdb -nw sample GNU gdb 2002-05-06-cvs Copyright 2002 Free Software Foundation, Inc. GDB is free software, @dots{} -(gdb) +(@value{GDBP}) @end smallexample We can expand macros and examine their definitions, even when the @@ -6538,7 +6555,7 @@ program is not running. @value{GDBN} uses the current listing position to decide which macro definitions are in scope: @smallexample -(gdb) list main +(@value{GDBP}) list main 3 4 #define M 42 5 #define ADD(x) (M + x) @@ -6549,18 +6566,18 @@ to decide which macro definitions are in scope: 10 printf ("Hello, world!\n"); 11 #undef N 12 printf ("We're so creative.\n"); -(gdb) info macro ADD +(@value{GDBP}) info macro ADD Defined at /home/jimb/gdb/macros/play/sample.c:5 #define ADD(x) (M + x) -(gdb) info macro Q +(@value{GDBP}) info macro Q Defined at /home/jimb/gdb/macros/play/sample.h:1 included at /home/jimb/gdb/macros/play/sample.c:2 #define Q < -(gdb) macro expand ADD(1) +(@value{GDBP}) macro expand ADD(1) expands to: (42 + 1) -(gdb) macro expand-once ADD(1) +(@value{GDBP}) macro expand-once ADD(1) expands to: once (M + 1) -(gdb) +(@value{GDBP}) @end smallexample In the example above, note that @command{macro expand-once} expands only @@ -6572,27 +6589,27 @@ Once the program is running, GDB uses the macro definitions in force at the source line of the current stack frame: @smallexample -(gdb) break main +(@value{GDBP}) break main Breakpoint 1 at 0x8048370: file sample.c, line 10. -(gdb) run +(@value{GDBP}) run Starting program: /home/jimb/gdb/macros/play/sample Breakpoint 1, main () at sample.c:10 10 printf ("Hello, world!\n"); -(gdb) +(@value{GDBP}) @end smallexample At line 10, the definition of the macro @code{N} at line 9 is in force: @smallexample -(gdb) info macro N +(@value{GDBP}) info macro N Defined at /home/jimb/gdb/macros/play/sample.c:9 #define N 28 -(gdb) macro expand N Q M +(@value{GDBP}) macro expand N Q M expands to: 28 < 42 -(gdb) print N Q M +(@value{GDBP}) print N Q M $1 = 1 -(gdb) +(@value{GDBP}) @end smallexample As we step over directives that remove @code{N}'s definition, and then @@ -6600,23 +6617,23 @@ give it a new definition, @value{GDBN} finds the definition (or lack thereof) in force at each point: @smallexample -(gdb) next +(@value{GDBP}) next Hello, world! 12 printf ("We're so creative.\n"); -(gdb) info macro N +(@value{GDBP}) info macro N The symbol `N' has no definition as a C/C++ preprocessor macro at /home/jimb/gdb/macros/play/sample.c:12 -(gdb) next +(@value{GDBP}) next We're so creative. 14 printf ("Goodbye, world!\n"); -(gdb) info macro N +(@value{GDBP}) info macro N Defined at /home/jimb/gdb/macros/play/sample.c:13 #define N 1729 -(gdb) macro expand N Q M +(@value{GDBP}) macro expand N Q M expands to: 1729 < 42 -(gdb) print N Q M +(@value{GDBP}) print N Q M $2 = 0 -(gdb) +(@value{GDBP}) @end smallexample @@ -7414,14 +7431,13 @@ you can abbreviate this as @code{ov} or @code{ovly}. The commands are: @table @code @item overlay off -@kindex overlay off +@kindex overlay Disable @value{GDBN}'s overlay support. When overlay support is disabled, @value{GDBN} assumes that all functions and variables are always present at their mapped addresses. By default, @value{GDBN}'s overlay support is disabled. @item overlay manual -@kindex overlay manual @cindex manual overlay debugging Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN} relies on you to tell it which overlays are mapped, and which are not, @@ -7430,7 +7446,6 @@ commands described below. @item overlay map-overlay @var{overlay} @itemx overlay map @var{overlay} -@kindex overlay map-overlay @cindex map an overlay Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must be the name of the object file section containing the overlay. When an @@ -7441,7 +7456,6 @@ that any other overlays whose mapped ranges overlap that of @item overlay unmap-overlay @var{overlay} @itemx overlay unmap @var{overlay} -@kindex overlay unmap-overlay @cindex unmap an overlay Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay} must be the name of the object file section containing the overlay. @@ -7449,7 +7463,6 @@ When an overlay is unmapped, @value{GDBN} assumes it can find the overlay's functions and variables at their load addresses. @item overlay auto -@kindex overlay auto Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN} consults a data structure the overlay manager maintains in the inferior to see which overlays are mapped. For details, see @ref{Automatic @@ -7457,7 +7470,6 @@ Overlay Debugging}. @item overlay load-target @itemx overlay load -@kindex overlay load-target @cindex reloading the overlay table Re-read the overlay table from the inferior. Normally, @value{GDBN} re-reads the table @value{GDBN} automatically each time the inferior @@ -7477,7 +7489,7 @@ Normally, when @value{GDBN} prints a code address, it includes the name of the function the address falls in: @smallexample -(gdb) print main +(@value{GDBP}) print main $3 = @{int ()@} 0x11a0 <main> @end smallexample @noindent @@ -7487,9 +7499,9 @@ asterisks around them. For example, if @code{foo} is a function in an unmapped overlay, @value{GDBN} prints it this way: @smallexample -(gdb) overlay list +(@value{GDBP}) overlay list No sections are mapped. -(gdb) print foo +(@value{GDBP}) print foo $5 = @{int (int)@} 0x100000 <*foo*> @end smallexample @noindent @@ -7497,10 +7509,10 @@ When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's name normally: @smallexample -(gdb) overlay list +(@value{GDBP}) overlay list Section .ov.foo.text, loaded at 0x100000 - 0x100034, mapped at 0x1016 - 0x104a -(gdb) print foo +(@value{GDBP}) print foo $6 = @{int (int)@} 0x1016 <foo> @end smallexample @@ -7705,6 +7717,11 @@ If a source file name ends in one of the following extensions, then @value{GDBN} infers that its language is the one indicated. @table @file +@item .ada +@itemx .ads +@itemx .adb +@itemx .a +Ada source file. @item .c C source file @@ -7794,8 +7811,6 @@ The following commands help you find out which language is the working language, and also what language source files were written in. @kindex show language -@kindex info frame@r{, show the source language} -@kindex info source@r{, show the source language} @table @code @item show language Display the current working language. This is the @@ -7803,12 +7818,14 @@ language you can use with commands such as @code{print} to build and compute expressions that may involve variables in your program. @item info frame +@kindex info frame@r{, show the source language} Display the source language for this frame. This language becomes the working language if you use an identifier from this frame. @xref{Frame Info, ,Information about a frame}, to identify the other information listed here. @item info source +@kindex info source@r{, show the source language} Display the source language of this source file. @xref{Symbols, ,Examining the Symbol Table}, to identify the other information listed here. @@ -7903,7 +7920,6 @@ details on specific languages. @value{GDBN} provides some additional commands for controlling the type checker: -@kindex set check@r{, type} @kindex set check type @kindex show check type @table @code @@ -7964,7 +7980,6 @@ Supported languages}, for further details on specific languages. @value{GDBN} provides some additional commands for controlling the range checker: -@kindex set check@r{, range} @kindex set check range @kindex show check range @table @code @@ -7995,7 +8010,7 @@ being set automatically by @value{GDBN}. @node Support @section Supported languages -@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, and Modula-2. +@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, Modula-2, and Ada. @c This is false ... Some @value{GDBN} features may be used in expressions regardless of the language you use: the @value{GDBN} @code{@@} and @code{::} operators, @@ -8015,6 +8030,7 @@ language reference or tutorial. * C:: C and C@t{++} * Objective-C:: Objective-C * Modula-2:: Modula-2 +* Ada:: Ada @end menu @node C @@ -8630,7 +8646,7 @@ 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 +@node Modula-2, Ada, Objective-C, Support @subsection Modula-2 @cindex Modula-2, @value{GDBN} support @@ -9073,6 +9089,341 @@ address can be specified by an integral constant, the construct In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is interpreted as the beginning of a comment. Use @code{<>} instead. +@node Ada +@subsection Ada +@cindex Ada + +The extensions made to @value{GDBN} for Ada only support +output from the @sc{gnu} Ada (GNAT) compiler. +Other Ada compilers are not currently supported, and +attempting to debug executables produced by them is most likely +to be difficult. + + +@cindex expressions in Ada +@menu +* Ada Mode Intro:: General remarks on the Ada syntax + and semantics supported by Ada mode + in @value{GDBN}. +* Omissions from Ada:: Restrictions on the Ada expression syntax. +* Additions to Ada:: Extensions of the Ada expression syntax. +* Stopping Before Main Program:: Debugging the program during elaboration. +* Ada Glitches:: Known peculiarities of Ada mode. +@end menu + +@node Ada Mode Intro +@subsubsection Introduction +@cindex Ada mode, general + +The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression +syntax, with some extensions. +The philosophy behind the design of this subset is + +@itemize @bullet +@item +That @value{GDBN} should provide basic literals and access to operations for +arithmetic, dereferencing, field selection, indexing, and subprogram calls, +leaving more sophisticated computations to subprograms written into the +program (which therefore may be called from @value{GDBN}). + +@item +That type safety and strict adherence to Ada language restrictions +are not particularly important to the @value{GDBN} user. + +@item +That brevity is important to the @value{GDBN} user. +@end itemize + +Thus, for brevity, the debugger acts as if there were +implicit @code{with} and @code{use} clauses in effect for all user-written +packages, making it unnecessary to fully qualify most names with +their packages, regardless of context. Where this causes ambiguity, +@value{GDBN} asks the user's intent. + +The debugger will start in Ada mode if it detects an Ada main program. +As for other languages, it will enter Ada mode when stopped in a program that +was translated from an Ada source file. + +While in Ada mode, you may use `@t{--}' for comments. This is useful +mostly for documenting command files. The standard @value{GDBN} comment +(@samp{#}) still works at the beginning of a line in Ada mode, but not in the +middle (to allow based literals). + +The debugger supports limited overloading. Given a subprogram call in which +the function symbol has multiple definitions, it will use the number of +actual parameters and some information about their types to attempt to narrow +the set of definitions. It also makes very limited use of context, preferring +procedures to functions in the context of the @code{call} command, and +functions to procedures elsewhere. + +@node Omissions from Ada +@subsubsection Omissions from Ada +@cindex Ada, omissions from + +Here are the notable omissions from the subset: + +@itemize @bullet +@item +Only a subset of the attributes are supported: + +@itemize @minus +@item +@t{'First}, @t{'Last}, and @t{'Length} + on array objects (not on types and subtypes). + +@item +@t{'Min} and @t{'Max}. + +@item +@t{'Pos} and @t{'Val}. + +@item +@t{'Tag}. + +@item +@t{'Range} on array objects (not subtypes), but only as the right +operand of the membership (@code{in}) operator. + +@item +@t{'Access}, @t{'Unchecked_Access}, and +@t{'Unrestricted_Access} (a GNAT extension). + +@item +@t{'Address}. +@end itemize + +@item +The names in +@code{Characters.Latin_1} are not available and +concatenation is not implemented. Thus, escape characters in strings are +not currently available. + +@item +Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise +equality of representations. They will generally work correctly +for strings and arrays whose elements have integer or enumeration types. +They may not work correctly for arrays whose element +types have user-defined equality, for arrays of real values +(in particular, IEEE-conformant floating point, because of negative +zeroes and NaNs), and for arrays whose elements contain unused bits with +indeterminate values. + +@item +The other component-by-component array operations (@code{and}, @code{or}, +@code{xor}, @code{not}, and relational tests other than equality) +are not implemented. + +@item +There are no record or array aggregates. + +@item +Calls to dispatching subprograms are not implemented. + +@item +The overloading algorithm is much more limited (i.e., less selective) +than that of real Ada. It makes only limited use of the context in which a subexpression +appears to resolve its meaning, and it is much looser in its rules for allowing +type matches. As a result, some function calls will be ambiguous, and the user +will be asked to choose the proper resolution. + +@item +The @code{new} operator is not implemented. + +@item +Entry calls are not implemented. + +@item +Aside from printing, arithmetic operations on the native VAX floating-point +formats are not supported. + +@item +It is not possible to slice a packed array. +@end itemize + +@node Additions to Ada +@subsubsection Additions to Ada +@cindex Ada, deviations from + +As it does for other languages, @value{GDBN} makes certain generic +extensions to Ada (@pxref{Expressions}): + +@itemize @bullet +@item +If the expression @var{E} is a variable residing in memory +(typically a local variable or array element) and @var{N} is +a positive integer, then @code{@var{E}@@@var{N}} displays the values of +@var{E} and the @var{N}-1 adjacent variables following it in memory as an array. +In Ada, this operator is generally not necessary, since its prime use +is in displaying parts of an array, and slicing will usually do this in Ada. +However, there are occasional uses when debugging programs +in which certain debugging information has been optimized away. + +@item +@code{@var{B}::@var{var}} means ``the variable named @var{var} that appears +in function or file @var{B}.'' When @var{B} is a file name, you must typically +surround it in single quotes. + +@item +The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type +@var{type} that appears at address @var{addr}.'' + +@item +A name starting with @samp{$} is a convenience variable +(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}). +@end itemize + +In addition, @value{GDBN} provides a few other shortcuts and outright additions specific +to Ada: + +@itemize @bullet +@item +The assignment statement is allowed as an expression, returning +its right-hand operand as its value. Thus, you may enter + +@smallexample +set x := y + 3 +print A(tmp := y + 1) +@end smallexample + +@item +The semicolon is allowed as an ``operator,'' returning as its value +the value of its right-hand operand. +This allows, for example, +complex conditional breaks: + +@smallexample +break f +condition 1 (report(i); k += 1; A(k) > 100) +@end smallexample + +@item +Rather than use catenation and symbolic character names to introduce special +characters into strings, one may instead use a special bracket notation, +which is also used to print strings. A sequence of characters of the form +@samp{["@var{XX}"]} within a string or character literal denotes the +(single) character whose numeric encoding is @var{XX} in hexadecimal. The +sequence of characters @samp{["""]} also denotes a single quotation mark +in strings. For example, +@smallexample + "One line.["0a"]Next line.["0a"]" +@end smallexample +@noindent +contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) after each +period. + +@item +The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and +@t{'Max} is optional (and is ignored in any case). For example, it is valid +to write + +@smallexample +print 'max(x, y) +@end smallexample + +@item +When printing arrays, @value{GDBN} uses positional notation when the +array has a lower bound of 1, and uses a modified named notation otherwise. +For example, a one-dimensional array of three integers with a lower bound of 3 might print as + +@smallexample +(3 => 10, 17, 1) +@end smallexample + +@noindent +That is, in contrast to valid Ada, only the first component has a @code{=>} +clause. + +@item +You may abbreviate attributes in expressions with any unique, +multi-character subsequence of +their names (an exact match gets preference). +For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh} +in place of @t{a'length}. + +@item +@cindex quoting Ada internal identifiers +Since Ada is case-insensitive, the debugger normally maps identifiers you type +to lower case. The GNAT compiler uses upper-case characters for +some of its internal identifiers, which are normally of no interest to users. +For the rare occasions when you actually have to look at them, +enclose them in angle brackets to avoid the lower-case mapping. +For example, +@smallexample +@value{GDBP} print <JMPBUF_SAVE>[0] +@end smallexample + +@item +Printing an object of class-wide type or dereferencing an +access-to-class-wide value will display all the components of the object's +specific type (as indicated by its run-time tag). Likewise, component +selection on such a value will operate on the specific type of the +object. + +@end itemize + +@node Stopping Before Main Program +@subsubsection Stopping at the Very Beginning + +@cindex breakpointing Ada elaboration code +It is sometimes necessary to debug the program during elaboration, and +before reaching the main procedure. +As defined in the Ada Reference +Manual, the elaboration code is invoked from a procedure called +@code{adainit}. To run your program up to the beginning of +elaboration, simply use the following two commands: +@code{tbreak adainit} and @code{run}. + +@node Ada Glitches +@subsubsection Known Peculiarities of Ada Mode +@cindex Ada, problems + +Besides the omissions listed previously (@pxref{Omissions from Ada}), +we know of several problems with and limitations of Ada mode in +@value{GDBN}, +some of which will be fixed with planned future releases of the debugger +and the GNU Ada compiler. + +@itemize @bullet +@item +Currently, the debugger +has insufficient information to determine whether certain pointers represent +pointers to objects or the objects themselves. +Thus, the user may have to tack an extra @code{.all} after an expression +to get it printed properly. + +@item +Static constants that the compiler chooses not to materialize as objects in +storage are invisible to the debugger. + +@item +Named parameter associations in function argument lists are ignored (the +argument lists are treated as positional). + +@item +Many useful library packages are currently invisible to the debugger. + +@item +Fixed-point arithmetic, conversions, input, and output is carried out using +floating-point arithmetic, and may give results that only approximate those on +the host machine. + +@item +The type of the @t{'Address} attribute may not be @code{System.Address}. + +@item +The GNAT compiler never generates the prefix @code{Standard} for any of +the standard symbols defined by the Ada language. @value{GDBN} knows about +this: it will strip the prefix from names when you use it, and will never +look for a name you have so qualified among local symbols, nor match against +symbols in other packages or subprograms. If you have +defined entities anywhere in your program other than parameters and +local variables whose simple names match names in @code{Standard}, +GNAT's lack of qualification here can cause confusion. When this happens, +you can usually resolve the confusion +by qualifying the problematic names with package +@code{Standard} explicitly. +@end itemize + @node Unsupported languages @section Unsupported languages @@ -9888,9 +10239,9 @@ symbol table. It cannot be shared across multiple host platforms. @c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol @c files. -@kindex core @kindex core-file @item core-file @r{[} @var{filename} @r{]} +@itemx core Specify the whereabouts of a core dump file to be used as the ``contents of memory''. Traditionally, core files contain only some parts of the address space of the process that generated them; @value{GDBN} can access the @@ -10308,7 +10659,7 @@ polynomials, reversals, byte ordering, etc.), the simplest way to describe the CRC used in @code{.gnu_debuglink} sections is to give the complete code for a function that computes it: -@kindex @code{gnu_debuglink_crc32} +@kindex gnu_debuglink_crc32 @smallexample unsigned long gnu_debuglink_crc32 (unsigned long crc, @@ -10580,22 +10931,24 @@ Use the @code{show gnutarget} command to display what file format and @code{show gnutarget} displays @samp{The current BDF target is "auto"}. @end table +@cindex common targets Here are some common targets (available, or not, depending on the GDB configuration): @table @code -@kindex target exec +@kindex target @item target exec @var{program} +@cindex executable file target An executable file. @samp{target exec @var{program}} is the same as @samp{exec-file @var{program}}. -@kindex target core @item target core @var{filename} +@cindex core dump file target A core dump file. @samp{target core @var{filename}} is the same as @samp{core-file @var{filename}}. -@kindex target remote @item target remote @var{dev} +@cindex remote target Remote serial target in GDB-specific protocol. The argument @var{dev} specifies what serial device to use for the connection (e.g. @file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote} @@ -10603,8 +10956,8 @@ supports the @code{load} command. This is only useful if you have some other way of getting the stub to the target system, and you can put it somewhere in memory where it won't get clobbered by the download. -@kindex target sim @item target sim +@cindex built-in simulator target Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. In general, @smallexample @@ -10625,8 +10978,8 @@ Some configurations may include these targets as well: @table @code -@kindex target nrom @item target nrom @var{dev} +@cindex NetROM ROM emulator target NetROM ROM emulator. This target only supports downloading. @end table @@ -10675,15 +11028,13 @@ which to use. However, you may still find it useful to adjust @value{GDBN}'s idea of processor endian-ness manually. @table @code -@kindex set endian big +@kindex set endian @item set endian big Instruct @value{GDBN} to assume the target is big-endian. -@kindex set endian little @item set endian little Instruct @value{GDBN} to assume the target is little-endian. -@kindex set endian auto @item set endian auto Instruct @value{GDBN} to use the byte order associated with the executable. @@ -11156,14 +11507,14 @@ subroutines: @table @code @item set_debug_traps -@kindex set_debug_traps +@findex set_debug_traps @cindex remote serial stub, initialization This routine arranges for @code{handle_exception} to run when your program stops. You must call this subroutine explicitly near the beginning of your program. @item handle_exception -@kindex handle_exception +@findex handle_exception @cindex remote serial stub, main routine This is the central workhorse, but your program never calls it explicitly---the setup code arranges for @code{handle_exception} to @@ -11211,13 +11562,13 @@ serial port. @table @code @item int getDebugChar() -@kindex getDebugChar +@findex getDebugChar Write this subroutine to read a single character from the serial port. It may be identical to @code{getchar} for your target system; a different name is used to allow you to distinguish the two if you wish. @item void putDebugChar(int) -@kindex putDebugChar +@findex putDebugChar Write this subroutine to write a single character to the serial port. It may be identical to @code{putchar} for your target system; a different name is used to allow you to distinguish the two if you wish. @@ -11240,7 +11591,7 @@ Other routines you need to supply are: @table @code @item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) -@kindex exceptionHandler +@findex exceptionHandler Write this function to install @var{exception_address} in the exception handling tables. You need to do this because the stub does not have any way of knowing what the exception handling tables on your target system @@ -11262,7 +11613,7 @@ should be at privilege level 0 (the most privileged level). The help from @code{exceptionHandler}. @item void flush_i_cache() -@kindex flush_i_cache +@findex flush_i_cache On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the instruction cache, if any, on your target machine. If there is no instruction cache, this subroutine may be a no-op. @@ -11276,7 +11627,7 @@ You must also make sure this library routine is available: @table @code @item void *memset(void *, int, int) -@kindex memset +@findex memset This is the standard library function @code{memset} that sets an area of memory to a known value. If you have one of the free versions of @code{libc.a}, @code{memset} can be found there; otherwise, you must @@ -11376,6 +11727,7 @@ configurations. @menu * HP-UX:: HP-UX +* BSD libkvm Interface:: Debugging BSD kernel memory images * SVR4 Process Information:: SVR4 process information * DJGPP Native:: Features specific to the DJGPP port * Cygwin Native:: Features specific to the Cygwin port @@ -11388,6 +11740,46 @@ On HP-UX systems, if you refer to a function or variable name that begins with a dollar sign, @value{GDBN} searches for a user or system name first, before it searches for a convenience variable. +@node BSD libkvm Interface +@subsection BSD libkvm Interface + +@cindex libkvm +@cindex kernel memory image +@cindex kernel crash dump + +BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory +interface that provides a uniform interface for accessing kernel virtual +memory images, including live systems and crash dumps. @value{GDBN} +uses this interface to allow you to debug live kernels and kernel crash +dumps on many native BSD configurations. This is implemented as a +special @code{kvm} debugging target. For debugging a live system, load +the currently running kernel into @value{GDBN} and connect to the +@code{kvm} target: + +@smallexample +(@value{GDBP}) @b{target kvm} +@end smallexample + +For debugging crash dumps, provide the file name of the crash dump as an +argument: + +@smallexample +(@value{GDBP}) @b{target kvm /var/crash/bsd.0} +@end smallexample + +Once connected to the @code{kvm} target, the following commands are +available: + +@table @code +@kindex kvm +@item kvm pcb +Set current context from pcb address. + +@item kvm proc +Set current context from proc address. This command isn't available on +modern FreeBSD systems. +@end table + @node SVR4 Process Information @subsection SVR4 process information @@ -11714,7 +12106,7 @@ some confusion. If in doubt, try the @code{info functions} and @pxref{Symbols}). Here's an example: @smallexample -(gdb) info function CreateFileA +(@value{GDBP}) info function CreateFileA All functions matching regular expression "CreateFileA": Non-debugging symbols: @@ -11723,7 +12115,7 @@ Non-debugging symbols: @end smallexample @smallexample -(gdb) info function ! +(@value{GDBP}) info function ! All functions matching regular expression "!": Non-debugging symbols: @@ -11750,28 +12142,28 @@ type information in the command. Here's an example of the type of problem: @smallexample -(gdb) print 'cygwin1!__argv' +(@value{GDBP}) print 'cygwin1!__argv' $1 = 268572168 @end smallexample @smallexample -(gdb) x 'cygwin1!__argv' +(@value{GDBP}) x 'cygwin1!__argv' 0x10021610: "\230y\"" @end smallexample And two possible solutions: @smallexample -(gdb) print ((char **)'cygwin1!__argv')[0] +(@value{GDBP}) print ((char **)'cygwin1!__argv')[0] $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" @end smallexample @smallexample -(gdb) x/2x &'cygwin1!__argv' +(@value{GDBP}) x/2x &'cygwin1!__argv' 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 -(gdb) x/x 0x10021608 +(@value{GDBP}) x/x 0x10021608 0x10021608: 0x0022fd98 -(gdb) x/s 0x0022fd98 +(@value{GDBP}) x/s 0x0022fd98 0x22fd98: "/cygdrive/c/mydirectory/myprogram" @end smallexample @@ -11782,7 +12174,7 @@ function's frame set-up code. You can work around this by using ``*&'' to set the breakpoint at a raw memory address: @smallexample -(gdb) break *&'python22!PyOS_Readline' +(@value{GDBP}) break *&'python22!PyOS_Readline' Breakpoint 1 at 0x1e04eff0 @end smallexample @@ -11843,7 +12235,7 @@ The following information on connecting to VxWorks was current when this manual was produced; newer releases of VxWorks may use revised procedures. -@kindex INCLUDE_RDB +@findex INCLUDE_RDB To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel to include the remote debugging interface routines in the VxWorks library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the @@ -12503,49 +12895,39 @@ or Data. For example: @code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)} -@kindex htrace info +@kindex htrace @item htrace info Display information about current HW trace configuration. -@kindex htrace trigger @item htrace trigger @var{conditional} Set starting criteria for HW trace. -@kindex htrace qualifier @item htrace qualifier @var{conditional} Set acquisition qualifier for HW trace. -@kindex htrace stop @item htrace stop @var{conditional} Set HW trace stopping criteria. -@kindex htrace record @item htrace record [@var{data}]* Selects the data to be recorded, when qualifier is met and HW trace was triggered. -@kindex htrace enable @item htrace enable -@kindex htrace disable @itemx htrace disable Enables/disables the HW trace. -@kindex htrace rewind @item htrace rewind [@var{filename}] Clears currently recorded trace data. If filename is specified, new trace file is made and any newly collected data will be written there. -@kindex htrace print @item htrace print [@var{start} [@var{len}]] Prints trace buffer, using current record configuration. -@kindex htrace mode continuous @item htrace mode continuous Set continuous trace mode. -@kindex htrace mode suspend @item htrace mode suspend Set suspend trace mode. @@ -13001,7 +13383,7 @@ Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} @cindex readline @cindex command line editing -@value{GDBN} reads its input commands via the @dfn{readline} interface. This +@value{GDBN} reads its input commands via the @dfn{Readline} interface. This @sc{gnu} library provides consistent behavior for programs which provide a command line interface to the user. Advantages are @sc{gnu} Emacs-style or @dfn{vi}-style inline editing of commands, @code{csh}-like history @@ -13026,19 +13408,31 @@ Disable command line editing. Show whether command line editing is enabled. @end table +@xref{Command Line Editing}, for more details about the Readline +interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are +encouraged to read that chapter. + @node History @section Command history +@cindex command history @value{GDBN} can keep track of the commands you type during your debugging sessions, so that you can be certain of precisely what happened. Use these commands to manage the @value{GDBN} command history facility. +@value{GDBN} uses the @sc{gnu} History library, a part of the Readline +package, to provide the history facility. @xref{Using History +Interactively}, for the detailed description of the History library. + +Here is the description of @value{GDBN} commands related to command +history. + @table @code @cindex history substitution @cindex history file @kindex set history filename -@kindex GDBHISTFILE +@cindex @env{GDBHISTFILE}, environment variable @item set history filename @var{fname} Set the name of the @value{GDBN} command history file to @var{fname}. This is the file where @value{GDBN} reads an initial command history @@ -13050,7 +13444,7 @@ to the value of the environment variable @code{GDBHISTFILE}, or to is not set. @cindex history save -@kindex set history save +@kindex set history @item set history save @itemx set history save on Record command history in a file, whose name may be specified with the @@ -13060,19 +13454,16 @@ Record command history in a file, whose name may be specified with the Stop recording command history in a file. @cindex history size -@kindex set history size @item set history size @var{size} Set the number of commands which @value{GDBN} keeps in its history list. This defaults to the value of the environment variable @code{HISTSIZE}, or to 256 if this variable is not set. @end table -@cindex history expansion History expansion assigns special meaning to the character @kbd{!}. -@ifset have-readline-appendices -@xref{Event Designators}. -@end ifset +@xref{Event Designators}, for more details. +@cindex history expansion, turn on/off Since @kbd{!} is also the logical not operator in C, history expansion is off by default. If you decide to enable history expansion with the @code{set history expansion on} command, you may sometimes need to @@ -13084,21 +13475,14 @@ history facilities do not attempt substitution on the strings The commands to control history expansion are: @table @code -@kindex set history expansion @item set history expansion on @itemx set history expansion +@kindex set history expansion Enable history expansion. History expansion is off by default. @item set history expansion off Disable history expansion. -The readline code comes with more complete documentation of -editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs -or @code{vi} may wish to read it. -@ifset have-readline-appendices -@xref{Command Line Editing}. -@end ifset - @c @group @kindex show history @item show history @@ -13373,78 +13757,79 @@ Displays state of confirmation requests. @node Debugging Output @section Optional messages about internal happenings +@cindex optional debugging messages + @table @code -@kindex set debug arch +@kindex set debug +@cindex gdbarch debugging info @item set debug arch Turns on or off display of gdbarch debugging info. The default is off -@kindex show debug arch +@kindex show debug @item show debug arch Displays the current state of displaying gdbarch debugging info. -@kindex set debug event @item set debug event +@cindex event debugging info Turns on or off display of @value{GDBN} event debugging info. The default is off. -@kindex show debug event @item show debug event Displays the current state of displaying @value{GDBN} event debugging info. -@kindex set debug expression @item set debug expression +@cindex expression debugging info Turns on or off display of @value{GDBN} expression debugging info. The default is off. -@kindex show debug expression @item show debug expression Displays the current state of displaying @value{GDBN} expression debugging info. -@kindex set debug frame @item set debug frame +@cindex frame debugging info Turns on or off display of @value{GDBN} frame debugging info. The default is off. -@kindex show debug frame @item show debug frame Displays the current state of displaying @value{GDBN} frame debugging info. -@kindex set debug overload +@item set debug observer +@cindex observer debugging info +Turns on or off display of @value{GDBN} observer debugging. This +includes info such as the notification of observable events. +@item show debug observer +Displays the current state of observer debugging. @item set debug overload +@cindex C@t{++} overload debugging info Turns on or off display of @value{GDBN} C@t{++} overload debugging info. This includes info such as ranking of functions, etc. The default is off. -@kindex show debug overload @item show debug overload Displays the current state of displaying @value{GDBN} C@t{++} overload debugging info. -@kindex set debug remote @cindex packets, reporting on stdout @cindex serial connections, debugging @item set debug remote Turns on or off display of reports on all packets sent back and forth across the serial line to the remote machine. The info is printed on the @value{GDBN} standard output stream. The default is off. -@kindex show debug remote @item show debug remote Displays the state of display of remote packets. -@kindex set debug serial @item set debug serial Turns on or off display of @value{GDBN} serial debugging info. The default is off. -@kindex show debug serial @item show debug serial Displays the current state of displaying @value{GDBN} serial debugging info. -@kindex set debug target @item set debug target +@cindex target debugging info 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. -@kindex show debug target +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. @item show debug target Displays the current state of displaying @value{GDBN} target debugging info. -@kindex set debug varobj @item set debug varobj +@cindex variable object debugging info Turns on or off display of @value{GDBN} variable object debugging info. The default is off. -@kindex show debug varobj @item show debug varobj Displays the current state of displaying @value{GDBN} variable object debugging info. @@ -13573,7 +13958,6 @@ messages when used in a user-defined command. @cindex hooks, pre-command @kindex hook -@kindex hook- You may define @dfn{hooks}, which are a special kind of user-defined command. Whenever you run the command @samp{foo}, if the user-defined command @samp{hook-foo} exists, it is executed (with no arguments) @@ -13581,7 +13965,6 @@ before that command. @cindex hooks, post-command @kindex hookpost -@kindex hookpost- A hook may also be defined which is run after the command you executed. Whenever you run the command @samp{foo}, if the user-defined command @samp{hookpost-foo} exists, it is executed (with no arguments) after @@ -14202,27 +14585,22 @@ in the TUI mode. List and give the size of all displayed windows. @item layout next -@kindex layout next +@kindex layout Display the next layout. @item layout prev -@kindex layout prev Display the previous layout. @item layout src -@kindex layout src Display the source window only. @item layout asm -@kindex layout asm Display the assembly window only. @item layout split -@kindex layout split Display the source and assembly window. @item layout regs -@kindex layout regs Display the register window together with the source or assembly window. @item focus next | prev | src | asm | regs | split @@ -14643,7 +15021,7 @@ corresponding output for that command will also be prefixed by that same @table @code @item @var{output} @expansion{} -@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} +@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}} @item @var{result-record} @expansion{} @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} @@ -16803,14 +17181,24 @@ There's no @value{GDBN} command which directly corresponds to this one. List the source files for the current executable. +It will always output the filename, but only when GDB can find the absolute +file name of a source file, will it output the fullname. + @subsubheading @value{GDBN} Command There's no @value{GDBN} command which directly corresponds to this one. @code{gdbtk} has an analogous command @samp{gdb_listfiles}. @subsubheading Example -N.A. - +@smallexample +(@value{GDBP}) +-file-list-exec-source-files +^done,files=[ +@{file=foo.c,fullname=/home/foo.c@}, +@{file=/home/bar.c,fullname=/home/bar.c@}, +@{file=gdb_could_not_find_fullpath.c@}] +(@value{GDBP}) +@end smallexample @subheading The @code{-file-list-shared-libraries} Command @findex -file-list-shared-libraries @@ -18496,7 +18884,7 @@ for details. This GDB was configured as "i386-pc-linux-gnu" ^Z^Zpre-prompt -(gdb) +(@value{GDBP}) ^Z^Zprompt @kbd{quit} @@ -18905,6 +19293,16 @@ ours fails to crash, we would know that the bug was not happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations. +@pindex script +@cindex recording a session script +To collect all this information, you can use a session recording program +such as @command{script}, which is available on many Unix systems. +Just run your @value{GDBN} session inside @command{script} and then +include the @file{typescript} file with your bug report. + +Another way to record a @value{GDBN} session is to run @value{GDBN} +inside Emacs and then save the entire buffer to a file. + @item If you wish to suggest changes to the @value{GDBN} source, send us context diffs. If you even discuss something in the @value{GDBN} source, refer to @@ -19408,13 +19806,13 @@ either quit @value{GDBN} or create a core file of the current @value{GDBN} session. @smallexample -(gdb) @kbd{maint internal-error testing, 1, 2} +(@value{GDBP}) @kbd{maint internal-error testing, 1, 2} @dots{}/maint.c:121: internal-error: testing, 1, 2 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) +(@value{GDBP}) @end smallexample Takes an optional parameter that is used as the text of the error or @@ -19426,18 +19824,18 @@ warning message. Prints the contents of @value{GDBN}'s internal dummy-frame stack. @smallexample -(gdb) @kbd{b add} +(@value{GDBP}) @kbd{b add} @dots{} -(gdb) @kbd{print add(2,3)} +(@value{GDBP}) @kbd{print add(2,3)} Breakpoint 2, add (a=2, b=3) at @dots{} 58 return (a + b); The program being debugged stopped while in a function called from GDB. @dots{} -(gdb) @kbd{maint print dummy-frames} +(@value{GDBP}) @kbd{maint print dummy-frames} 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@} call_lo=0x01014000 call_hi=0x01014001 -(gdb) +(@value{GDBP}) @end smallexample Takes an optional file parameter. @@ -19468,7 +19866,7 @@ Print @value{GDBN}'s internal register group data structures. Takes an optional file parameter. @smallexample -(gdb) @kbd{maint print reggroups} +(@value{GDBP}) @kbd{maint print reggroups} Group Type general user float user @@ -19497,6 +19895,19 @@ 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. +@kindex maint set dwarf2 max-cache-age +@kindex maint show dwarf2 max-cache-age +@item maint set dwarf2 max-cache-age +@itemx maint show dwarf2 max-cache-age +Control the DWARF 2 compilation unit cache. + +In object files with inter-compilation-unit references, such as those +produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2 +reader needs to frequently refer to previously read compilation units. +This setting controls how long a compilation unit will remain in the cache +if it is not referenced. Setting it to zero disables caching, which will +slow down @value{GDBN} startup but reduce memory consumption. + @end table @@ -19896,17 +20307,20 @@ Reserved for future use. @item @code{O} --- reserved -Reserved for future use. - -@item @code{p}@var{n@dots{}} --- read reg @strong{(reserved)} +@item @code{p}@var{hex number of register} --- read register packet @cindex @code{p} packet -@xref{write register packet}. +@xref{read registers packet}, for a description of how the returned +register value is encoded. Reply: @table @samp -@item @var{r@dots{}.} -The hex encoded value of the register in target byte order. +@item @var{XX@dots{}} +the register's value +@item E@var{NN} +for an error +@item +Indicating an unrecognized @var{query}. @end table @item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register @@ -20656,7 +21070,7 @@ previous activity (continue, step). No additional continue or step request from @value{GDBN} is required. @smallexample -(gdb) continue +(@value{GDBP}) continue <- target requests 'system call X' target is stopped, @value{GDBN} executes system call -> GDB returns result diff --git a/gnu/usr.bin/binutils/gdb/doc/gdbint.texinfo b/gnu/usr.bin/binutils/gdb/doc/gdbint.texinfo index 7b58f5fd414..8dd234ad568 100644 --- a/gnu/usr.bin/binutils/gdb/doc/gdbint.texinfo +++ b/gnu/usr.bin/binutils/gdb/doc/gdbint.texinfo @@ -1,7 +1,7 @@ \input texinfo @c -*- texinfo -*- @setfilename gdbint.info @include gdb-cfg.texi -@dircategory Programming & development tools. +@dircategory Software development @direntry * Gdb-Internals: (gdbint). The GNU debugger's internals. @end direntry @@ -38,7 +38,7 @@ Free Documentation License''. @page @tex \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 1.5 $} % For use in headers, footers too +\xdef\manvers{\$Revision: 1.6 $} % For use in headers, footers too {\parskip=0pt \hfill Cygnus Solutions\par \hfill \manvers\par @@ -84,6 +84,7 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets. * Support Libraries:: * Coding:: * Porting GDB:: +* Versions and Branches:: * Releasing GDB:: * Testsuite:: * Hints:: @@ -476,9 +477,10 @@ no other code touches these values, the implementations of the above two macros can use them for their internal purposes. @findex target_stopped_data_address -@item target_stopped_data_address () -If the inferior has some watchpoint that triggered, return the address -associated with that watchpoint. Otherwise, return zero. +@item target_stopped_data_address (@var{addr_p}) +If the inferior has some watchpoint that triggered, place the address +associated with the watchpoint at the location pointed to by +@var{addr_p} and return non-zero. Otherwise, return zero. @findex HAVE_STEPPABLE_WATCHPOINT @item HAVE_STEPPABLE_WATCHPOINT @@ -598,15 +600,25 @@ less than 4, the number of debug registers available to x86 processors. @findex i386_stopped_data_address -@item i386_stopped_data_address (void) -The macros @code{STOPPED_BY_WATCHPOINT} and -@code{target_stopped_data_address} are set to call this function. The -argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This +@item i386_stopped_data_address (@var{addr_p}) +The target function +@code{target_stopped_data_address} is set to call this function. +This function examines the breakpoint condition bits in the DR6 Debug Status register, as returned by the @code{I386_DR_LOW_GET_STATUS} macro, and returns the address associated with the first bit that is set in DR6. +@findex i386_stopped_by_watchpoint +@item i386_stopped_by_watchpoint (void) +The macro @code{STOPPED_BY_WATCHPOINT} +is set to call this function. The +argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This +function examines the breakpoint condition bits in the DR6 Debug +Status register, as returned by the @code{I386_DR_LOW_GET_STATUS} +macro, and returns true if any bit is set. Otherwise, false is +returned. + @findex i386_insert_watchpoint @findex i386_remove_watchpoint @item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type}) @@ -654,7 +666,7 @@ register. @item i386_stopped_by_hwbp (void) This function returns non-zero if the inferior has some watchpoint or hardware breakpoint that triggered. It works like -@code{i386_stopped_data_address}, except that it doesn't return the +@code{i386_stopped_data_address}, except that it doesn't record the address whose watchpoint triggered. @findex i386_cleanup_dregs @@ -1372,7 +1384,7 @@ Finally, here's an example of printing an address. The original code: @smallexample annotate_field (4); printf_filtered ("%s ", - local_hex_string_custom ((unsigned long) b->address, "08l")); + hex_string_custom ((unsigned long) b->address, 8)); @end smallexample It became: @@ -2134,9 +2146,6 @@ The default name of @value{GDBN}'s initialization file (normally @item NO_STD_REGS This macro is deprecated. -@item NO_SYS_FILE -Define this if your system does not have a @code{<sys/file.h>}. - @item SIGWINCH_HANDLER If your host defines @code{SIGWINCH}, you can define this to be the name of a function to be called if @code{SIGWINCH} is received. @@ -2168,19 +2177,9 @@ The default value of the prompt string (normally @code{"(gdb) "}). @cindex terminal device The name of the generic TTY device, defaults to @code{"/dev/tty"}. -@item FCLOSE_PROVIDED -Define this if the system declares @code{fclose} in the headers included -in @code{defs.h}. This isn't needed unless your compiler is unusually -anal. - @item FOPEN_RB Define this if binary files are opened the same way as text files. -@item GETENV_PROVIDED -Define this if the system declares @code{getenv} in its headers included -in @code{defs.h}. This isn't needed unless your compiler is unusually -anal. - @item HAVE_MMAP @findex mmap In some cases, use the system call @code{mmap} for reading symbol @@ -2251,10 +2250,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 NO_SIGINTERRUPT -@findex siginterrupt -Define this to indicate that @code{siginterrupt} is not available. - @item SEEK_CUR @itemx SEEK_SET Define these to appropriate value for the system @code{lseek}, if not already @@ -2264,11 +2259,6 @@ defined. This is the signal for stopping @value{GDBN}. Defaults to @code{SIGTSTP}. (Only redefined for the Convex.) -@item USE_O_NOCTTY -Define this if the interior's tty should be opened with the @code{O_NOCTTY} -flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is -always linked in.) - @item USG Means that System V (prior to SVR4) include files are in use. (FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c}, and @@ -2930,12 +2920,6 @@ Define if the compiler promotes a @code{short} or @code{char} parameter to an @code{int}, but still reports the parameter as its original type, rather than the promoted type. -@item BELIEVE_PCC_PROMOTION_TYPE -@findex BELIEVE_PCC_PROMOTION_TYPE -Define this if @value{GDBN} should believe the type of a @code{short} -argument when compiled by @code{pcc}, but look within a full int space to get -its value. Only defined for Sun-3 at present. - @item BITS_BIG_ENDIAN @findex BITS_BIG_ENDIAN Define this if the numbering of bits in the targets does @strong{not} match the @@ -3041,35 +3025,6 @@ 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 -host-byte-ordered @code{DEPRECATED_REGISTER_SIZE} sized values that -partially specify the sequence of instructions needed for an inferior -function call. - -Should be deprecated in favor of a macro that uses target-byte-ordered -data. - -This method has been replaced by @code{push_dummy_code} -(@pxref{push_dummy_code}). - -@item DEPRECATED_SIZEOF_CALL_DUMMY_WORDS -@findex DEPRECATED_SIZEOF_CALL_DUMMY_WORDS -The size of @code{DEPRECATED_CALL_DUMMY_WORDS}. This must return a -positive value. See also @code{DEPRECATED_CALL_DUMMY_LENGTH}. - -This method has been replaced by @code{push_dummy_code} -(@pxref{push_dummy_code}). - -@item CALL_DUMMY -@findex CALL_DUMMY -A static initializer for @code{DEPRECATED_CALL_DUMMY_WORDS}. -Deprecated. - -This method has been replaced by @code{push_dummy_code} -(@pxref{push_dummy_code}). - @item CALL_DUMMY_LOCATION @findex CALL_DUMMY_LOCATION See the file @file{inferior.h}. @@ -3090,15 +3045,6 @@ written to the target. This is often the case for program counters, status words, and other special registers. If this is not defined, @value{GDBN} will assume that all registers may be written. -@item DO_DEFERRED_STORES -@itemx CLEAR_DEFERRED_STORES -@findex CLEAR_DEFERRED_STORES -@findex DO_DEFERRED_STORES -Define this to execute any deferred stores of registers into the inferior, -and to cancel any deferred stores. - -Currently only implemented correctly for native Sparc configurations? - @item int CONVERT_REGISTER_P(@var{regnum}) @findex CONVERT_REGISTER_P Return non-zero if register @var{regnum} can represent data values in a @@ -3308,20 +3254,20 @@ function end symbol is 0. For such targets, you must define @code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a function's epilogue. -@item FUNCTION_START_OFFSET -@findex FUNCTION_START_OFFSET +@item DEPRECATED_FUNCTION_START_OFFSET +@findex DEPRECATED_FUNCTION_START_OFFSET An integer, giving the offset in bytes from a function's address (as used in the values of symbols, function pointers, etc.), and the function's first genuine instruction. This is zero on almost all machines: the function's address is usually -the address of its first instruction. However, on the VAX, for example, -each function starts with two bytes containing a bitmask indicating -which registers to save upon entry to the function. The VAX @code{call} -instructions check this value, and save the appropriate registers -automatically. Thus, since the offset from the function's address to -its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would -be 2 on the VAX. +the address of its first instruction. However, on the VAX, for +example, each function starts with two bytes containing a bitmask +indicating which registers to save upon entry to the function. The +VAX @code{call} instructions check this value, and save the +appropriate registers automatically. Thus, since the offset from the +function's address to its first instruction is two bytes, +@code{DEPRECATED_FUNCTION_START_OFFSET} would be 2 on the VAX. @item GCC_COMPILED_FLAG_SYMBOL @itemx GCC2_COMPILED_FLAG_SYMBOL @@ -3411,10 +3357,10 @@ The epilogue of a function is defined as the part of a function where the stack frame of the function already has been destroyed up to the final `return from function call' instruction. -@item SIGTRAMP_START (@var{pc}) -@findex SIGTRAMP_START -@itemx SIGTRAMP_END (@var{pc}) -@findex SIGTRAMP_END +@item DEPRECATED_SIGTRAMP_START (@var{pc}) +@findex DEPRECATED_SIGTRAMP_START +@itemx DEPRECATED_SIGTRAMP_END (@var{pc}) +@findex DEPRECATED_SIGTRAMP_END Define these to be the start and end address of the @code{sigtramp} for the given @var{pc}. On machines where the address is just a compile time constant, the macro expansion will typically just ignore the supplied @@ -3551,43 +3497,6 @@ form. 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 -@cindex structures, returning by value - -Return non-zero if values of type TYPE are returned on the stack, using -the ``struct convention'' (i.e., the caller provides a pointer to a -buffer in which the callee should store the return value). This -controls how the @samp{finish} command finds a function's return value, -and whether an inferior function call reserves space on the stack for -the return value. - -The full logic @value{GDBN} uses here is kind of odd. - -@itemize @bullet -@item -If the type being returned by value is not a structure, union, or array, -and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN} -concludes the value is not returned using the struct convention. - -@item -Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below). -If that returns non-zero, @value{GDBN} assumes the struct convention is -in use. -@end itemize - -In other words, to indicate that a given type is returned by value using -the struct convention, that type must be either a struct, union, array, -or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something -that @code{USE_STRUCT_CONVENTION} likes. - -Note that, in C and C@t{++}, arrays are never returned by value. In those -languages, these predicates will always see a pointer type, never an -array type. All the references above to arrays being returned by value -apply only to other languages. - @item SOFTWARE_SINGLE_STEP_P() @findex SOFTWARE_SINGLE_STEP_P Define this as 1 if the target does not have a hardware single-step @@ -3632,22 +3541,6 @@ and guess the starting and ending addresses of the compilation unit from them. @end itemize -@item PCC_SOL_BROKEN -@findex PCC_SOL_BROKEN -(Used only in the Convex target.) - -@item PC_IN_SIGTRAMP (@var{pc}, @var{name}) -@findex PC_IN_SIGTRAMP -@cindex sigtramp -The @dfn{sigtramp} is a routine that the kernel calls (which then calls -the signal handler). On most machines it is a library routine that is -linked into the executable. - -This function, given a program counter value in @var{pc} and the -(possibly NULL) name of the function in which that @var{pc} resides, -returns nonzero if the @var{pc} and/or @var{name} show that we are in -sigtramp. - @item PC_LOAD_SEGMENT @findex PC_LOAD_SEGMENT If defined, print information about the load segment for the program @@ -3695,7 +3588,7 @@ definition is only used in generic code when parsing "$ps".) If defined, used by @code{frame_pop} to remove a stack frame. This method has been superseeded by generic code. -@item push_dummy_call (@var{gdbarch}, @var{func_addr}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr}) +@item push_dummy_call (@var{gdbarch}, @var{function}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr}) @findex push_dummy_call @findex DEPRECATED_PUSH_ARGUMENTS. @anchor{push_dummy_call} Define this to push the dummy frame's call to @@ -3703,13 +3596,15 @@ the inferior function onto the stack. In addition to pushing @var{nargs}, the code should push @var{struct_addr} (when @var{struct_return}), and the return address (@var{bp_addr}). +@var{function} is a pointer to a @code{struct value}; on architectures that use +function descriptors, this contains the function descriptor value. + Returns the updated top-of-stack pointer. This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}. @item CORE_ADDR push_dummy_code (@var{gdbarch}, @var{sp}, @var{funaddr}, @var{using_gcc}, @var{args}, @var{nargs}, @var{value_type}, @var{real_pc}, @var{bp_addr}) @findex push_dummy_code -@findex DEPRECATED_FIX_CALL_DUMMY @anchor{push_dummy_code} Given a stack based call dummy, push the instruction sequence (including space for a breakpoint) to which the called function should return. @@ -3722,24 +3617,8 @@ By default, the stack is grown sufficient to hold a frame-aligned (@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address 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}. - -@item DEPRECATED_PUSH_DUMMY_FRAME -@findex DEPRECATED_PUSH_DUMMY_FRAME -Used in @samp{call_function_by_hand} to create an artificial stack frame. - -@item DEPRECATED_REGISTER_BYTES -@findex DEPRECATED_REGISTER_BYTES -The total amount of space needed to store @value{GDBN}'s copy of the -machine's register state. - -This is no longer needed. @value{GDBN} instead computes the size of the -register buffer at run-time. +This method replaces @code{CALL_DUMMY_LOCATION}, +@code{DEPRECATED_REGISTER_SIZE}. @item REGISTER_NAME(@var{i}) @findex REGISTER_NAME @@ -3870,10 +3749,6 @@ 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.) - @item SYMBOL_RELOADING_DEFAULT @findex SYMBOL_RELOADING_DEFAULT The default value of the ``symbol-reloading'' variable. (Never defined in @@ -3953,9 +3828,9 @@ Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. @findex read_sp @findex read_fp @anchor{TARGET_READ_SP} These change the behavior of @code{read_pc}, -@code{write_pc}, @code{read_sp} and @code{deprecated_read_fp}. For most -targets, these may be left undefined. @value{GDBN} will call the read -and write register functions with the relevant @code{_REGNUM} argument. +@code{write_pc}, and @code{read_sp}. For most targets, these may be +left undefined. @value{GDBN} will call the read and write register +functions with the relevant @code{_REGNUM} argument. These macros are useful when a target keeps one of these registers in a hard to get at place; for example, part in a segment register and part @@ -3996,8 +3871,8 @@ frame. The value returned must match the dummy frame stack value previously saved using @code{SAVE_DUMMY_FRAME_TOS}. @xref{SAVE_DUMMY_FRAME_TOS}. -@item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type}) -@findex USE_STRUCT_CONVENTION +@item DEPRECATED_USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type}) +@findex DEPRECATED_USE_STRUCT_CONVENTION If defined, this must be an expression that is nonzero if a value of the given @var{type} being returned from a function must have space allocated for it on the stack. @var{gcc_p} is true if the function @@ -4471,10 +4346,6 @@ target systems are the same. These macros should be defined (or left undefined) in @file{nm-@var{system}.h}. @table @code -@item ATTACH_DETACH -@findex ATTACH_DETACH -If defined, then @value{GDBN} will include support for the @code{attach} and -@code{detach} commands. @item CHILD_PREPARE_TO_STORE @findex CHILD_PREPARE_TO_STORE @@ -4493,10 +4364,6 @@ Define this if the native-dependent code will provide its own routines @file{infptrace.c} is included in this configuration, the default routines in @file{infptrace.c} are used for these functions. -@item FILES_INFO_HOOK -@findex FILES_INFO_HOOK -(Only defined for Convex.) - @item FP0_REGNUM @findex FP0_REGNUM This macro is normally defined to be the number of the first floating @@ -4527,12 +4394,6 @@ needs to know this so that it can subtract this address from absolute addresses in the upage, that are obtained via ptrace or from core files. On systems that don't need this value, set it to zero. -@item KERNEL_U_ADDR_BSD -@findex KERNEL_U_ADDR_BSD -Define this to cause @value{GDBN} to determine the address of @code{u} at -runtime, by using Berkeley-style @code{nlist} on the kernel's image in -the root directory. - @item KERNEL_U_ADDR_HPUX @findex KERNEL_U_ADDR_HPUX Define this to cause @value{GDBN} to determine the address of @code{u} at @@ -4550,10 +4411,6 @@ Defines the format for the name of a @file{/proc} device. Should be defined in @file{nm.h} @emph{only} in order to override the default definition in @file{procfs.c}. -@item PTRACE_FP_BUG -@findex PTRACE_FP_BUG -See @file{mach386-xdep.c}. - @item PTRACE_ARG3_TYPE @findex PTRACE_ARG3_TYPE The type of the third argument to the @code{ptrace} system call, if it @@ -4593,10 +4450,6 @@ the shell execs, and once when the program itself execs. If the actual number of traps is something other than 2, then define this macro to expand into the number expected. -@item SVR4_SHARED_LIBS -@findex SVR4_SHARED_LIBS -Define this to indicate that SVR4-style shared libraries are in use. - @item USE_PROC_FS @findex USE_PROC_FS This determines whether small routines in @file{*-tdep.c}, which @@ -4872,134 +4725,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}) +@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 -Any memory required by the @var{init} function should be allocated -using @code{GDBARCH_OBSTACK_ZALLOC}. That memory is automatically -released when the corresponding architecture is deleted. +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 an @code{init} function 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 = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel); - @dots{} - return 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); -@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: - -@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{handle}, void *@var{pointer}) -Set the still @code{NULL} data-pointer corresponding to @var{handle} -to the non-@code{NULL} @var{pointer} value. -@end deftypefun +A module can on-demand create architecture dependant data structures +using @code{post_init}. -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 -/* Always return a non-NULL nozel. */ -static struct nozel * -gdbarch_nozel (struct gdbarch *gdbarch) +static void * +nozel_post_init (struct gdbarch *gdbarch) @{ - struct nozel *nozel = gdbarch_data (gdbarch, nozel_handle); - if (nozel == NULL) - @{ - nozel = nozel_init (gdbarch); - set_gdbarch_data (gdbarch, nozel_handle, nozel); - @} - return nozel; + struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel); + nozel->total = gdbarch@dots{} (gdbarch); + return data; @} @end smallexample @smallexample -/* Called during architecture creation. */ -extern void -set_gdbarch_nozel (struct gdbarch *gdbarch, int total) +extern int +nozel_total (struct gdbarch *gdbarch) @{ - struct nozel *data = gdbarch_nozel (gdbarch); - @dots{} - data->total = total; + struct nozel *data = gdbarch_data (gdbarch, nozel_handle); + return data->total; @} @end smallexample -@smallexample -void -_initialize_nozel (void) -@{ - nozel_handle = register_gdbarch_data (nozel_init); - @dots{} -@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 @@ -5079,7 +4902,7 @@ allocation of small temporary values (such as strings). restrict the memory being allocated to no more than a few kilobytes.} @value{GDBN} uses the string function @code{xstrdup} and the print -function @code{xasprintf}. +function @code{xstrprintf}. @emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print functions such as @code{sprintf} are very prone to buffer overflow @@ -5557,109 +5380,198 @@ target-dependent @file{.h} and @file{.c} files used for your configuration. @end itemize -@node Releasing GDB +@node Versions and Branches +@chapter Versions and Branches -@chapter Releasing @value{GDBN} -@cindex making a new release of gdb +@section Versions -@section Versions and Branches +@value{GDBN}'s version is determined by the file +@file{gdb/version.in} and takes one of the following forms: -@subsection Version Identifiers +@table @asis +@item @var{major}.@var{minor} +@itemx @var{major}.@var{minor}.@var{patchlevel} +an official release (e.g., 6.0 or 6.0.1) +@item @var{major}.@var{minor}.@var{patchlevel}_@var{YYYY}@var{MM}@var{DD} +a snapshot (e.g., 6.0.50_20020630) +@item @var{major}.@var{minor}.@var{patchlevel}_@var{YYYY}-@var{MM}-@var{DD}-cvs +a @sc{cvs} check out (e.g., 6.0.90_2004-02-30-cvs) +@item @var{major}.@var{minor}.@var{patchlevel}_@var{YYYY}@var{MM}@var{DD} (@var{vendor}) +a vendor specific release of @value{GDBN}, that while based on@* +@var{major}.@var{minor}.@var{patchlevel}_@var{YYYY}@var{MM}@var{DD}, +may contain additional changes +@end table -@value{GDBN}'s version is determined by the file @file{gdb/version.in}. +@value{GDBN}'s mainline uses the @var{major} and @var{minor} version +numbers from the most recent release branch, with a @var{patchlevel} +of 50. As each new release branch is created, the mainline +@var{major} and @var{minor} version numbers are accordingly updated. -@value{GDBN}'s mainline uses ISO dates to differentiate between -versions. The CVS repository uses @var{YYYY}-@var{MM}-@var{DD}-cvs -while the corresponding snapshot uses @var{YYYYMMDD}. +@value{GDBN}'s release branch uses a similar, but slightly more +complicated scheme. When the branch is first cut, the mainline's +@var{patchlevel} is changed to .90. As draft releases are drawn from +the branch, the @var{patchlevel} is incremented. Once the first +release (@var{major}.@var{minor}) has been made, the version prefix is +updated to @var{major}.@var{minor}.0.90. Follow on releases have an +incremented @var{patchlevel}. -@value{GDBN}'s release branch uses a slightly more complicated scheme. -When the branch is first cut, the mainline version identifier is -prefixed with the @var{major}.@var{minor} from of the previous release -series but with .90 appended. As draft releases are drawn from the -branch, the minor minor number (.90) is incremented. Once the first -release (@var{M}.@var{N}) has been made, the version prefix is updated -to @var{M}.@var{N}.0.90 (dot zero, dot ninety). Follow on releases have -an incremented minor minor version number (.0). +If the previous @value{GDBN} version is 6.1 and the current version is +6.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor}, +here's an illustration of a typical sequence: -Using 5.1 (previous) and 5.2 (current), the example below illustrates a -typical sequence of version identifiers: +@smallexample + <HEAD> + | +6.1.50_2002-03-02-cvs + | + +---------------------------. + | <gdb_6_2-branch> + | | +6.2.50_2002-03-03-cvs 6.1.90 (draft #1) + | | +6.2.50_2002-03-04-cvs 6.1.90_2002-03-04-cvs + | | +6.2.50_2002-03-05-cvs 6.1.91 (draft #2) + | | +6.2.50_2002-03-06-cvs 6.1.91_2002-03-06-cvs + | | +6.2.50_2002-03-07-cvs 6.2 (release) + | | +6.2.50_2002-03-08-cvs 6.2.0.90_2002-03-08-cvs + | | +6.2.50_2002-03-09-cvs 6.2.1 (update) + | | +6.2.50_2002-03-10-cvs <branch closed> + | +6.2.50_2002-03-11-cvs + | + +---------------------------. + | <gdb_6_3-branch> + | | +6.3.50_2002-03-12-cvs 6.2.90 (draft #1) + | | +@end smallexample -@table @asis -@item 5.1.1 -final release from previous branch -@item 2002-03-03-cvs -main-line the day the branch is cut -@item 5.1.90-2002-03-03-cvs -corresponding branch version -@item 5.1.91 -first draft release candidate -@item 5.1.91-2002-03-17-cvs -updated branch version -@item 5.1.92 -second draft release candidate -@item 5.1.92-2002-03-31-cvs -updated branch version -@item 5.1.93 -final release candidate (see below) -@item 5.2 -official release -@item 5.2.0.90-2002-04-07-cvs -updated CVS branch version -@item 5.2.1 -second official release -@end table +@section Release Branches +@cindex Release Branches -Notes: +@value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a +single release branch, and identifies that branch using the @sc{cvs} +branch tags: -@itemize @bullet -@item -Minor minor minor draft release candidates such as 5.2.0.91 have been -omitted from the example. Such release candidates are, typically, never -made. -@item -For 5.1.93 the bziped tar ball @file{gdb-5.1.93.tar.bz2} is just the -official @file{gdb-5.2.tar} renamed and compressed. -@end itemize +@smallexample +gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint +gdb_@var{major}_@var{minor}-branch +gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release +@end smallexample + +@emph{Pragmatics: To help identify the date at which a branch or +release is made, both the branchpoint and release tags include the +date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag. The +branch tag, denoting the head of the branch, does not need this.} + +@section Vendor Branches +@cindex vendor branches To avoid version conflicts, vendors are expected to modify the file @file{gdb/version.in} to include a vendor unique alphabetic identifier (an official @value{GDBN} release never uses alphabetic characters in -its version identifer). +its version identifer). E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit +Inc Patch 2)}. + +@section Experimental Branches +@cindex experimental branches -Since @value{GDBN} does not make minor minor minor releases (e.g., -5.1.0.1) the conflict between that and a minor minor draft release -identifier (e.g., 5.1.0.90) is avoided. +@subsection Guidelines +@value{GDBN} permits the creation of branches, cut from the @sc{cvs} +repository, for experimental development. Branches make it possible +for developers to share preliminary work, and maintainers to examine +significant new developments. -@subsection Branches +The following are a set of guidelines for creating such branches: -@value{GDBN} draws a release series (5.2, 5.2.1, @dots{}) from a single -release branch (gdb_5_2-branch). Since minor minor minor releases -(5.1.0.1) are not made, the need to branch the release branch is avoided -(it also turns out that the effort required for such a a branch and -release is significantly greater than the effort needed to create a new -release from the head of the release branch). +@table @emph + +@item a branch has an owner +The owner can set further policy for a branch, but may not change the +ground rules. In particular, they can set a policy for commits (be it +adding more reviewers or deciding who can commit). + +@item all commits are posted +All changes committed to a branch shall also be posted to +@email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches +mailing list}. While commentary on such changes are encouraged, people +should remember that the changes only apply to a branch. + +@item all commits are covered by an assignment +This ensures that all changes belong to the Free Software Foundation, +and avoids the possibility that the branch may become contaminated. + +@item a branch is focused +A focused branch has a single objective or goal, and does not contain +unnecessary or irrelevant changes. Cleanups, where identified, being +be pushed into the mainline as soon as possible. -Releases 5.0 and 5.1 used branch and release tags of the form: +@item a branch tracks mainline +This keeps the level of divergence under control. It also keeps the +pressure on developers to push cleanups and other stuff into the +mainline. + +@item a branch shall contain the entire @value{GDBN} module +The @value{GDBN} module @code{gdb} should be specified when creating a +branch (branches of individual files should be avoided). @xref{Tags}. + +@item a branch shall be branded using @file{version.in} +The file @file{gdb/version.in} shall be modified so that it identifies +the branch @var{owner} and branch @var{name}, e.g., +@samp{6.2.50_20030303_owner_name} or @samp{6.2 (Owner Name)}. + +@end table +@subsection Tags +@anchor{Tags} + +To simplify the identification of @value{GDBN} branches, the following +branch tagging convention is strongly recommended: + +@table @code + +@item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint +@itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch +The branch point and corresponding branch tag. @var{YYYYMMDD} is the +date that the branch was created. A branch is created using the +sequence: @anchor{experimental branch tags} @smallexample -gdb_N_M-YYYY-MM-DD-branchpoint -gdb_N_M-YYYY-MM-DD-branch -gdb_M_N-YYYY-MM-DD-release +cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb +cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \ + @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb @end smallexample -Release 5.2 is trialing the branch and release tags: - +@item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint +The tagged point, on the mainline, that was used when merging the branch +on @var{yyyymmdd}. To merge in all changes since the branch was cut, +use a command sequence like: @smallexample -gdb_N_M-YYYY-MM-DD-branchpoint -gdb_N_M-branch -gdb_M_N-YYYY-MM-DD-release +cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb +cvs update \ + -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint + -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint @end smallexample +@noindent +Similar sequences can be used to just merge in changes since the last +merge. -@emph{Pragmatics: The branchpoint and release tags need to identify when -a branch and release are made. The branch tag, denoting the head of the -branch, does not have this criteria.} +@end table +@noindent +For further information on @sc{cvs}, see +@uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}. + +@node Releasing GDB + +@chapter Releasing @value{GDBN} +@cindex making a new release of gdb @section Branch Commit Policy @@ -6460,6 +6372,15 @@ difficult to test, such as code that handles host OS failures or bugs in particular versions of compilers, and it's OK not to try to write tests for all of those. +DejaGNU supports separate build, host, and target machines. However, +some @value{GDBN} test scripts do not work if the build machine and +the host machine are not the same. In such an environment, these scripts +will give a result of ``UNRESOLVED'', like this: + +@smallexample +UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host. +@end smallexample + @section Testsuite Organization @cindex test suite organization diff --git a/gnu/usr.bin/binutils/gdb/doc/stabs.texinfo b/gnu/usr.bin/binutils/gdb/doc/stabs.texinfo index a4461321acd..dd8ccdd2d93 100644 --- a/gnu/usr.bin/binutils/gdb/doc/stabs.texinfo +++ b/gnu/usr.bin/binutils/gdb/doc/stabs.texinfo @@ -5,7 +5,7 @@ @c This is a dir.info fragment to support semi-automated addition of @c manuals to an info tree. -@dircategory Programming & development tools. +@dircategory Software development @direntry * Stabs: (stabs). The "stabs" debugging information format. @end direntry @@ -35,7 +35,7 @@ Free Documentation License''. @page @tex \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 1.4 $} % For use in headers, footers too +\xdef\manvers{\$Revision: 1.5 $} % For use in headers, footers too {\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par @@ -422,9 +422,33 @@ file. This information is contained in a symbol of stab type value of the symbol is the start address of the portion of the text section corresponding to that file. -With the Sun Solaris2 compiler, the desc field contains a -source-language code. -@c Do the debuggers use it? What are the codes? -djm +Some compilers use the desc field to indicate the language of the +source file. Sun's compilers started this usage, and the first +constants are derived from their documentation. Languages added +by gcc/gdb start at 0x32 to avoid conflict with languages Sun may +add in the future. A desc field with a value 0 indicates that no +language has been specified via this mechanism. + +@table @asis +@item @code{N_SO_AS} (0x1) +Assembly language +@item @code{N_SO_C} (0x2) +K&R traditional C +@item @code{N_SO_ANSI_C} (0x3) +ANSI C +@item @code{N_SO_CC} (0x4) +C++ +@item @code{N_SO_FORTRAN} (0x5) +Fortran +@item @code{N_SO_PASCAL} (0x6) +Pascal +@item @code{N_SO_FORTRAN90} (0x7) +Fortran90 +@item @code{N_SO_OBJC} (0x32) +Objective-C +@item @code{N_SO_OBJCPLUS} (0x33) +Objective-C++ +@end table Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also include the directory in which the source was compiled, in a second |