From eb9747a649476236002a4db7e100a6f2fe1b6eab Mon Sep 17 00:00:00 2001 From: "Andrey A. Chernov" Date: Wed, 11 Jan 1995 16:29:45 +0000 Subject: [PATCH] Install infopages --- gnu/usr.bin/gdb/doc/GDBvn.texi | 1 + gnu/usr.bin/gdb/doc/Makefile | 342 +---------- gnu/usr.bin/gdb/doc/annotate.texi | 708 +++++++++++++++++++++ gnu/usr.bin/gdb/doc/gdb.texinfo | 952 +++++++++++++++++++---------- gnu/usr.bin/gdb/doc/gdbint.texinfo | 289 ++++----- gnu/usr.bin/gdb/doc/inc-hist.texi | 155 +++++ gnu/usr.bin/gdb/doc/remote.texi | 280 ++++++--- gnu/usr.bin/gdb/doc/stabs.texinfo | 614 +++++++++++++------ 8 files changed, 2290 insertions(+), 1051 deletions(-) create mode 100644 gnu/usr.bin/gdb/doc/GDBvn.texi create mode 100644 gnu/usr.bin/gdb/doc/annotate.texi create mode 100644 gnu/usr.bin/gdb/doc/inc-hist.texi diff --git a/gnu/usr.bin/gdb/doc/GDBvn.texi b/gnu/usr.bin/gdb/doc/GDBvn.texi new file mode 100644 index 00000000000..c891e560020 --- /dev/null +++ b/gnu/usr.bin/gdb/doc/GDBvn.texi @@ -0,0 +1 @@ +@set GDBVN 4.13 diff --git a/gnu/usr.bin/gdb/doc/Makefile b/gnu/usr.bin/gdb/doc/Makefile index 8cde5d4b535..2f5b55751e8 100644 --- a/gnu/usr.bin/gdb/doc/Makefile +++ b/gnu/usr.bin/gdb/doc/Makefile @@ -1,340 +1,4 @@ -# This file was generated automatically by configure. Do not edit. -VPATH = . -links = -host_alias = i386-unknown-freebsd -host_cpu = i386 -host_vendor = unknown -host_os = freebsd -host_canonical = i386-unknown-freebsd -target_alias = i386-unknown-freebsd -target_cpu = i386 -target_vendor = unknown -target_os = freebsd -target_canonical = i386-unknown-freebsd -##Copyright (C) 1991, 1992 Free Software Foundation, Inc. +INFO = gdb gdbint stabs +MAKEINFOFLAGS += -I ${.CURDIR}/../../../lib/libreadline/doc -# Makefile for GDB documentation. -# This file is part of GDB. - -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - -srcdir = . - -prefix = /usr/gnu - -infodir = $(prefix)/info - -SHELL = /bin/sh - -INSTALL = install -c -INSTALL_PROGRAM = $(INSTALL) -INSTALL_DATA = $(INSTALL) - -# main GDB source directory -gdbdir = $(srcdir)/.. - -# where to find texinfo; GDB dist should include a recent one -TEXIDIR=${gdbdir}/../texinfo - -# where to find makeinfo, preferably one designed for texinfo-2 -MAKEINFO=makeinfo - -# where to find texi2roff, ditto -TEXI2ROFF=texi2roff - -# Where is the source dir for the READLINE library doc? -# Traditionally readline is in .. or . -READLINE_DIR = ${gdbdir}/../readline/doc - -SET_TEXINPUTS = TEXINPUTS=${TEXIDIR}:.:$(srcdir):$(READLINE_DIR):$$TEXINPUTS - -# There may be alternate predefined collections of switches to configure -# the GDB manual. Normally this is not done in synch with the software -# config system, since this choice tends to be independent; most people -# want a doc config of `all' for a generic manual, regardless of sw config. -DOC_CONFIG = all - -# This list of sed edits will edit the GDB reference card -# for what fonts and what papersize to use. -# By default (NO edits applied), the refcard uses: -# - Computer Modern (CM) fonts -# - US letter paper (8.5x11in) -# List some of the following files for alternative fonts and paper: -# a4rc.sed use A4 paper (297 x 210 mm) -# psrc.sed use PostScript fonts (Karl Berry short TeX names) -# lpsrc.sed use PostScript fonts (full PostScript names in TeX) -# e.g. for A4, Postscript: REFEDITS = a4rc.sed psrc.sed -# for A4, CM fonts: REFEDITS = a4rc.sed -# for US, PS fonts: REFEDITS = psrc.sed -# for default: -REFEDITS = - -# Don Knuth's TeX formatter -TEX = tex - -# auxiliary program for sorting Texinfo indices -TEXINDEX = texindex - -# Main GDB manual's source files -SFILES_INCLUDED = gdb-cfg.texi $(srcdir)/remote.texi - -SFILES_LOCAL = $(srcdir)/gdb.texinfo GDBvn.texi $(SFILES_INCLUDED) - -SFILES_DOC = $(SFILES_LOCAL) \ - $(READLINE_DIR)/rluser.texinfo $(READLINE_DIR)/inc-hist.texi - -#### Host, target, and site specific Makefile fragments come in here. -### - -all install: - -info: gdb.info gdbint.info stabs.info -dvi: gdb.dvi refcard.dvi gdbint.dvi -all-doc: gdb.info gdb.dvi refcard.dvi gdb-internals gdbint.dvi - -install-info: info - for i in *.info* ; do \ - $(INSTALL_DATA) $$i $(infodir)/$$i ; \ - done - -STAGESTUFF = *.info* gdb-all.texi GDBvn.texi - -# Copy the object files from a particular stage into a subdirectory. -stage1: force - -mkdir stage1 - -mv $(STAGESTUFF) stage1 - -stage2: force - -mkdir stage2 - -mv $(STAGESTUFF) stage2 - -stage3: force - -mkdir stage3 - -mv $(STAGESTUFF) stage3 - -against=stage2 - -comparison: force - for i in $(STAGESTUFF) ; do cmp $$i $(against)/$$i ; done - -de-stage1: force - -(cd stage1 ; mv -f * ..) - -rmdir stage1 - -de-stage2: force - -(cd stage2 ; mv -f * ..) - -rmdir stage2 - -de-stage3: force - -(cd stage3 ; mv -f * ..) - -rmdir stage3 - -clean-info: - rm -f gdb.info* gdbint.info* stabs.info* - -clean-dvi: - rm -f gdb.dvi refcard.dvi gdbint.dvi stabs.dvi sedref.dvi - -mostlyclean: clean-info clean-dvi - rm -f gdb.?? gdb.??? gdb.mm gdb.ms gdb.me - rm -f links2roff - rm -f refcard.ps lrefcard.ps refcard.log sedref.* *~ - rm -f gdbint.?? gdbint.??? stabs.?? stabs.??? - -clean: mostlyclean - rm -f GDBvn.texi rluser.texinfo inc-hist.texi - -distclean: clean - rm -f Makefile config.status - -realclean: distclean clean-dvi clean-info - -# GDB QUICK REFERENCE (dvi output) -refcard.dvi : refcard.tex $(REFEDITS) - if [ -z "$(REFEDITS)" ]; then \ - cp $(srcdir)/refcard.tex sedref.tex ; \ - else \ - echo > tmp.sed ; \ - for f in "$(REFEDITS)" ; do \ - cat $(srcdir)/$$f >>tmp.sed ; done ; \ - sed -f tmp.sed $(srcdir)/refcard.tex >sedref.tex ; \ - fi - $(SET_TEXINPUTS) $(TEX) sedref.tex - mv sedref.dvi refcard.dvi - rm -f sedref.log sedref.tex tmp.sed - -refcard.ps : refcard.dvi - dvips -t landscape refcard.dvi -o - -# File to record current GDB version number (copied from main dir Makefile.in) -GDBvn.texi : ${gdbdir}/Makefile.in - echo "@set GDBVN `sed <$(srcdir)/../Makefile.in -n 's/VERSION = //p'`" > ./GDBvn.new - mv GDBvn.new GDBvn.texi - -# Updated atomically -.PRECIOUS: GDBvn.texi - -# Choose configuration for GDB manual (normally `all'; normally not tied into -# `configure' script because most users prefer generic version of manual, -# not one for their binary config---which may not be specifically -# defined anyways). -gdb-cfg.texi: ${srcdir}/${DOC_CONFIG}-cfg.texi - ln -s ${srcdir}/${DOC_CONFIG}-cfg.texi gdb-cfg.texi || \ - ln ${srcdir}/${DOC_CONFIG}-cfg.texi gdb-cfg.texi || \ - cp ${srcdir}/${DOC_CONFIG}-cfg.texi gdb-cfg.texi - -# GDB MANUAL: texinfo source, using @set/@clear/@value/@ifset/@ifclear -# If your texinfo or makeinfo don't support these, get a new texinfo release -# -# The nonsense with GDBvn.texi gets this to run with both Sun and GNU make. -# Note that we can *generate* GDBvn.texi, but since we distribute one in the -# source directory for the benefit of people who *don't* use this makefile, -# VPATH will often tell make not to bother building it, because the one -# in the srcdir is up to date. (if not, then make should build one here). - -# GDB MANUAL: TeX dvi file -gdb.dvi: ${SFILES_DOC} - if [ ! -f ./GDBvn.texi ]; then \ - ln -s $(srcdir)/GDBvn.texi . || \ - ln $(srcdir)/GDBvn.texi . || \ - cp $(srcdir)/GDBvn.texi . ; else true; fi - $(SET_TEXINPUTS) $(TEX) gdb.texinfo - $(SET_TEXINPUTS) $(TEX) gdb.texinfo - $(TEXINDEX) gdb.?? - $(SET_TEXINPUTS) $(TEX) gdb.texinfo - rm -f gdb.?? gdb.log gdb.aux gdb.toc gdb.??s - -# GDB MANUAL: info file -# We're using texinfo2, and older makeinfo's may not be able to -# cope with all the markup. -gdb.info: ${SFILES_DOC} - $(MAKEINFO) -I ${READLINE_DIR} -I $(srcdir) -o ./gdb.info gdb.texinfo - -# GDB MANUAL: roff translations -# Try to use a recent texi2roff. v2 was put on prep in jan91. -# If you want an index, see texi2roff doc for postprocessing -# and add -i to texi2roff invocations below. -# Workarounds for texi2roff-2 (probably fixed in later texi2roff's, delete -# corresponding -e lines when later texi2roff's are current) -# + @ifinfo's deleted explicitly due to texi2roff-2 bug w nested constructs. -# + @c's deleted explicitly because texi2roff sees texinfo commands in them -# + @ (that's at-BLANK) not recognized by texi2roff, turned into blank -# + @alphaenumerate is ridiculously new, turned into @enumerate - -# texi2roff doesn't have a notion of include dirs, so we have to fake -# it out for gdb manual's include files---but only if not configured -# in main sourcedir. -links2roff: $(SFILES_INCLUDED) - if [ ! -f gdb.texinfo ]; then \ - ln -s $(SFILES_INCLUDED) . || \ - ln $(SFILES_INCLUDED) . || \ - cp $(SFILES_INCLUDED) . ; \ - fi - touch links2roff - -# "Readline" appendices. Get them also due to lack of includes, -# regardless of whether or not configuring in main sourcedir. -# @ftable removed due to bug in texi2roff-2; if your texi2roff -# is newer, try just ln or cp -rluser.texinfo: ${READLINE_DIR}/rluser.texinfo - sed -e 's/^@ftable/@table/g' \ - -e 's/^@end ftable/@end table/g' \ - ${READLINE_DIR}/rluser.texinfo > ./rluser.texinfo - -inc-hist.texi: ${READLINE_DIR}/inc-hist.texi - ln -s ${READLINE_DIR}/inc-hist.texi . || \ - ln ${READLINE_DIR}/inc-hist.texi . || \ - cp ${READLINE_DIR}/inc-hist.texi . - -# gdb manual suitable for [gtn]roff -me -gdb.me: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texi - sed -e '/\\input texinfo/d' \ - -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ - -e '/^@ifinfo/,/^@end ifinfo/d' \ - -e '/^@c /d' \ - -e 's/{.*,,/{/' \ - -e 's/@ / /g' \ - -e 's/^@alphaenumerate/@enumerate/g' \ - -e 's/^@end alphaenumerate/@end enumerate/g' \ - $(srcdir)/gdb.texinfo | \ - $(TEXI2ROFF) -me | \ - sed -e 's/---/\\(em/g' \ - >gdb.me - -# gdb manual suitable for [gtn]roff -ms -gdb.ms: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texi - sed -e '/\\input texinfo/d' \ - -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ - -e '/^@ifinfo/,/^@end ifinfo/d' \ - -e '/^@c /d' \ - -e 's/{.*,,/{/' \ - -e 's/@ / /g' \ - -e 's/^@alphaenumerate/@enumerate/g' \ - -e 's/^@end alphaenumerate/@end enumerate/g' \ - $(srcdir)/gdb.texinfo | \ - $(TEXI2ROFF) -ms | \ - sed -e 's/---/\\(em/g' \ - >gdb.ms - -# gdb manual suitable for [tn]roff -mm -# '@noindent's removed due to texi2roff-2 mm bug; if yours is newer, -# try leaving them in -gdb.mm: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texi - sed -e '/\\input texinfo/d' \ - -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ - -e '/^@ifinfo/,/^@end ifinfo/d' \ - -e '/^@c /d' \ - -e 's/{.*,,/{/' \ - -e '/@noindent/d' \ - -e 's/@ / /g' \ - -e 's/^@alphaenumerate/@enumerate/g' \ - -e 's/^@end alphaenumerate/@end enumerate/g' \ - $(srcdir)/gdb.texinfo | \ - $(TEXI2ROFF) -mm | \ - sed -e 's/---/\\(em/g' \ - >gdb.mm - -# GDB INTERNALS MANUAL: TeX dvi file -gdbint.dvi : gdbint.texinfo - $(SET_TEXINPUTS) $(TEX) gdbint.texinfo - $(TEXINDEX) gdbint.?? - $(SET_TEXINPUTS) $(TEX) gdbint.texinfo - rm -f gdbint.?? gdbint.aux gdbint.cps gdbint.fns gdbint.kys \ - gdbint.log gdbint.pgs gdbint.toc gdbint.tps gdbint.vrs - -# GDB INTERNALS MANUAL: info file -gdb-internals: gdbint.info - -gdbint.info: gdbint.texinfo - $(MAKEINFO) -o gdbint.info $(srcdir)/gdbint.texinfo - -stabs.info: stabs.texinfo - $(MAKEINFO) -o stabs.info $(srcdir)/stabs.texinfo - -# STABS DOCUMENTATION: TeX dvi file -stabs.dvi : stabs.texinfo - $(SET_TEXINPUTS) $(TEX) stabs.texinfo - $(TEXINDEX) stabs.?? - $(SET_TEXINPUTS) $(TEX) stabs.texinfo - rm -f stabs.?? stabs.aux stabs.cps stabs.fns stabs.kys \ - stabs.log stabs.pgs stabs.toc stabs.tps stabs.vrs - -stabs.ps: stabs.dvi - dvips -o stabs.ps stabs - -force: - -Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag) - $(SHELL) ./config.status +.include diff --git a/gnu/usr.bin/gdb/doc/annotate.texi b/gnu/usr.bin/gdb/doc/annotate.texi new file mode 100644 index 00000000000..77165358c07 --- /dev/null +++ b/gnu/usr.bin/gdb/doc/annotate.texi @@ -0,0 +1,708 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename annotate.info +@settitle GDB Annotations +@setchapternewpage off +@c %**end of header + +@set EDITION 0.5 +@set DATE May 1994 + +@ifinfo +This file documents GDB annotations. + +This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB +Annotations}. Copyright 1994 Free Software Foundation + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@titlepage +@title GDB Annotations +@subtitle Edition @value{EDITION} +@subtitle @value{DATE} +@author Cygnus Support +@page +@vskip 0pt plus 1filll +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Copyright @copyright{} 1994 Free Software Foundation +@end titlepage + +@ifinfo +@node Top +@top GDB Annotations + +This file describes annotations in GDB, the GNU symbolic debugger. +Annotations are designed to interface GDB to graphical user interfaces +or other similar programs which want to interact with GDB at a +relatively high level. + +This is Edition @value{EDITION}, @value{DATE}. + +@menu +* General:: What annotations are; the general syntax. +* Server:: Issuing a command without affecting user state. +* Values:: Values are marked as such. +* Frames:: Stack frames are annotated. +* Displays:: GDB can be told to display something periodically. +* Prompting:: Annotations marking GDB's need for input. +* Errors:: Annotations for error messages. +* Breakpoint Info:: Information on breakpoints. +* Invalidation:: Some annotations describe things now invalid. +* Running:: Whether the program is running, how it stopped, etc. +* Source:: Annotations describing source code. +* TODO:: Annotations which might be added in the future. +* Index:: Index +@end menu +@end ifinfo + +@node General +@chapter What is an Annotation? + +To produce annotations, start GDB with the @code{--annotate=2} option. + +Annotations start with a newline character, two @samp{control-z} +characters, and the name of the annotation. If there is no additional +information associated with this annotation, the name of the annotation +is followed immediately by a newline. If there is additional +information, the name of the annotation is followed by a space, the +additional information, and a newline. The additional information +cannot contain newline characters. + +Any output not beginning with a newline and two @samp{control-z} +characters denotes literal output from GDB. Currently there is no need +for GDB to output a newline followed by two @samp{control-z} characters, +but if there was such a need, the annotations could be extended with an +@samp{escape} annotation which means those three characters as output. + +A simple example of starting up GDB with annotations is: + +@example +$ gdb --annotate=2 +GDB is free software and you are welcome to distribute copies of it + under certain conditions; type "show copying" to see the conditions. +There is absolutely no warranty for GDB; type "show warranty" for details. +GDB 4.12.3 (sparc-sun-sunos4.1.3), +Copyright 1994 Free Software Foundation, Inc. + +^Z^Zpre-prompt +(gdb) +^Z^Zprompt +quit + +^Z^Zpost-prompt +$ +@end example + +Here @samp{quit} is input to GDB; the rest is output from GDB. The three +lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z} +character) are annotations; the rest is output from GDB. + +@node Server +@chapter The Server Prefix + +To issue a command to GDB without affecting certain aspects of the state +which is seen by users, prefix it with @samp{server }. This means that +this command will not affect the command history, nor will it affect +GDB's notion of which command to repeat if @key{RET} is pressed on a +line by itself. + +The server prefix does not affect the recording of values into the value +history; to print a value without recording it into the value history, +use the @code{output} command instead of the @code{print} command. + +@node Values +@chapter Values + +When a value is printed in various contexts, GDB uses annotations to +delimit the value from the surrounding text. + +@findex value-history-begin +@findex value-history-value +@findex value-history-end +If a value is printed using @code{print} and added to the value history, +the annotation looks like + +@example +^Z^Zvalue-history-begin @var{history-number} @var{value-flags} +@var{history-string} +^Z^Zvalue-history-value +@var{the-value} +^Z^Zvalue-history-end +@end example + +where @var{history-number} is the number it is getting in the value +history, @var{history-string} is a string, such as @samp{$5 = }, which +introduces the value to the user, @var{the-value} is the output +corresponding to the value itself, and @var{value-flags} is @samp{*} for +a value which can be dereferenced and @samp{-} for a value which cannot. + +@findex value-begin +@findex value-end +If the value is not added to the value history (it is an invalid float +or it is printed with the @code{output} command), the annotation is similar: + +@example +^Z^Zvalue-begin @var{value-flags} +@var{the-value} +^Z^Zvalue-end +@end example + +@findex arg-begin +@findex arg-name-end +@findex arg-value +@findex arg-end +When GDB prints an argument to a function (for example, in the output +from the @code{backtrace} command), it annotates it as follows: + +@example +^Z^Zarg-begin +@var{argument-name} +^Z^Zarg-name-end +@var{separator-string} +^Z^Zarg-value @var{value-flags} +@var{the-value} +^Z^Zarg-end +@end example + +where @var{argument-name} is the name of the argument, +@var{separator-string} is text which separates the name from the value +for the user's benefit (such as @samp{=}), and @var{value-flags} and +@var{the-value} have the same meanings as in a +@code{value-history-begin} annotation. + +@findex field-begin +@findex field-name-end +@findex field-value +@findex field-end +When printing a structure, GDB annotates it as follows: + +@example +^Z^Zfield-begin @var{value-flags} +@var{field-name} +^Z^Zfield-name-end +@var{separator-string} +^Z^Zfield-value +@var{the-value} +^Z^Zfield-end +@end example + +where @var{field-name} is the name of the field, @var{separator-string} +is text which separates the name from the value for the user's benefit +(such as @samp{=}), and @var{value-flags} and @var{the-value} have the +same meanings as in a @code{value-history-begin} annotation. + +When printing an array, GDB annotates it as follows: + +@example +^Z^Zarray-section-begin @var{array-index} @var{value-flags} +@end example + +where @var{array-index} is the index of the first element being +annotated and @var{value-flags} has the same meaning as in a +@code{value-history-begin} annotation. This is followed by any number +of elements, where is element can be either a single element: + +@findex elt +@example +@samp{,} @var{whitespace} ; @r{omitted for the first element} +@var{the-value} +^Z^Zelt +@end example + +or a repeated element + +@findex elt-rep +@findex elt-rep-end +@example +@samp{,} @var{whitespace} ; @r{omitted for the first element} +@var{the-value} +^Z^Zelt-rep @var{number-of-repititions} +@var{repetition-string} +^Z^Zelt-rep-end +@end example + +In both cases, @var{the-value} is the output for the value of the +element and @var{whitespace} can contain spaces, tabs, and newlines. In +the repeated case, @var{number-of-repititons} is the number of +consecutive array elements which contain that value, and +@var{repetition-string} is a string which is designed to convey to the +user that repitition is being depicted. + +@findex array-section-end +Once all the array elements have been output, the array annotation is +ended with + +@example +^Z^Zarray-section-end +@end example + +@node Frames +@chapter Frames + +Whenever GDB prints a frame, it annotates it. For example, this applies +to frames printed when GDB stops, output from commands such as +@code{backtrace} or @code{up}, etc. + +@findex frame-begin +The frame annotation begins with + +@example +^Z^Zframe-begin @var{level} @var{address} +@var{level-string} +@end example + +where @var{level} is the number of the frame (0 is the innermost frame, +and other frames have positive numbers), @var{address} is the address of +the code executing in that frame, and @var{level-string} is a string +designed to convey the level to the user. The frame ends with + +@findex frame-end +@example +^Z^Zframe-end +@end example + +Between these annotations is the main body of the frame, which can +consist of + +@itemize @bullet +@item +@findex function-call +@example +^Z^Zfunction-call +@var{function-call-string} +@end example + +where @var{function-call-string} is text designed to convey to the user +that this frame is associated with a function call made by GDB to a +function in the program being debugged. + +@item +@findex signal-handler-caller +@example +^Z^Zsignal-handler-caller +@var{signal-handler-caller-string} +@end example + +where @var{signal-handler-caller-string} is text designed to convey to +the user that this frame is associated with whatever mechanism is used +by this operating system to call a signal handler (it is the frame which +calls the signal handler, not the frame for the signal handler itself). + +@item +A normal frame. + +@findex frame-address +@findex frame-address-end +This can optionally (depending on whether this is thought of as +interesting information for the user to see) begin with + +@example +^Z^Zframe-address +@var{address} +^Z^Zframe-address-end +@var{separator-string} +@end example + +where @var{address} is the address executing in the frame (the same +address as in the @code{frame-begin} annotation), and +@var{separator-string} is a string intended to separate this address +from what follows for the user's benefit. + +@findex frame-function-name +@findex frame-args +Then comes + +@example +^Z^Zframe-function-name +@var{function-name} +^Z^Zframe-args +@var{arguments} +@end example + +where @var{function-name} is the name of the function executing in the +frame, or @samp{??} if not known, and @var{arguments} are the arguments +to the frame, with parentheses around them (each argument is annotated +individually as well @pxref{Values}). + +@findex frame-source-begin +@findex frame-source-file +@findex frame-source-file-end +@findex frame-source-line +@findex frame-source-end +If source information is available, a reference to it is then printed: + +@example +^Z^Zframe-source-begin +@var{source-intro-string} +^Z^Zframe-source-file +@var{filename} +^Z^Zframe-source-file-end +: +^Z^Zframe-source-line +@var{line-number} +^Z^Zframe-source-end +@end example + +where @var{source-intro-string} separates for the user's benefit the +reference from the text which precedes it, @var{filename} is the name of +the source file, and @var{line-number} is the line number within that +file (the first line is line 1). + +@findex frame-where +If GDB prints some information about where the frame is from (which +library, which load segment, etc.; currently only done on the RS/6000), +it is annotated with + +@example +^Z^Zframe-where +@var{information} +@end example + +Then, if source is to actually be displayed for this frame (for example, +this is not true for output from the @code{backtrace} command), then a +@code{source} annotation (@pxref{Source}) is displayed. Unlike most +annotations, this is output instead of the normal text which would be +output, not in addition. +@end itemize + +@node Displays +@chapter Displays + +@findex display-begin +@findex display-number-end +@findex display-format +@findex display-expression +@findex display-expression-end +@findex display-value +@findex display-end +When GDB is told to display something using the @code{display} command, +the results of the display are annotated: + +@example +^Z^Zdisplay-begin +@var{number} +^Z^Zdisplay-number-end +@var{number-separator} +^Z^Zdisplay-format +@var{format} +^Z^Zdisplay-expression +@var{expression} +^Z^Zdisplay-expression-end +@var{expression-separator} +^Z^Zdisplay-value +@var{value} +^Z^Zdisplay-end +@end example + +where @var{number} is the number of the display, @var{number-separator} +is intended to separate the number from what follows for the user, +@var{format} includes information such as the size, format, or other +information about how the value is being displayed, @var{expression} is +the expression being displayed, @var{expression-separator} is intended +to separate the expression from the text that follows for the user, +and @var{value} is the actual value being displayed. + +@node Prompting +@chapter Annotation for GDB Input + +When GDB prompts for input, it annotates this fact so it is possible +to know when to send output, when the output from a given command is +over, etc. + +Different kinds of input each have a different @dfn{input type}. Each +input type has three annotations: a @code{pre-} annotation, which +denotes the beginning of any prompt which is being output, a plain +annotation, which denotes the end of the prompt, and then a @code{post-} +annotation which denotes the end of any echo which may (or may not) be +associated with the input. For example, the @code{prompt} input type +features the following annotations: + +@example +^Z^Zpre-prompt +^Z^Zprompt +^Z^Zpost-prompt +@end example + +The input types are + +@table @code +@findex pre-prompt +@findex prompt +@findex post-prompt +@item prompt +When GDB is prompting for a command (the main GDB prompt). + +@findex pre-commands +@findex commands +@findex post-commands +@item commands +When GDB prompts for a set of commands, like in the @code{commands} +command. The annotations are repeated for each command which is input. + +@findex pre-overload-choice +@findex overload-choice +@findex post-overload-choice +@item overload-choice +When GDB wants the user to select between various overloaded functions. + +@findex pre-query +@findex query +@findex post-query +@item query +When GDB wants the user to confirm a potentially dangerous operation. + +@findex pre-prompt-for-continue +@findex prompt-for-continue +@findex post-prompt-for-continue +@item prompt-for-continue +When GDB is asking the user to press return to continue. Note: Don't +expect this to work well; instead use @code{set height 0} to disable +prompting. This is because the counting of lines is buggy in the +presence of annotations. +@end table + +@node Errors +@chapter Errors + +@findex quit +@example +^Z^Zquit +@end example + +This annotation occurs right before GDB responds to an interrupt. + +@findex error +@example +^Z^Zerror +@end example + +This annotation occurs right before GDB responds to an error. + +Quit and error annotations indicate that any annotations which GDB was +in the middle of may end abruptly. For example, if a +@code{value-history-begin} annotation is followed by a @code{error}, one +cannot expect to receive the matching @code{value-history-end}. One +cannot expect not to receive it either, however; an error annotation +does not necessarily mean that GDB is immediately returning all the way +to the top level. + +@findex error-begin +A quit or error annotation may be preceded by + +@example +^Z^Zerror-begin +@end example + +Any output between that and the quit or error annotation is the error +message. + +Warning messages are not yet annotated. +@c If we want to change that, need to fix warning(), type_error(), +@c range_error(), and possibly other places. + +@node Breakpoint Info +@chapter Information on Breakpoints + +The output from the @code{info breakpoints} command is annotated as follows: + +@findex breakpoints-headers +@findex breakpoints-table +@example +^Z^Zbreakpoints-headers +@var{header-entry} +^Z^Zbreakpoints-table +@end example + +where @var{header-entry} has the same syntax as an entry (see below) but +instead of containing data, it contains strings which are intended to +convey the meaning of each field to the user. This is followed by any +number of entries. If a field does not apply for this entry, it is +omitted. Fields may contain trailing whitespace. Each entry consists +of: + +@findex record +@findex field +@example +^Z^Zrecord +^Z^Zfield 0 +@var{number} +^Z^Zfield 1 +@var{type} +^Z^Zfield 2 +@var{disposition} +^Z^Zfield 3 +@var{enable} +^Z^Zfield 4 +@var{address} +^Z^Zfield 5 +@var{what} +^Z^Zfield 6 +@var{frame} +^Z^Zfield 7 +@var{condition} +^Z^Zfield 8 +@var{ignore-count} +^Z^Zfield 9 +@var{commands} +@end example + +The output ends with + +@findex breakpoints-table-end +@example +^Z^Zbreakpoints-table-end +@end example + +@node Invalidation +@chapter Invalidation Notices + +The following annotations say that certain pieces of state may have +changed. + +@table @code +@findex frames-invalid +@item ^Z^Zframes-invalid + +The frames (for example, output from the @code{backtrace} command) may +have changed. + +@findex breakpoints-invalid +@item ^Z^Zbreakpoints-invalid + +The breakpoints may have changed. For example, the user just added or +deleted a breakpoint. +@end table + +@node Running +@chapter Running the Program + +@findex starting +@findex stopping +When the program starts executing due to a GDB command such as +@code{step} or @code{continue}, + +@example +^Z^Zstarting +@end example + +is output. When the program stops, + +@example +^Z^Zstopped +@end example + +is output. Before the @code{stopped} annotation, a variety of +annotations describe how the program stopped. + +@table @code +@findex exited +@item ^Z^Zexited @var{exit-status} +The program exited, and @var{exit-status} is the exit status (zero for +successful exit, otherwise nonzero). + +@findex signalled +@findex signal-name +@findex signal-name-end +@findex signal-string +@findex signal-string-end +@item ^Z^Zsignalled +The program exited with a signal. After the @code{^Z^Zsignalled}, the +annotation continues: + +@example +@var{intro-text} +^Z^Zsignal-name +@var{name} +^Z^Zsignal-name-end +@var{middle-text} +^Z^Zsignal-string +@var{string} +^Z^Zsignal-string-end +@var{end-text} +@end example + +where @var{name} is the name of the signal, such as @code{SIGILL} or +@code{SIGSEGV}, and @var{string} is the explanation of the signal, such +as @code{Illegal Instruction} or @code{Segmentation fault}. +@var{intro-text}, @var{middle-text}, and @var{end-text} are for the +user's benefit and have no particular format. + +@findex signal +@item ^Z^Zsignal +The syntax of this annotation is just like @code{signalled}, but GDB is +just saying that the program received the signal, not that it was +terminated with it. + +@findex breakpoint +@item ^Z^Zbreakpoint @var{number} +The program hit breakpoint number @var{number}. + +@findex watchpoint +@item ^Z^Zwatchpoint @var{number} +The program hit watchpoint number @var{number}. +@end table + +@node Source +@chapter Displaying Source + +@findex source +The following annotation is used instead of displaying source code: + +@example +^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} +@end example + +where @var{filename} is an absolute file name indicating which source +file, @var{line} is the line number within that file (where 1 is the +first line in the file), @var{character} is the character position +within the file (where 0 is the first character in the file) (for most +debug formats this will necessarily point to the beginning of a line), +@var{middle} is @samp{middle} if @var{addr} is in the middle of the +line, or @samp{beg} if @var{addr} is at the beginning of the line, and +@var{addr} is the address in the target program associated with the +source which is being displayed. + +@node TODO +@chapter Annotations We Might Want in the Future + +@format + - target-invalid + the target might have changed (registers, heap contents, or + execution status). For performance, we might eventually want + to hit `registers-invalid' and `all-registers-invalid' with + greater precision + + - systematic annotation for set/show parameters (including + invalidation notices). + + - similarly, `info' returns a list of candidates for invalidation + notices. +@end format + +@node Index +@unnumbered Index + +@printindex fn + +@bye diff --git a/gnu/usr.bin/gdb/doc/gdb.texinfo b/gnu/usr.bin/gdb/doc/gdb.texinfo index a2f293deb2a..5db92537fc5 100644 --- a/gnu/usr.bin/gdb/doc/gdb.texinfo +++ b/gnu/usr.bin/gdb/doc/gdb.texinfo @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@c Copyright (c) 1988 1989 1990 1991 1992 1993 Free Software Foundation, Inc. +@c Copyright 1988 1989 1990 1991 1992 1993 1994 Free Software Foundation, Inc. @c @c %**start of header @c makeinfo ignores cmds prev to setfilename, so its arg cannot make use @@ -28,10 +28,11 @@ @c readline appendices use @vindex @syncodeindex vr cp -@c ===> NOTE! <== -@c Determine the edition number in *three* places by hand: -@c 1. First ifinfo section 2. title page 3. top node -@c To find the locations, search for !!set +@c !!set GDB manual's edition---not the same as GDB version! +@set EDITION 4.12 + +@c !!set GDB manual's revision date +@set DATE January 1994 @c GDB CHANGELOG CONSULTED BETWEEN: @c Fri Oct 11 23:27:06 1991 John Gilmore (gnu at cygnus.com) @@ -44,7 +45,7 @@ @c manuals to an info tree. zoo@cygnus.com is developing this facility. @format START-INFO-DIR-ENTRY -* Gdb:: The GNU debugger. +* Gdb: (gdb). The GNU debugger. END-INFO-DIR-ENTRY @end format @end ifinfo @@ -53,8 +54,8 @@ END-INFO-DIR-ENTRY @ifinfo This file documents the GNU debugger @value{GDBN}. -@c !!set edition, date, version -This is Edition 4.09, August 1993, + +This is Edition @value{EDITION}, @value{DATE}, of @cite{Debugging with @value{GDBN}: the GNU Source-Level Debugger} for GDB Version @value{GDBVN}. @@ -87,9 +88,8 @@ into another language, under the above conditions for modified versions. @subtitle (@value{TARGET}) @end ifclear @sp 1 -@c !!set edition, date, version -@subtitle Edition 4.09, for @value{GDBN} version @value{GDBVN} -@subtitle August 1993 +@subtitle Edition @value{EDITION}, for @value{GDBN} version @value{GDBVN} +@subtitle @value{DATE} @author Richard M. Stallman and Roland H. Pesch @page @tex @@ -131,8 +131,7 @@ into another language, under the above conditions for modified versions. This file describes @value{GDBN}, the GNU symbolic debugger. -@c !!set edition, date, version -This is Edition 4.09, August 1993, for GDB Version @value{GDBVN}. +This is Edition @value{EDITION}, @value{DATE}, for GDB Version @value{GDBVN}. @menu * Summary:: Summary of @value{GDBN} @@ -209,19 +208,28 @@ effects of one bug and go on to learn about another. @end itemize @ifclear CONLY -@ifclear MOD2 You can use @value{GDBN} to debug programs written in C or C++. +@c "MOD2" used as a "miscellaneous languages" flag here. +@c This is acceptable while there is no real doc for Chill and Pascal. +@ifclear MOD2 +For more information, see @ref{Support,,Supported languages}. @end ifclear @ifset MOD2 -You can use @value{GDBN} to debug programs written in C, C++, and -Modula-2. +For more information, see @ref{C,,C and C++}. + +Support for Modula-2 and Chill is partial. For information on Modula-2, +see @ref{Modula-2,,Modula-2}. There is no further documentation on Chill yet. + +Debugging Pascal programs which use sets, subranges, file variables, or nested +functions does not currently work. @value{GDBN} does not support +entering expressions, printing values, or similar features using Pascal syntax. @end ifset @ifset FORTRAN @cindex Fortran @value{GDBN} can be used to debug programs written in Fortran, although -it does not yet support entering expressions, printing values, etc. -using Fortran syntax. It may be necessary to refer to some variables -with a trailing underscore. +it does not yet support entering expressions, printing values, or +similar features using Fortran syntax. It may be necessary to refer to +some variables with a trailing underscore. @end ifset @end ifclear @@ -265,11 +273,13 @@ omitted from this list, we would like to add your names! @end quotation So that they may not regard their long labor as thankless, we -particularly thank those who shepherded GDB through major releases: Fred -Fish (releases 4.11, 4.10, 4.9), Stu Grossman and John Gilmore (releases -4.8, 4.7, 4.6, 4.5, 4.4), John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and -3.9); Jim Kingdon (releases 3.5, 3.4, 3.3); and Randy Smith (releases -3.2, 3.1, 3.0). As major maintainer of GDB for some period, each +particularly thank those who shepherded GDB through major releases: +Fred Fish (releases 4.12, 4.11, 4.10, and 4.9), +Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4), +John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); +Jim Kingdon (releases 3.5, 3.4, and 3.3); +and Randy Smith (releases 3.2, 3.1, and 3.0). +As major maintainer of GDB for some period, each contributed significantly to the structure, stability, and capabilities of the entire debugger. @@ -292,17 +302,22 @@ the original support for encapsulated COFF. Adam de Boor and Bradley Davis contributed the ISI Optimum V support. Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS -support. Jean-Daniel Fekete contributed Sun 386i support. Chris -Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki -Hasei contributed Sony/News OS 3 support. David Johnson contributed -Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. -Keith Packard contributed NS32K support. Doug Rabson contributed -Acorn Risc Machine support. Chris Smith contributed Convex support -(and Fortran debugging). Jonathan Stone contributed Pyramid support. -Michael Tiemann contributed SPARC support. Tim Tucker contributed -support for the Gould NP1 and Gould Powernode. Pace Willison -contributed Intel 386 support. Jay Vosburgh contributed Symmetry support. +Jean-Daniel Fekete contributed Sun 386i support. +Chris Hanson improved the HP9000 support. +Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. +David Johnson contributed Encore Umax support. +Jyrki Kuoppala contributed Altos 3068 support. +Jeff Law contributed HP PA and SOM support. +Keith Packard contributed NS32K support. +Doug Rabson contributed Acorn Risc Machine support. +Bob Rusk contributed Harris Nighthawk CX-UX support. +Chris Smith contributed Convex support (and Fortran debugging). +Jonathan Stone contributed Pyramid support. +Michael Tiemann contributed SPARC support. +Tim Tucker contributed support for the Gould NP1 and Gould Powernode. +Pace Willison contributed Intel 386 support. +Jay Vosburgh contributed Symmetry support. Rich Schaefer and Peter Schauer helped with support of SunOS shared libraries. @@ -331,6 +346,14 @@ symbols. Hitachi America, Ltd. sponsored the support for Hitachi microprocessors. +Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware +watchpoints. + +Stu Grossman wrote gdbserver. + +Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made +nearly innumerable bug fixes and cleanups throughout GDB. + @ifset NOVEL @node New Features @unnumbered New Features since GDB Version 3.5 @@ -339,7 +362,7 @@ Hitachi America, Ltd. sponsored the support for Hitachi microprocessors. @item Targets Using the new command @code{target}, you can select at runtime whether you are debugging local files, local processes, standalone systems over -a serial port, realtime systems over a TCP/IP connection, etc. The +a serial port, or realtime systems over a TCP/IP connection. The command @code{load} can download programs into a remote system. Serial stubs are available for Motorola 680x0, Intel 80386, and Sparc remote systems; GDB also supports debugging realtime processes running under @@ -410,6 +433,9 @@ of your program, and the latter refer to the state of GDB itself. GDB 4 can debug programs and core files that use SunOS, SVR4, or IBM RS/6000 shared libraries. +@item Threads +On some systems, GDB 4 has facilities to debug multi-thread programs. + @item Reference Card GDB 4 has a reference card. @xref{Formatting Documentation,,Formatting the Documentation}, for instructions about how to print it. @@ -478,10 +504,10 @@ GDB @value{GDBVN}, Copyright 1993 Free Software Foundation, Inc... @end smallexample @noindent -@value{GDBN} reads only enough symbol data to know where to find the rest when -needed; as a result, the first prompt comes up very quickly. We now -tell @value{GDBN} to use a narrower display width than usual, so that examples -will fit in this manual. +@value{GDBN} reads only enough symbol data to know where to find the +rest when needed; as a result, the first prompt comes up very quickly. +We now tell @value{GDBN} to use a narrower display width than usual, so +that examples fit in this manual. @smallexample (@value{GDBP}) @b{set width 70} @@ -570,7 +596,7 @@ stack frame for each active subroutine. @end smallexample @noindent -We will step through a few more lines to see what happens. The first two +We step through a few more lines to see what happens. The first two times, we can use @samp{s}; the next two times we use @code{n} to avoid falling into the @code{xstrdup} subroutine. @@ -783,8 +809,8 @@ in sequential order. The order makes a difference when the * i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy) @end ifset @ifset AMD29K -* UDI29K Remote:: @value{GDBN} and the UDI protocol for AMD29K -* EB29K Remote:: @value{GDBN} with a remote EB29K +* UDI29K Remote:: The UDI protocol for AMD29K +* EB29K Remote:: The EBMON protocol for AMD29K @end ifset @ifset VXWORKS * VxWorks Remote:: @value{GDBN} and VxWorks @@ -886,9 +912,9 @@ If memory-mapped files are available on your system through the @code{mmap} system call, you can use this option to have @value{GDBN} write the symbols from your program into a reusable file in the current directory. If the program you are debugging is -called @file{/tmp/fred}, the mapped symbol file will be @file{./fred.syms}. -Future @value{GDBN} debugging sessions will notice the presence of this file, -and will quickly map in symbol information from it, rather than reading +called @file{/tmp/fred}, the mapped symbol file is @file{./fred.syms}. +Future @value{GDBN} debugging sessions notice the presence of this file, +and can quickly map in symbol information from it, rather than reading the symbol table from the executable program. @c FIXME! Really host, not target? @@ -1006,9 +1032,9 @@ an end-of-file character (usually @kbd{C-d}). @end table @cindex interrupt -An interrupt (often @kbd{C-c}) will not exit from @value{GDBN}, but rather -will terminate the action of any @value{GDBN} command that is in progress and -return to @value{GDBN} command level. It is safe to type the interrupt +An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather +terminates the action of any @value{GDBN} command that is in progress and +returns to @value{GDBN} command level. It is safe to type the interrupt character at any time because @value{GDBN} does not allow it to take effect until a time when it is safe. @@ -1086,7 +1112,7 @@ arguments to the @code{help} command. @kindex RET A blank line as input to @value{GDBN} (typing just @key{RET}) means to repeat the previous command. Certain commands (for example, @code{run}) -will not repeat this way; these are commands for which unintentional +will not repeat this way; these are commands whose unintentional repetition might cause trouble and which you are unlikely to want to repeat. @@ -1117,8 +1143,8 @@ are for the next word in a command, at any time. This works for @value{GDBN} commands, @value{GDBN} subcommands, and the names of symbols in your program. Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest -of a word. If there is only one possibility, @value{GDBN} will fill in the -word, and wait for you to finish the command (or press @key{RET} to +of a word. If there is only one possibility, @value{GDBN} fills in the +word, and waits for you to finish the command (or press @key{RET} to enter it). For example, if you type @c FIXME "@key" does not distinguish its argument sufficiently to permit @@ -1146,12 +1172,12 @@ might as well just type @key{RET} immediately after @samp{info bre}, to exploit command abbreviations rather than command completion). If there is more than one possibility for the next word when you press -@key{TAB}, @value{GDBN} will sound a bell. You can either supply more -characters and try again, or just press @key{TAB} a second time, and -@value{GDBN} will display all the possible completions for that word. For +@key{TAB}, @value{GDBN} sounds a bell. You can either supply more +characters and try again, or just press @key{TAB} a second time; +@value{GDBN} displays all the possible completions for that word. For example, you might want to set a breakpoint on a subroutine whose name begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} -just sounds the bell. Typing @key{TAB} again will display all the +just sounds the bell. Typing @key{TAB} again displays all the function names in your program that begin with those characters, for example: @@ -1207,8 +1233,8 @@ bubble(double,double) bubble(int,int) (@value{GDBP}) b 'bubble( @end example -In some cases, @value{GDBN} can tell that completing a name will require -quotes. When this happens, @value{GDBN} will insert the quote for you (while +In some cases, @value{GDBN} can tell that completing a name requires using +quotes. When this happens, @value{GDBN} inserts the quote for you (while completing as much as it can) if you do not type the quote in the first place: @@ -1287,7 +1313,7 @@ Command name abbreviations are allowed if unambiguous. @end smallexample @item help @var{command} -With a command name as @code{help} argument, @value{GDBN} will display a +With a command name as @code{help} argument, @value{GDBN} displays a short paragraph on how to use that command. @end table @@ -1373,6 +1399,7 @@ already running process, or kill a child process. * Attach:: Debugging an already-running process * Kill Process:: Killing the child process * Process Information:: Additional process information +* Threads:: Debugging programs with multiple threads @end ifclear @end menu @@ -1401,10 +1428,10 @@ your luck. @cindex optimized code, debugging @cindex debugging optimized code When you debug a program compiled with @samp{-g -O}, remember that the -optimizer is rearranging your code; the debugger will show you what is +optimizer is rearranging your code; the debugger shows you what is really there. Do not be too surprised when the execution path does not exactly match your source file! An extreme example: if you define a -variable, but never use it, @value{GDBN} will never see that +variable, but never use it, @value{GDBN} never sees that variable---because the compiler optimizes it out of existence. Some things do not work as well with @samp{-g -O} as with just @@ -1446,7 +1473,7 @@ that process run your program. (In environments without processes, The execution of a program is affected by certain information it receives from its superior. @value{GDBN} provides ways to specify this information, which you must do @emph{before} starting your program. (You -can change it after starting your program, but such changes will only affect +can change it after starting your program, but such changes only affect your program the next time you start it.) This information may be divided into four categories: @@ -1463,7 +1490,7 @@ program's arguments}. @item The @emph{environment.} Your program normally inherits its environment from @value{GDBN}, but you can use the @value{GDBN} commands @code{set environment} and @code{unset -environment} to change parts of the environment that will be given to +environment} to change parts of the environment that affect your program. @xref{Environment, ,Your program's environment}. @item The @emph{working directory.} @@ -1492,10 +1519,10 @@ of how to arrange for your program to stop. Once your program has stopped, you may call functions in your program, using the @code{print} or @code{call} commands. @xref{Data, ,Examining Data}. -If the modification time of your symbol file has changed since the -last time @value{GDBN} read its symbols, @value{GDBN} will discard its symbol table and -re-read it. When it does this, @value{GDBN} tries to retain your current -breakpoints. +If the modification time of your symbol file has changed since the last +time @value{GDBN} read its symbols, @value{GDBN} discards its symbol +table, and reads it again. When it does this, @value{GDBN} tries to retain +your current breakpoints. @ifclear BARETARGET @node Arguments @@ -1506,8 +1533,8 @@ The arguments to your program can be specified by the arguments of the @code{run} command. They are passed to a shell, which expands wildcard characters and performs redirection of I/O, and thence to your program. Your @code{SHELL} environment variable (if it exists) specifies what -shell @value{GDBN} if you do not define @code{SHELL}, @value{GDBN} uses -@code{/bin/sh}. +shell @value{GDBN} uses. If you do not define @code{SHELL}, +@value{GDBN} uses @code{/bin/sh}. @code{run} with no arguments uses the same arguments used by the previous @code{run}, or those set by the @code{set args} command. @@ -1516,7 +1543,7 @@ shell @value{GDBN} if you do not define @code{SHELL}, @value{GDBN} uses @table @code @item set args Specify the arguments to be used the next time your program is run. If -@code{set args} has no arguments, @code{run} will execute your program +@code{set args} has no arguments, @code{run} executes your program with no arguments. Once you have run your program with arguments, using @code{set args} before the next @code{run} is the only way to run it again without arguments. @@ -1545,7 +1572,7 @@ Add @var{directory} to the front of the @code{PATH} environment variable (the search path for executables), for both @value{GDBN} and your program. You may specify several directory names, separated by @samp{:} or whitespace. If @var{directory} is already in the path, it is moved to -the front, so it will be searched sooner. +the front, so it is searched sooner. You can use the string @samp{$cwd} to refer to whatever is the current working directory at the time @value{GDBN} searches the path. If you @@ -1602,7 +1629,7 @@ rather than assigning it an empty value. by your @code{SHELL} environment variable if it exists (or @code{/bin/sh} if not). If your @code{SHELL} variable names a shell that runs an initialization file---such as @file{.cshrc} for C-shell, or -@file{.bashrc} for BASH---any variables you set in that file will affect +@file{.bashrc} for BASH---any variables you set in that file affect your program. You may wish to move setting of environment variables to files that are only run when you sign on, such as @file{.login} or @file{.profile}. @@ -1693,12 +1720,12 @@ for @value{GDBN} still comes from your terminal. @table @code @item attach @var{process-id} This command attaches to a running process---one that was started -outside @value{GDBN}. (@code{info files} will show your active +outside @value{GDBN}. (@code{info files} shows your active targets.) The command takes as argument a process ID. The usual way to find out the process-id of a Unix process is with the @code{ps} utility, or with the @samp{jobs -l} shell command. -@code{attach} will not repeat if you press @key{RET} a second time after +@code{attach} does not repeat if you press @key{RET} a second time after executing the command. @end table @@ -1727,15 +1754,16 @@ When you have finished debugging the attached process, you can use the the process continues its execution. After the @code{detach} command, that process and @value{GDBN} become completely independent once more, and you are ready to @code{attach} another process or start one with @code{run}. -@code{detach} will not repeat if you press @key{RET} again after +@code{detach} does not repeat if you press @key{RET} again after executing the command. @end table -If you exit @value{GDBN} or use the @code{run} command while you have an attached -process, you kill that process. By default, you will be asked for -confirmation if you try to do either of these things; you can control -whether or not you need to confirm by using the @code{set confirm} command -(@pxref{Messages/Warnings, ,Optional warnings and messages}). +If you exit @value{GDBN} or use the @code{run} command while you have an +attached process, you kill that process. By default, @value{GDBN} asks +for confirmation if you try to do either of these things; you can +control whether or not you need to confirm by using the @code{set +confirm} command (@pxref{Messages/Warnings, ,Optional warnings and +messages}). @node Kill Process @c @group @@ -1760,8 +1788,8 @@ outside the debugger. The @code{kill} command is also useful if you wish to recompile and relink your program, since on many systems it is impossible to modify an executable file while it is running in a process. In this case, when you -next type @code{run}, @value{GDBN} will notice that the file has changed, and -will re-read the symbol table (while trying to preserve your current +next type @code{run}, @value{GDBN} notices that the file has changed, and +reads the symbol table again (while trying to preserve your current breakpoint settings). @node Process Information @@ -1804,6 +1832,157 @@ received. @item info proc all Show all the above information about the process. @end table + +@node Threads +@section Debugging programs with multiple threads + +@cindex threads of execution +@cindex multiple threads +@cindex switching threads +In some operating systems, a single program may have more than one +@dfn{thread} of execution. The precise semantics of threads differ from +one operating system to another, but in general the threads of a single +program are akin to multiple processes---except that they share one +address space (that is, they can all examine and modify the same +variables). On the other hand, each thread has its own registers and +execution stack, and perhaps private memory. + +@value{GDBN} provides these facilities for debugging multi-thread +programs: + +@itemize @bullet +@item automatic notification of new threads +@item @samp{thread @var{threadno}}, a command to switch among threads +@item @samp{info threads}, a command to inquire about existing threads +@item thread-specific breakpoints +@end itemize + +@quotation +@emph{Warning:} These facilities are not yet available on every +@value{GDBN} configuration where the operating system supports threads. +If your @value{GDBN} does not support threads, these commands have no +effect. For example, a system without thread support shows no output +from @samp{info threads}, and always rejects the @code{thread} command, +like this: + +@smallexample +(@value{GDBP}) info threads +(@value{GDBP}) thread 1 +Thread ID 1 not known. Use the "info threads" command to +see the IDs of currently known threads. +@end smallexample +@c FIXME to implementors: how hard would it be to say "sorry, this GDB +@c doesn't support threads"? +@end quotation + +@cindex focus of debugging +@cindex current thread +The @value{GDBN} thread debugging facility allows you to observe all +threads while your program runs---but whenever @value{GDBN} takes +control, one thread in particular is always the focus of debugging. +This thread is called the @dfn{current thread}. Debugging commands show +program information from the perspective of the current thread. + +@kindex New @var{systag} +@cindex thread identifier (system) +@c FIXME-implementors!! It would be more helpful if the [New...] message +@c included GDB's numeric thread handle, so you could just go to that +@c thread without first checking `info threads'. +Whenever @value{GDBN} detects a new thread in your program, it displays +the target system's identification for the thread with a message in the +form @samp{[New @var{systag}]}. @var{systag} is a thread identifier +whose form varies depending on the particular system. For example, on +LynxOS, you might see + +@example +[New process 35 thread 27] +@end example + +@noindent +when @value{GDBN} notices a new thread. In contrast, on an SGI system, +the @var{systag} is simply something like @samp{process 368}, with no +further qualifier. + +@c FIXME!! (1) Does the [New...] message appear even for the very first +@c thread of a program, or does it only appear for the +@c second---i.e., when it becomes obvious we have a multithread +@c program? +@c (2) *Is* there necessarily a first thread always? Or do some +@c multithread systems permit starting a program with multiple +@c threads ab initio? + +@cindex thread number +@cindex thread identifier (GDB) +For debugging purposes, @value{GDBN} associates its own thread +number---always a single integer---with each thread in your program. + +@table @code +@item info threads +@kindex info threads +Display a summary of all threads currently in your +program. @value{GDBN} displays for each thread (in this order): + +@enumerate +@item the thread number assigned by @value{GDBN} + +@item the target system's thread identifier (@var{systag}) + +@item the current stack frame summary for that thread +@end enumerate + +@noindent +An asterisk @samp{*} to the left of the @value{GDBN} thread number +indicates the current thread. + +For example, +@end table +@c end table here to get a little more width for example + +@smallexample +(@value{GDBP}) info threads + 3 process 35 thread 27 0x34e5 in sigpause () + 2 process 35 thread 23 0x34e5 in sigpause () +* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + at threadtest.c:68 +@end smallexample + +@table @code +@item thread @var{threadno} +@kindex thread @var{threadno} +Make thread number @var{threadno} the current thread. The command +argument @var{threadno} is the internal @value{GDBN} thread number, as +shown in the first field of the @samp{info threads} display. +@value{GDBN} responds by displaying the system identifier of the thread +you selected, and its current stack frame summary: + +@smallexample +@c FIXME!! This example made up; find a GDB w/threads and get real one +(@value{GDBP}) thread 2 +[Switching to process 35 thread 23] +0x34e5 in sigpause () +@end smallexample + +@noindent +As with the @samp{[New @dots{}]} message, the form of the text after +@samp{Switching to} depends on your system's conventions for identifying +threads. +@end table + +@cindex automatic thread selection +@cindex switching threads automatically +@cindex threads, automatic switching +Whenever @value{GDBN} stops your program, due to a breakpoint or a +signal, it automatically selects the thread where that breakpoint or +signal happened. @value{GDBN} alerts you to the context switch with a +message of the form @samp{[Switching to @var{systag}]} to identify the +thread. + +@xref{Thread Stops,,Stopping and starting multi-thread programs}, for +more information about how @value{GDBN} behaves when you stop and start +programs with multiple threads. + +@xref{Set Watchpoints,,Setting watchpoints}, for information about +watchpoints in programs with multiple threads. @end ifclear @node Stopping @@ -1849,6 +2028,9 @@ and why it stopped. @ifset POSIX * Signals:: Signals @end ifset +@ifclear BARETARGET +* Thread Stops:: Stopping and starting multi-thread programs +@end ifclear @end menu @c makeinfo node-defaulting requires adjacency of @node and sectioning cmds @@ -1865,16 +2047,16 @@ and why it stopped. @cindex breakpoints A @dfn{breakpoint} makes your program stop whenever a certain point in -the program is reached. For each breakpoint, you can add various -conditions to control in finer detail whether your program will stop. +the program is reached. For each breakpoint, you can add +conditions to control in finer detail whether your program stops. You can set breakpoints with the @code{break} command and its variants (@pxref{Set Breaks, ,Setting breakpoints}), to specify the place where your program should stop by line number, function name or exact address in the program. @ifclear CONLY In languages with exception handling (such as GNU C++), you can also set -breakpoints where an exception is raised (@pxref{Exception Handling, -,Breakpoints and exceptions}). +breakpoints where an exception is raised (@pxref{Exception Handling,, +Breakpoints and exceptions}). @end ifclear @cindex watchpoints @@ -1889,8 +2071,8 @@ any other breakpoint: you enable, disable, and delete both breakpoints and watchpoints using the same commands. You can arrange to have values from your program displayed automatically -whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display, -,Automatic display}. +whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, +Automatic display}. @cindex breakpoint numbers @cindex numbers for breakpoints @@ -1957,7 +2139,7 @@ at which execution stopped in the currently selected frame. @item break @var{linenum} Set a breakpoint at line @var{linenum} in the current source file. That file is the last file whose source text was printed. This -breakpoint will stop your program just before it executes any of the +breakpoint stops your program just before it executes any of the code on that line. @item break @var{filename}:@var{linenum} @@ -1978,11 +2160,11 @@ information or source files. When called without any arguments, @code{break} sets a breakpoint at the next instruction to be executed in the selected stack frame (@pxref{Stack, ,Examining the Stack}). In any selected frame but the -innermost, this will cause your program to stop as soon as control +innermost, this makes your program stop as soon as control returns to that frame. This is similar to the effect of a @code{finish} command in the frame inside the selected frame---except that @code{finish} does not leave an active breakpoint. If you use -@code{break} without an argument in the innermost frame, @value{GDBN} will stop +@code{break} without an argument in the innermost frame, @value{GDBN} stops the next time it reaches the current location; this may be useful inside loops. @@ -2004,7 +2186,7 @@ above (or no argument) specifying where to break. @xref{Conditions, @kindex tbreak Set a breakpoint enabled only for one stop. @var{args} are the same as for the @code{break} command, and the breakpoint is set in the same -way, but the breakpoint is automatically disabled after the first time your +way, but the breakpoint is automatically deleted after the first time your program stops there. @xref{Disabling, ,Disabling breakpoints}. @item rbreak @var{regex} @@ -2014,9 +2196,10 @@ program stops there. @xref{Disabling, ,Disabling breakpoints}. Set breakpoints on all functions matching the regular expression @var{regex}. This command sets an unconditional breakpoint on all matches, printing a list of all -breakpoints it set. Once these breakpoints are set, they are treated -just like the breakpoints set with the @code{break} command. They can -be deleted, disabled, made conditional, etc., in the standard ways. +breakpoints it set. Once these breakpoints are set, they are treated +just like the breakpoints set with the @code{break} command. You can +delete them, disable them, or make them conditional the same way as any +other breakpoint. @ifclear CONLY When debugging C++ programs, @code{rbreak} is useful for setting @@ -2119,9 +2302,18 @@ where this may happen. Watchpoints currently execute two orders of magnitude more slowly than other breakpoints, but this can be well worth it to catch errors where -you have no clue what part of your program is the culprit. Some -processors provide special hardware to support watchpoint evaluation; future -releases of @value{GDBN} will use such hardware if it is available. +you have no clue what part of your program is the culprit. + +@ignore +@c this "future releases" promise has been in too long, is getting +@c embarrassing. But... +@c FIXME: in future updates, check whether hardware watchpoints in on any +@c platforms yet. As of 26jan94, they're very close on HPPA running +@c Berkeley and on Irix 4. +Some processors provide special hardware to support watchpoint +evaluation; future releases of @value{GDBN} will use such hardware if it +is available. +@end ignore @table @code @kindex watch @@ -2134,6 +2326,21 @@ This command prints a list of watchpoints and breakpoints; it is the same as @code{info break}. @end table +@ifclear BARETARGET +@quotation +@cindex watchpoints and threads +@cindex threads and watchpoints +@emph{Warning:} in multi-thread programs, watchpoints have only limited +usefulness. With the current watchpoint implementation, @value{GDBN} +can only watch the value of an expression @emph{in a single thread}. If +you are confident that the expression can only change due to the current +thread's activity (and if you are also confident that no other thread +can become current), then you can use watchpoints as usual. However, +@value{GDBN} may not notice when a non-current thread's activity changes +the expression. +@end quotation +@end ifclear + @ifclear CONLY @node Exception Handling @subsection Breakpoints and exceptions @@ -2155,8 +2362,7 @@ to catch. You can use @code{info catch} to list active exception handlers. @xref{Frame Info, ,Information about a frame}. -There are currently some limitations to exception handling in @value{GDBN}. -These will be corrected in a future release. +There are currently some limitations to exception handling in @value{GDBN}: @itemize @bullet @item @@ -2166,10 +2372,12 @@ raises an exception, however, the call may bypass the mechanism that returns control to you and cause your program to simply continue running until it hits a breakpoint, catches a signal that @value{GDBN} is listening for, or exits. + @item You cannot raise an exception interactively. + @item -You cannot interactively install an exception handler. +You cannot install an exception handler interactively. @end itemize @cindex raise exceptions @@ -2269,17 +2477,17 @@ enablement: @itemize @bullet @item -Enabled. The breakpoint will stop your program. A breakpoint set +Enabled. The breakpoint stops your program. A breakpoint set with the @code{break} command starts out in this state. @item Disabled. The breakpoint has no effect on your program. @item -Enabled once. The breakpoint will stop your program, but -when it does so it will become disabled. A breakpoint set -with the @code{tbreak} command starts out in this state. +Enabled once. The breakpoint stops your program, but then becomes +disabled. A breakpoint set with the @code{tbreak} command starts out in +this state. @item -Enabled for deletion. The breakpoint will stop your program, but -immediately after it does so it will be deleted permanently. +Enabled for deletion. The breakpoint stops your program, but +immediately after it does so it is deleted permanently. @end itemize You can use the following commands to enable or disable breakpoints and @@ -2303,19 +2511,19 @@ Enable the specified breakpoints (or all defined breakpoints). They become effective once again in stopping your program. @item enable @r{[}breakpoints@r{]} once @var{bnums}@dots{} -Enable the specified breakpoints temporarily. Each will be disabled -again the next time it stops your program. +Enable the specified breakpoints temporarily. @value{GDBN} disables any +of these breakpoints immediately after stopping your program. @item enable @r{[}breakpoints@r{]} delete @var{bnums}@dots{} -Enable the specified breakpoints to work once and then die. Each of -the breakpoints will be deleted the next time it stops your program. +Enable the specified breakpoints to work once, then die. @value{GDBN} +deletes any of these breakpoints as soon as your program stops there. @end table Save for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, ,Setting breakpoints}), breakpoints that you set are initially enabled; subsequently, they become disabled or enabled only when you use one of the commands above. (The command @code{until} can set and delete a -breakpoint of its own, but it will not change the state of your other +breakpoint of its own, but it does not change the state of your other breakpoints; see @ref{Continuing and Stepping, ,Continuing and stepping}.) @@ -2367,11 +2575,12 @@ impose a further condition on a watchpoint. @item condition @var{bnum} @var{expression} @kindex condition Specify @var{expression} as the break condition for breakpoint or -watchpoint number @var{bnum}. From now on, this breakpoint will stop -your program only if the value of @var{expression} is true (nonzero, in -C). When you use @code{condition}, @value{GDBN} checks @var{expression} -immediately for syntactic correctness, and to determine whether symbols -in it have referents in the context of your breakpoint. +watchpoint number @var{bnum}. After you set a condition, breakpoint +@var{bnum} stops your program only if the value of @var{expression} is +true (nonzero, in C). When you use @code{condition}, @value{GDBN} +checks @var{expression} immediately for syntactic correctness, and to +determine whether symbols in it have referents in the context of your +breakpoint. @c FIXME so what does GDB do if there is no referent? Moreover, what @c about watchpoints? @value{GDBN} does @@ -2392,15 +2601,15 @@ is an integer. Most of the time, the ignore count is zero, and therefore has no effect. But if your program reaches a breakpoint whose ignore count is positive, then instead of stopping, it just decrements the ignore count by one and continues. As a result, if the ignore count -value is @var{n}, the breakpoint will not stop the next @var{n} times it -is reached. +value is @var{n}, the breakpoint does not stop the next @var{n} times +your program reaches it. @table @code @item ignore @var{bnum} @var{count} @kindex ignore Set the ignore count of breakpoint number @var{bnum} to @var{count}. The next @var{count} times the breakpoint is reached, your program's -execution will not stop; other than to decrement the ignore count, @value{GDBN} +execution does not stop; other than to decrement the ignore count, @value{GDBN} takes no action. To make the breakpoint stop the next time it is reached, specify @@ -2411,9 +2620,9 @@ breakpoint, you can specify an ignore count directly as an argument to @code{continue}, rather than using @code{ignore}. @xref{Continuing and Stepping,,Continuing and stepping}. -If a breakpoint has a positive ignore count and a condition, the condition -is not checked. Once the ignore count reaches zero, the condition will -be checked. +If a breakpoint has a positive ignore count and a condition, the +condition is not checked. Once the ignore count reaches zero, +@value{GDBN} resumes checking the condition. You could achieve the effect of the ignore count with a condition such as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that @@ -2466,7 +2675,7 @@ If the first command you specify in a command list is @code{silent}, the usual message about stopping at a breakpoint is not printed. This may be desirable for breakpoints that are to print a specific message and then continue. If none of the remaining commands print anything, you -will see no sign that the breakpoint was reached. @code{silent} is +see no sign that the breakpoint was reached. @code{silent} is meaningful only at the beginning of a breakpoint command list. The commands @code{echo}, @code{output}, and @code{printf} allow you to @@ -2512,7 +2721,7 @@ Some programming languages (notably C++) permit a single function name to be defined several times, for application in different contexts. This is called @dfn{overloading}. When a function name is overloaded, @samp{break @var{function}} is not enough to tell @value{GDBN} where you want -a breakpoint. If you realize this will be a problem, you can use +a breakpoint. If you realize this is a problem, you can use something like @samp{break @var{function}(@var{types})} to specify which particular version of the function you want. Otherwise, @value{GDBN} offers you a menu of numbered choices for different possible breakpoints, and @@ -2652,10 +2861,17 @@ line, then stop it and return control to @value{GDBN}. This command is abbreviated @code{s}. @quotation +@c "without debugging information" is imprecise; actually "without line +@c numbers in the debugging information". (gcc -g1 has debugging info but +@c not line numbers). But it seems complex to try to make that +@c distinction here. @emph{Warning:} If you use the @code{step} command while control is within a function that was compiled without debugging information, execution proceeds until control reaches a function that does have -debugging information. +debugging information. Likewise, it will not step into a function which +is compiled without debugging information. To step through functions +without debugging information, use the @code{stepi} command, described +below. @end quotation @item step @var{count} @@ -2702,10 +2918,10 @@ automatically continues execution until the program counter is greater than the address of the jump. This means that when you reach the end of a loop after single stepping -though it, @code{until} will cause your program to continue execution -until the loop is exited. In contrast, a @code{next} command at the end -of a loop will simply step back to the beginning of the loop, which -would force you to step through the next iteration. +though it, @code{until} makes your program continue execution until it +exits the loop. In contrast, a @code{next} command at the end of a loop +simply steps back to the beginning of the loop, which forces you to step +through the next iteration. @code{until} always stops your program if it attempts to exit the current stack frame. @@ -2751,9 +2967,9 @@ and hence is quicker than @code{until} without an argument. Execute one machine instruction, then stop and return to the debugger. It is often useful to do @samp{display/i $pc} when stepping by machine -instructions. This will cause the next instruction to be executed to -be displayed automatically at each stop. @xref{Auto Display, -,Automatic display}. +instructions. This makes @value{GDBN} automatically display the next +instruction to be executed, each time your program stops. @xref{Auto +Display,, Automatic display}. An argument is a repeat count, as in @code{step}. @@ -2835,8 +3051,8 @@ the @code{print} keyword as well. implies the @code{nostop} keyword as well. @item pass -@value{GDBN} should allow your program to see this signal; your program will be -able to handle the signal, or may be terminated if the signal is fatal +@value{GDBN} should allow your program to see this signal; your program +can handle the signal, or else it may terminate if the signal is fatal and not handled. @item nopass @@ -2845,11 +3061,11 @@ and not handled. @c @end group When a signal stops your program, the signal is not visible until you -continue. Your program will see the signal then, if @code{pass} is in +continue. Your program sees the signal then, if @code{pass} is in effect for the signal in question @emph{at that time}. In other words, after @value{GDBN} reports a signal, you can use the @code{handle} -command with @code{pass} or @code{nopass} to control whether that -signal will be seen by your program when you later continue it. +command with @code{pass} or @code{nopass} to control whether your +program sees that signal when you continue. You can also use the @code{signal} command to prevent your program from seeing a signal, or cause it to see a signal it normally would not see, @@ -2862,6 +3078,67 @@ you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your program a signal}. @end ifset +@ifclear BARETARGET +@node Thread Stops +@section Stopping and starting multi-thread programs + +When your program has multiple threads (@pxref{Threads,, Debugging +programs with multiple threads}), you can choose whether to set +breakpoints on all threads, or on a particular thread. + +@table @code +@cindex breakpoints and threads +@cindex thread breakpoints +@kindex break @dots{} thread @var{threadno} +@item break @var{linespec} thread @var{threadno} +@itemx break @var{linespec} thread @var{threadno} if @dots{} +Use the qualifier @samp{thread @var{threadno}} with a breakpoint command +to specify that you only want @value{GDBN} to stop the program when a +particular thread reaches this breakpoint. @var{threadno} is one of the +numeric thread identifiers assigned by @value{GDBN}, shown in the first +column of the @samp{info threads} display. + +If you do not specify @samp{thread @var{threadno}} when you set a +breakpoint, the breakpoint applies to @emph{all} threads of your +program. + +You can use the @code{thread} qualifier on conditional breakpoints as +well; in this case, place @samp{thread @var{threadno}} before the +breakpoint condition, like this: + +@smallexample +(gdb) break frik.c:13 thread 28 if bartab > lim +@end smallexample +@end table + +@cindex stopped threads +@cindex threads, stopped +Whenever your program stops under @value{GDBN} for any reason, +@emph{all} threads of execution stop, not just the current thread. This +allows you to examine the overall state of the program, including +switching between threads, without worrying that things may change +underfoot. + +@cindex continuing threads +@cindex threads, continuing +Conversely, whenever you restart the program, @emph{all} threads start +executing. @emph{This is true even when single-stepping} with commands +like @code{step} or @code{next}. + +In particular, @value{GDBN} cannot single-step all threads in lockstep. +Since thread scheduling is up to your debugging target's operating +system (not controlled by @value{GDBN}), other threads may +execute more than one statement while the current thread completes a +single step. Moreover, in general other threads stop in the middle of a +statement, rather than at a clean statement boundary, when the program +stops. + +You might even find your program stopped in another thread after +continuing or even single-stepping. This happens whenever some other +thread runs into a breakpoint, a signal, or an exception before the +first thread completes whatever you requested. +@end ifclear + @node Stack @chapter Examining the Stack @@ -2943,11 +3220,11 @@ frames in @value{GDBN} commands. @cindex frameless execution Some compilers provide a way to compile functions so that they operate without stack frames. (For example, the @code{@value{GCC}} option -@samp{-fomit-frame-pointer} will generate functions without a frame.) +@samp{-fomit-frame-pointer} generates functions without a frame.) This is occasionally done with heavily used library functions to save the frame setup time. @value{GDBN} has limited facilities for dealing with these function invocations. If the innermost function invocation -has no stack frame, @value{GDBN} will nevertheless regard it as though +has no stack frame, @value{GDBN} nevertheless regards it as though it had a separate frame, which is numbered zero as usual, allowing correct tracing of the function call chain. However, @value{GDBN} has no provision for frameless functions elsewhere in the stack. @@ -3038,14 +3315,19 @@ impossible for @value{GDBN} to assign numbers properly to all frames. In addition, this can be useful when your program has multiple stacks and switches between them. -@ifset SPARC +@ifclear H8EXCLUSIVE On the SPARC architecture, @code{frame} needs two addresses to select an arbitrary frame: a frame pointer and a stack pointer. + +On the MIPS and Alpha architecture, it needs two addresses: a stack +pointer and a program counter. + +On the 29k architecture, it needs three addresses: a register stack +pointer, a program counter, and a memory stack pointer. @c note to future updaters: this is conditioned on a flag -@c FRAME_SPECIFICATION_DYADIC in the tm-*.h files, currently only used -@c by SPARC, hence the specific attribution. Generalize or list all -@c possibilities if more supported machines start doing this. -@end ifset +@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date +@c as of 27 Jan 1994. +@end ifclear @item up @var{n} @kindex up @@ -3067,7 +3349,9 @@ frame. The first line shows the frame number, the function name, the arguments, and the source file and line number of execution in that frame. The second line shows the text of that source line. +@need 1000 For example: + @smallexample @group (@value{GDBP}) up @@ -3077,8 +3361,8 @@ For example: @end group @end smallexample -After such a printout, the @code{list} command with no arguments will -print ten lines centered on the point of execution in the frame. +After such a printout, the @code{list} command with no arguments +prints ten lines centered on the point of execution in the frame. @xref{List, ,Printing source lines}. @table @code @@ -3124,9 +3408,11 @@ the usual conventions. @item info frame @var{addr} @itemx info f @var{addr} -Print a verbose description of the frame at address @var{addr}, -without selecting that frame. The selected frame remains unchanged by -this command. +Print a verbose description of the frame at address @var{addr}, without +selecting that frame. The selected frame remains unchanged by this +command. This requires the same kind of address (more than one for some +architectures) that you specify in the @code{frame} command. +@xref{Selection, ,Selecting a frame}. @item info args @kindex info args @@ -3172,7 +3458,7 @@ commands: @cindex @code{heuristic-fence-post} (MIPS) @table @code @item set heuristic-fence-post @var{limit} -Restrict @var{GDBN} to examining at most @var{limit} bytes in its search +Restrict @value{GDBN} to examining at most @var{limit} bytes in its search for the beginning of a function. A value of @code{0} (the default) means there is no limit. @@ -3254,8 +3540,7 @@ the @code{list} argument explicitly specifies some other number). @item show listsize @kindex show listsize -Display the number of lines that @code{list} will currently display by -default. +Display the number of lines that @code{list} prints. @end table Repeating a @code{list} command with @key{RET} discards the argument, @@ -3375,15 +3660,15 @@ 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} will, as a last resort, look in the current -directory. +If @value{GDBN} cannot find a source file in the source path, and the +object program records a directory, @value{GDBN} tries that directory +too. If the source path is empty, and there is no record of the +compilation directory, @value{GDBN} looks in the current directory as a +last resort. -Whenever you reset or rearrange the source path, @value{GDBN} will clear out -any information it has cached about where source files are found, where -each line is in the file, etc. +Whenever you reset or rearrange the source path, @value{GDBN} clears out +any information it has cached about where source files are found and where +each line is in the file. @kindex directory When you start @value{GDBN}, its source path is empty. @@ -3394,7 +3679,7 @@ To add other directories, use the @code{directory} command. Add directory @var{dirname} to the front of the source path. Several directory names may be given to this command, separated by @samp{:} or whitespace. You may specify a directory that is already in the source -path; this moves it forward, so it will be searched sooner. +path; this moves it forward, so @value{GDBN} searches it sooner. @kindex cdir @kindex cwd @@ -3488,9 +3773,9 @@ variables}). This specialized command dumps a range of memory as machine instructions. The default memory range is the function surrounding the program counter of the selected frame. A single argument to this -command is a program counter value; the function surrounding this value -will be dumped. Two arguments specify a range of addresses (first -inclusive, second exclusive) to dump. +command is a program counter value; @value{GDBN} dumps the function +surrounding this value. Two arguments specify a range of addresses +(first inclusive, second exclusive) to dump. @end table @ifclear H8EXCLUSIVE @@ -3824,9 +4109,10 @@ used with the @code{x} command, where @samp{b} stands for ``byte''; @pxref{Memory,,Examining memory}.} @item a -Print as an address, both absolute in hex and as an offset from the -nearest preceding symbol. This format can be used to discover where (in -what function) an unknown address is located: +@cindex unknown address, locating +Print as an address, both absolute in hexadecimal and as an offset from +the nearest preceding symbol. You can use this format used to discover +where (in what function) an unknown address is located: @example (@value{GDBP}) p/a 0x54320 @@ -3927,9 +4213,9 @@ words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; Since the letters indicating unit sizes are all distinct from the letters specifying output formats, you do not have to remember whether -unit size or format comes first; either order will work. The output +unit size or format comes first; either order works. The output specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. -(However, the count @var{n} must come first; @samp{wx4} will not work.) +(However, the count @var{n} must come first; @samp{wx4} does not work.) Even though the unit size @var{u} is ignored for the formats @samp{s} and @samp{i}, you might still want to use a count @var{n}; for example, @@ -3967,7 +4253,7 @@ address printed if several units were printed on the last line of output. If you find that you want to print the value of an expression frequently (to see how it changes), you might want to add it to the @dfn{automatic -display list} so that @value{GDBN} will print its value each time your program stops. +display list} so that @value{GDBN} prints its value each time your program stops. Each expression added to the list is given a number to identify it; to remove an expression from the list, you specify that number. The automatic display looks like this: @@ -3992,7 +4278,7 @@ supported by @code{x}; otherwise it uses @code{print}. Add the expression @var{exp} to the list of expressions to display each time your program stops. @xref{Expressions, ,Expressions}. -@code{display} will not repeat if you press @key{RET} again after using it. +@code{display} does not repeat if you press @key{RET} again after using it. @item display/@var{fmt} @var{exp} For @var{fmt} specifying only a display format and not a size or @@ -4018,7 +4304,7 @@ is a common name for the program counter; @pxref{Registers}). @kindex undisplay Remove item numbers @var{dnums} from the list of expressions to display. -@code{undisplay} will not repeat if you press @key{RET} after using it. +@code{undisplay} does not repeat if you press @key{RET} after using it. (Otherwise you would just get the error @samp{No display number @dots{}}.) @item disable display @var{dnums}@dots{} @@ -4050,11 +4336,11 @@ sense outside the lexical context for which it was set up. Such an expression is disabled when execution enters a context where one of its variables is not defined. For example, if you give the command @code{display last_char} while inside a function with an argument -@code{last_char}, then this argument will be displayed while your program +@code{last_char}, @value{GDBN} displays this argument while your program continues to stop inside that function. When it stops elsewhere---where -there is no variable @code{last_char}---display is disabled. The next time -your program stops where @code{last_char} is meaningful, you can enable the -display expression once again. +there is no variable @code{last_char}---the display is disabled +automatically. The next time your program stops where @code{last_char} +is meaningful, you can enable the display expression once again. @node Print Settings @section Print settings @@ -4071,10 +4357,10 @@ These settings are useful for debugging programs in any language: @item set print address @itemx set print address on @kindex set print address -@value{GDBN} will print memory addresses showing the location of stack +@value{GDBN} prints memory addresses showing the location of stack traces, structure values, pointer values, breakpoints, and so forth, even when it also displays the contents of those addresses. The default -is on. For example, this is what a stack frame display looks like, with +is @code{on}. For example, this is what a stack frame display looks like, with @code{set print address on}: @smallexample @@ -4113,7 +4399,7 @@ When @value{GDBN} prints a symbolic address, it normally prints the closest earlier symbol plus an offset. If that symbol does not uniquely identify the address (for example, it is a name whose scope is a single source file), you may need to disambiguate. One way to do this is with -@code{info line}, for example @code{info line *0x4537}. Alternately, +@code{info line}, for example @samp{info line *0x4537}. Alternately, you can set @value{GDBN} to print the source file and line number when it prints a symbolic address: @@ -4133,6 +4419,10 @@ Show whether or not @value{GDBN} will print the source file name and line number of a symbol in the symbolic form of an address. @end table +Another situation where it is helpful to show symbol filenames and line +numbers is when disassembling code; @value{GDBN} shows you the line +number and source file that corresponds to each instruction. + Also, you may wish to see the symbolic form only if the address being printed is reasonably close to the closest earlier symbol: @@ -4146,15 +4436,38 @@ symbolic form of an address, if any symbol precedes it. @item show print max-symbolic-offset @kindex show print max-symbolic-offset -Ask how large the maximum offset is that @value{GDBN} will print in a +Ask how large the maximum offset is that @value{GDBN} prints in a symbolic address. @end table +@cindex wild pointer, interpreting +@cindex pointer, finding referent +If you have a pointer and you are not sure where it points, try +@samp{set print symbol-filename on}. Then you can determine the name +and source file location of the variable where it points, using +@samp{p/a @var{pointer}}. This interprets the address in symbolic form. +For example, here @value{GDBN} shows that a variable @code{ptt} points +at another variable @code{t}, defined in @file{hi2.c}: + +@example +(@value{GDBP}) set print symbol-filename on +(@value{GDBP}) p/a ptt +$4 = 0xe008 +@end example + +@quotation +@emph{Warning:} For pointers that point to a local variable, @samp{p/a} +does not show the symbol name and filename of the referent, even with +the appropriate @code{set print} options turned on. +@end quotation + +Other settings control how different kinds of objects are printed: + @table @code @item set print array @itemx set print array on @kindex set print array -@value{GDBN} will pretty-print arrays. This format is more convenient to read, +Pretty-print arrays. This format is more convenient to read, but uses more space. The default is off. @item set print array off @@ -4167,14 +4480,14 @@ arrays. @item set print elements @var{number-of-elements} @kindex set print elements -If @value{GDBN} is printing a large array, it will stop printing after it has +If @value{GDBN} is printing a large array, it stops printing after it has printed the number of elements set by the @code{set print elements} command. This limit also applies to the display of strings. Setting the number of elements to zero means that the printing is unlimited. @item show print elements @kindex show print elements -Display the number of elements of a large array that @value{GDBN} will print +Display the number of elements of a large array that @value{GDBN} prints before losing patience. @item set print pretty on @@ -4210,22 +4523,23 @@ This is the default format. @item show print pretty @kindex show print pretty -Show which format @value{GDBN} will use to print structures. +Show which format @value{GDBN} is using to print structures. @item set print sevenbit-strings on @kindex set print sevenbit-strings Print using only seven-bit characters; if this option is set, -@value{GDBN} will display any eight-bit characters (in strings or character -values) using the notation @code{\}@var{nnn}. For example, @kbd{M-a} is -displayed as @code{\341}. +@value{GDBN} displays any eight-bit characters (in strings or +character values) using the notation @code{\}@var{nnn}. This setting is +best if you are working in English (@sc{ascii}) and you use the +high-order bit of characters as a marker or ``meta'' bit. @item set print sevenbit-strings off -Print using either seven-bit or eight-bit characters, as required. This -is the default. +Print full eight-bit characters. This allows the use of more +international character sets, and is the default. @item show print sevenbit-strings @kindex show print sevenbit-strings -Show whether or not @value{GDBN} will print only seven-bit characters. +Show whether or not @value{GDBN} is printing only seven-bit characters. @item set print union on @kindex set print union @@ -4289,7 +4603,7 @@ linkage. The default is @samp{on}. @item show print demangle @kindex show print demangle -Show whether C++ names will be printed in mangled or demangled form. +Show whether C++ names are printed in mangled or demangled form. @item set print asm-demangle @itemx set print asm-demangle on @@ -4300,7 +4614,7 @@ The default is off. @item show print asm-demangle @kindex show print asm-demangle -Show whether C++ names in assembly listings will be printed in mangled +Show whether C++ names in assembly listings are printed in mangled or demangled form. @item set demangle-style @var{style} @@ -4344,7 +4658,7 @@ virtual function table. This is the default setting. @item show print object @kindex show print object -Show whether actual, or declared, object types will be displayed. +Show whether actual, or declared, object types are displayed. @item set print vtbl @itemx set print vtbl on @@ -4606,7 +4920,7 @@ frame (with @samp{frame 0}). However, @value{GDBN} must deduce where registers are saved, from the machine code generated by your compiler. If some registers are not saved, or if @value{GDBN} is unable to locate the saved registers, the selected stack -frame will make no difference. +frame makes no difference. @ifset AMD29K @table @code @@ -4621,7 +4935,7 @@ enough''. This may result in @value{GDBN} referencing memory locations that do not exist. If necessary, you can get around this problem by specifying the ending address of the register stack with the @code{set rstack_high_address} command. The argument should be an address, which -you will probably want to precede with @samp{0x} to specify in +you probably want to precede with @samp{0x} to specify in hexadecimal. @item show rstack_high_address @@ -4779,7 +5093,7 @@ case frees you from having to set the working language manually. @node Show @section Displaying the language -The following commands will help you find out which language is the +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 @@ -4793,9 +5107,9 @@ build and compute expressions that may involve variables in your program. @item info frame Among the other information listed here (@pxref{Frame Info, ,Information -about a frame}) is the source language for this frame. This is the -language that will become the working language if you ever use an -identifier that is in this frame. +about a frame}) is the source language for this frame. This +language becomes the working language if you use an +identifier from this frame. @item info source Among the other information listed here (@pxref{Symbols, ,Examining the @@ -4822,7 +5136,7 @@ by eliminating type mismatches, and providing active checks for range errors when your program is running. @value{GDBN} can check for conditions like the above if you wish. -Although @value{GDBN} will not check the statements in your program, it +Although @value{GDBN} does not check the statements in your program, it can check expressions entered directly into @value{GDBN} for evaluation via the @code{print} command, for example. As with the working language, @value{GDBN} can also decide whether or not to check automatically based on @@ -4984,7 +5298,7 @@ language. The following sections detail to what degree each source language is supported by @value{GDBN}. These sections are not meant to be language tutorials or references, but serve only as a reference guide to what the -@value{GDBN} expression parser will accept, and what input and output +@value{GDBN} expression parser accepts, and what input and output formats should look like for different languages. There are many good books written on each of these languages; please look to these for a language reference or tutorial. @@ -5013,9 +5327,15 @@ together. @kindex g++ @cindex GNU C++ The C++ debugging facilities are jointly implemented by the GNU C++ -compiler and @value{GDBN}. Therefore, to debug your C++ code effectively, -you must compile your C++ programs with the GNU C++ compiler, -@code{g++}. +compiler and @value{GDBN}. Therefore, to debug your C++ code +effectively, you must compile your C++ programs with the GNU C++ +compiler, @code{g++}. + +For best results when debugging C++ programs, use the stabs debugging +format. You can select that format explicitly with the @code{g++} +command-line options @samp{-gstabs} or @samp{-gstabs+}. See +@ref{Debugging Options,,Options for Debugging Your Program or GNU CC, +gcc.info, Using GNU CC}, for more information. @end ifclear @ifset CONLY @node C @@ -5291,18 +5611,20 @@ interpret a significant subset of C++ expressions. @cindex @sc{xcoff} and C++ @cindex @sc{elf}/stabs and C++ @cindex @sc{elf}/@sc{dwarf} and C++ +@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check +@c periodically whether this has happened... @quotation -@emph{Warning:} Most of these extensions depend on the use of additional -debugging information in the symbol table, and thus require a rich, -extendable object code format. In particular, if your system uses -a.out, MIPS @sc{ecoff}, RS/6000 @sc{xcoff}, or Sun @sc{elf} with stabs -extensions to the symbol table, these facilities are all available. -Where the object code format is standard @sc{coff}, on the other hand, -most of the C++ support in @value{GDBN} will @emph{not} work, nor can it. -For the standard SVr4 debugging format, @sc{dwarf} in @sc{elf}, the -standard is still evolving, so the C++ support in @value{GDBN} is still -fragile; when this debugging format stabilizes, however, C++ support -will also be available on systems that use it. +@emph{Warning:} @value{GDBN} can only debug C++ code if you compile with +the GNU C++ compiler. Moreover, C++ debugging depends on the use of +additional debugging information in the symbol table, and thus requires +special support. @value{GDBN} has this support @emph{only} with the +stabs debug format. In particular, if your compiler generates a.out, +MIPS @sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions +to the symbol table, these facilities are all available. (With GNU CC, +you can use the @samp{-gstabs} option to request stabs debugging +extensions explicitly.) Where the object code format is standard +@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C++ +support in @value{GDBN} does @emph{not} work. @end quotation @enumerate @@ -5326,10 +5648,10 @@ pointer @code{this} following the same rules as C++. @cindex call overloaded functions @cindex type conversions in C++ @item -You can call overloaded functions; @value{GDBN} will resolve the function +You can call overloaded functions; @value{GDBN} resolves the function call to the right definition, with one restriction---you must use arguments of the type required by the function that you want to call. -@value{GDBN} will not perform conversions requiring constructors or +@value{GDBN} does not perform conversions requiring constructors or user-defined type operators. @cindex reference declarations @@ -5378,8 +5700,8 @@ further details. @cindex C and C++ checks By default, when @value{GDBN} parses C or C++ expressions, type checking -is not used. However, if you turn type checking on, @value{GDBN} will -consider two variables type equivalent if: +is not used. However, if you turn type checking on, @value{GDBN} +considers two variables type equivalent if: @itemize @bullet @item @@ -5421,8 +5743,8 @@ inside a @code{struct} @ifclear CONLY or @code{class} @end ifclear -will also be printed. -Otherwise, it will appear as @samp{@{...@}}. +is also printed. +Otherwise, it appears as @samp{@{...@}}. The @code{@@} operator aids in the debugging of dynamic arrays, formed with pointers and a memory allocation function. @xref{Expressions, @@ -5502,8 +5824,8 @@ available choices, or to finish the type list for you. The extensions made to @value{GDBN} to support Modula-2 only support output from the GNU Modula-2 compiler (which is currently being developed). Other Modula-2 compilers are not currently supported, and -attempting to debug executables produced by them will most likely -result in an error as @value{GDBN} reads in the executable's symbol +attempting to debug executables produced by them is most likely +to give an error as @value{GDBN} reads in the executable's symbol table. @cindex expressions in Modula-2 @@ -5636,7 +5958,7 @@ as @code{^}. @quotation @emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN} -will treat the use of the operator @code{IN}, or the use of operators +treats the use of the operator @code{IN}, or the use of operators @code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, @code{<=}, and @code{>=} on sets as an error. @end quotation @@ -5749,7 +6071,7 @@ Returns the member of the type @var{t} whose ordinal value is @var{i}. @quotation @emph{Warning:} Sets and their operations are not yet supported, so -@value{GDBN} will treat the use of procedures @code{INCL} and @code{EXCL} as +@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as an error. @end quotation @@ -5813,7 +6135,7 @@ Modula-2. This happens regardless of whether you, or @value{GDBN}, selected the working language. If you allow @value{GDBN} to set the language automatically, then entering -code compiled from a file whose name ends with @file{.mod} will set the +code compiled from a file whose name ends with @file{.mod} sets the working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set the language automatically}, for further details. @@ -5835,7 +6157,7 @@ returned a pointer.) @item C escape sequences can be used in strings and characters to represent -non-printable characters. @value{GDBN} will print out strings with these +non-printable characters. @value{GDBN} prints out strings with these escape sequences embedded. Single non-printable characters are printed using the @samp{CHR(@var{nnn})} format. @@ -5905,7 +6227,7 @@ identifier within your program, except another module. Using the @code{::} operator makes @value{GDBN} search the scope specified by @var{scope} for the identifier @var{id}. If it is not -found in the specified scope, then @value{GDBN} will search all scopes +found in the specified scope, then @value{GDBN} searches all scopes enclosing the one specified by @var{scope}. Using the @code{.} operator makes @value{GDBN} search the current scope for @@ -6233,7 +6555,7 @@ an address of your own choosing, with the following commands: @table @code @item jump @var{linespec} @kindex jump -Resume execution at line @var{linespec}. Execution will stop +Resume execution at line @var{linespec}. Execution stops again immediately if there is a breakpoint there. @xref{List, ,Printing source lines}, for a description of the different forms of @var{linespec}. @@ -6255,14 +6577,14 @@ Resume execution at the instruction at address @var{address}. You can get much the same effect as the @code{jump} command by storing a new value into the register @code{$pc}. The difference is that this does not start your program running; it only changes the address where it -@emph{will} run when it is continued. For example, +@emph{will} run when you continue. For example, @example set $pc = 0x485 @end example @noindent -causes the next @code{continue} command or stepping command to execute at +makes the next @code{continue} command or stepping command execute at address @code{0x485}, rather than at the address where your program stopped. @xref{Continuing and Stepping, ,Continuing and stepping}. @@ -6375,12 +6697,12 @@ repairs. @item set write on @itemx set write off @kindex set write -If you specify @samp{set write on}, @value{GDBN} will open executable +If you specify @samp{set write on}, @value{GDBN} opens executable @ifclear BARETARGET and core @end ifclear files for both reading and writing; if you specify @samp{set write -off} (the default), @value{GDBN} will open them read-only. +off} (the default), @value{GDBN} opens them read-only. If you have already loaded a file, you must load it again (using the @code{exec-file} @@ -6396,7 +6718,7 @@ Display whether executable files @ifclear BARETARGET and core files @end ifclear -will be opened for writing as well as reading. +are opened for writing as well as reading. @end table @node GDB Files @@ -6448,13 +6770,13 @@ search, just as the shell does when looking for a program to run. You can change the value of this variable, for both @value{GDBN} and your program, using the @code{path} command. -On systems with memory-mapped files, an auxiliary symbol table file -@file{@var{filename}.syms} may be available for @var{filename}. If it -is, @value{GDBN} will map in the symbol table from +On systems with memory-mapped files, an auxiliary file +@file{@var{filename}.syms} may hold symbol table information for +@var{filename}. If so, @value{GDBN} maps in the symbol table from @file{@var{filename}.syms}, starting up more quickly. See the -descriptions of the options @samp{-mapped} and @samp{-readnow} (available -on the command line, and with the commands @code{file}, @code{symbol-file}, -or @code{add-symbol-file}), for more information. +descriptions of the options @samp{-mapped} and @samp{-readnow} +(available on the command line, and with the commands @code{file}, +@code{symbol-file}, or @code{add-symbol-file}), for more information. @item file @code{file} with no argument makes @value{GDBN} discard any information it @@ -6463,7 +6785,7 @@ has on both executable file and the symbol table. @item exec-file @r{[} @var{filename} @r{]} @kindex exec-file Specify that the program to be run (but not the symbol table) is found -in @var{filename}. @value{GDBN} will search the environment variable @code{PATH} +in @var{filename}. @value{GDBN} searches the environment variable @code{PATH} if necessary to locate your program. Omitting @var{filename} means to discard information on the executable file. @@ -6482,11 +6804,11 @@ auto-display expressions. This is because they may contain pointers to the internal data recording symbols and data types, which are part of the old symbol table data being discarded inside @value{GDBN}. -@code{symbol-file} will not repeat if you press @key{RET} again after +@code{symbol-file} does not repeat if you press @key{RET} again after executing it once. -When @value{GDBN} is configured for a particular environment, it will -understand debugging information in whatever format is the standard +When @value{GDBN} is configured for a particular environment, it +understands debugging information in whatever format is the standard generated for that environment; you may use either a GNU compiler, or other compilers that adhere to the local conventions. Best results are usually obtained from GNU compilers; for example, using @code{@value{GCC}} @@ -6526,7 +6848,7 @@ entire symbol table available. If memory-mapped files are available on your system through the @code{mmap} system call, you can use another option, @samp{-mapped}, to cause @value{GDBN} to write the symbols for your program into a reusable -file. Future @value{GDBN} debugging sessions will map in symbol information +file. Future @value{GDBN} debugging sessions map in symbol information from this auxiliary symbol file (if the program has not changed), rather than spending time reading the symbol table from the executable program. Using the @samp{-mapped} option has the same effect as @@ -6537,7 +6859,7 @@ file has all the symbol information for your program. The auxiliary symbol file for a program called @var{myprog} is called @samp{@var{myprog}.syms}. Once this file exists (so long as it is newer -than the corresponding executable), @value{GDBN} will always attempt to use +than the corresponding executable), @value{GDBN} always attempts to use it when you debug @var{myprog}; no special options or commands are needed. @@ -6587,19 +6909,20 @@ target is @dots{}}'' @end ifset The file is loaded at whatever address is specified in the executable. -For some object file formats, like a.out, the object file format fixes -the address and so it won't necessarily match the address you gave to -the linker. +For some object file formats, you can specify the load address when you +link the program; for other formats, like a.out, the object file format +specifies a fixed address. +@c FIXME! This would be a good place for an xref to the GNU linker doc. @ifset VXWORKS -On VxWorks, @code{load} will dynamically link @var{filename} on the +On VxWorks, @code{load} links @var{filename} dynamically on the current target system as well as adding its symbols in @value{GDBN}. @end ifset @ifset I960 @cindex download to Nindy-960 -With the Nindy interface to an Intel 960 board, @code{load} will -download @var{filename} to the 960 as well as adding its symbols in +With the Nindy interface to an Intel 960 board, @code{load} +downloads @var{filename} to the 960 as well as adding its symbols in @value{GDBN}. @end ifset @@ -6615,7 +6938,7 @@ opens it as the current executable target for @value{GDBN} on your host (like the @code{file} command). @end ifset -@code{load} will not repeat if you press @key{RET} again after using it. +@code{load} does not repeat if you press @key{RET} again after using it. @ifclear BARETARGET @item add-symbol-file @var{filename} @var{address} @@ -6635,7 +6958,7 @@ originally read with the @code{symbol-file} command. You can use the read keeps adding to the old. To discard all old symbol data instead, use the @code{symbol-file} command. -@code{add-symbol-file} will not repeat if you press @key{RET} after using it. +@code{add-symbol-file} does not repeat if you press @key{RET} after using it. You can use the @samp{-mapped} and @samp{-readnow} options just as with the @code{symbol-file} command, to change how @value{GDBN} manages the symbol @@ -6656,24 +6979,25 @@ names of the executable and core dump files name of the executable file @end ifset currently in use by @value{GDBN}, and the files from which symbols were -loaded. The command @code{help targets} lists all possible targets +loaded. The command @code{help target} lists all possible targets rather than current ones. @end table All file-specifying commands allow both absolute and relative file names -as arguments. @value{GDBN} always converts the file name to an absolute path +as arguments. @value{GDBN} always converts the file name to an absolute file name and remembers it that way. @ifclear BARETARGET @cindex shared libraries -@value{GDBN} supports SunOS, SVR4, and IBM RS/6000 shared libraries. +@value{GDBN} supports SunOS, SVr4, Irix 5, and IBM RS/6000 shared libraries. @value{GDBN} automatically loads symbol definitions from shared libraries when you use the @code{run} command, or when you examine a core file. -(Before you issue the @code{run} command, @value{GDBN} will not understand +(Before you issue the @code{run} command, @value{GDBN} does not understand references to a function in a shared library, however---unless you are debugging a core file). -@c FIXME: next @value{GDBN} release should permit some refs to undef -@c FIXME...symbols---eg in a break cmd---assuming they are from a shared lib +@c FIXME: some @value{GDBN} release may permit some refs to undef +@c FIXME...symbols---eg in a break cmd---assuming they are from a shared +@c FIXME...lib; check this from time to time when updating manual @table @code @item info share @@ -6688,7 +7012,7 @@ Print the names of the shared libraries which are currently loaded. @kindex share This is an obsolescent command; you can use it to explicitly load shared object library symbols for files matching a Unix regular expression, but -as with files loaded automatically, it will only load shared libraries +as with files loaded automatically, it only loads shared libraries required by your program for a core file or after typing @code{run}. If @var{regex} is omitted all shared libraries required by your program are loaded. @@ -6698,7 +7022,7 @@ loaded. @node Symbol Errors @section Errors reading symbol files -While reading a symbol file, @value{GDBN} will occasionally encounter problems, +While reading a symbol file, @value{GDBN} occasionally encounters problems, such as symbol types it does not recognize, or known bugs in compiler output. By default, @value{GDBN} does not notify you of such problems, since they are relatively common and primarily of interest to people @@ -6731,7 +7055,7 @@ The symbol information for symbol scope blocks should occur in order of increasing addresses. This error indicates that it does not do so. -@value{GDBN} does not circumvent this problem, and will have trouble +@value{GDBN} does not circumvent this problem, and has trouble locating symbols in the source file whose symbols it is reading. (You can often determine what source file is affected by specifying @code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and @@ -6763,8 +7087,8 @@ know how to read. @code{0x@var{nn}} is the symbol type of the misunderstood information, in hexadecimal. @value{GDBN} circumvents the error by ignoring this symbol information. This -will usually allow your program to be debugged, though certain symbols -will not be accessible. If you encounter such a problem and feel like +usually allows you to debug your program, though certain symbols +are not accessible. If you encounter such a problem and feel like debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint on @code{complain}, then go up to the function @code{read_dbx_symtab} and examine @code{*bufp} to see the symbol. @@ -6834,7 +7158,7 @@ file. For example, if you execute @samp{gdb a.out}, then the executable file @code{a.out} is the only active target. If you designate a core file as well---presumably from a prior run that crashed and coredumped---then -@value{GDBN} has two active targets and will use them in tandem, looking +@value{GDBN} has two active targets and uses them in tandem, looking first in the corefile target, then in the executable file, to satisfy requests for memory addresses. (Typically, these two classes of target are complementary, since core files contain only a program's @@ -6883,7 +7207,7 @@ typically include things like device names or host names to connect with, process numbers, and baud rates. @end ifclear -The @code{target} command will not repeat if you press @key{RET} again +The @code{target} command does not repeat if you press @key{RET} again after executing the command. @item help target @@ -6932,7 +7256,7 @@ CPU simulator. @xref{Simulator,,Simulated CPU Target}. @kindex target udi Remote AMD29K target, using the AMD UDI protocol. The @var{keyword} argument specifies which 29K board or simulator to use. @xref{UDI29K -Remote,,@value{GDBN} and the UDI protocol for AMD29K}. +Remote,,The UDI protocol for AMD29K}. @item target amd-eb @var{dev} @var{speed} @var{PROG} @kindex target amd-eb @@ -6941,7 +7265,7 @@ Remote PC-resident AMD EB29K board, attached over serial lines. @var{dev} is the serial device, as for @code{target remote}; @var{speed} allows you to specify the linespeed; and @var{PROG} is the name of the program to be debugged, as it appears to DOS on the PC. -@xref{EB29K Remote, ,@value{GDBN} with a remote EB29K}. +@xref{EB29K Remote, ,The EBMON protocol for AMD29K}. @end ifset @ifset H8 @@ -7002,11 +7326,11 @@ Some configurations of GDB have special serial or TCP/IP interfaces to make this work with particular debugging targets. In addition, GDB comes with a generic serial protocol (specific to GDB, but not specific to any particular target system) which you can use if you -write the remote stubs---the code that will run on the remote system to +write the remote stubs---the code that runs on the remote system to communicate with GDB. Other remote targets may be available in your -configuration of GDB; use @code{help targets} to list them. +configuration of GDB; use @code{help target} to list them. @ifset GENERIC @c Text on starting up GDB in various specific cases; it goes up front @@ -7020,8 +7344,8 @@ configuration of GDB; use @code{help targets} to list them. * i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy) @end ifset @ifset AMD29K -* UDI29K Remote:: @value{GDBN} and the UDI protocol for AMD29K -* EB29K Remote:: @value{GDBN} with a remote EB29K +* UDI29K Remote:: The UDI protocol for AMD29K +* EB29K Remote:: The EBMON protocol for AMD29K @end ifset @ifset VXWORKS * VxWorks Remote:: @value{GDBN} and VxWorks @@ -7121,13 +7445,14 @@ history facility. @cindex history substitution @cindex history file @kindex set history filename +@kindex GDBHISTFILE @item set history filename @var{fname} -Set the name of the @value{GDBN} command history file to @var{fname}. This is -the file from which @value{GDBN} will read an initial command history -list or to which it will write this list when it exits. This list is -accessed through history expansion or through the history -command editing characters listed below. This file defaults to the -value of the environment variable @code{GDBHISTFILE}, or to +Set the name of the @value{GDBN} command history file to @var{fname}. +This is the file where @value{GDBN} reads an initial command history +list, and where it writes the command history from this session when it +exits. You can access this list through history expansion or through +the history command editing characters listed below. This file defaults +to the value of the environment variable @code{GDBHISTFILE}, or to @file{./.gdb_history} if this variable is not set. @cindex history save @@ -7143,7 +7468,7 @@ 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} will keep in its history list. +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 @@ -7159,7 +7484,7 @@ is off by default. If you decide to enable history expansion with the @code{set history expansion on} command, you may sometimes need to follow @kbd{!} (when it is used as logical not, in an expression) with a space or a tab to prevent it from being expanded. The readline -history facilities will not attempt substitution on the strings +history facilities do not attempt substitution on the strings @kbd{!=} and @kbd{!(}, even when history expansion is enabled. The commands to control history expansion are: @@ -7238,7 +7563,7 @@ These @code{set} commands specify a screen height of @var{lpp} lines and a screen width of @var{cpl} characters. The associated @code{show} commands display the current settings. -If you specify a height of zero lines, @value{GDBN} will not pause during output +If you specify a height of zero lines, @value{GDBN} does not pause during output no matter how long the output is. This is useful if output is to a file or to an editor buffer. @@ -7274,8 +7599,8 @@ set radix 0xa @end example @noindent -will set the base to decimal. On the other hand, @samp{set radix 10} -will leave the radix unchanged no matter what it was. +sets the base to decimal. On the other hand, @samp{set radix 10} +leaves the radix unchanged no matter what it was. @kindex show radix @item show radix @@ -7287,7 +7612,7 @@ Display the current default base for numeric input and display. By default, @value{GDBN} is silent about its inner workings. If you are running on a slow machine, you may want to use the @code{set verbose} command. -It will make @value{GDBN} tell you when it does a lengthy internal operation, so +It makes @value{GDBN} tell you when it does a lengthy internal operation, so you will not think it has crashed. Currently, the messages controlled by @code{set verbose} are those @@ -7420,7 +7745,7 @@ Give documentation to the user-defined command @var{commandname}. The command @var{commandname} must already be defined. This command reads lines of documentation just as @code{define} reads the lines of the command definition, ending with @code{end}. After the @code{document} -command is finished, @code{help} on command @var{commandname} will print +command is finished, @code{help} on command @var{commandname} displays the documentation you have specified. You may use the @code{document} command again to change the @@ -7493,7 +7818,7 @@ If an error occurs during the execution of your hook, execution of (before the command that you actually typed had a chance to run). If you try to define a hook which does not match any known command, you -will get a warning from the @code{define} command. +get a warning from the @code{define} command. @node Command Files @section Command files @@ -7507,11 +7832,14 @@ it would from the terminal. @cindex init file @cindex @file{@value{GDBINIT}} When you start @value{GDBN}, it automatically executes commands from its -@dfn{init files}. These are files named @file{@value{GDBINIT}}. @value{GDBN} reads -the init file (if any) in your home directory and then the init file -(if any) in the current working directory. (The init files are not -executed if you use the @samp{-nx} option; @pxref{Mode Options, -,Choosing modes}.) +@dfn{init files}. These are files named @file{@value{GDBINIT}}. +@value{GDBN} reads the init file (if any) in your home directory, then +processes command line options and operands, and then reads the init +file (if any) in the current working directory. This is so the init +file in your home directory can set options (such as @code{set +complaints}) which affect the processing of the command line options and +operands. The init files are not executed if you use the @samp{-nx} +option; @pxref{Mode Options, ,Choosing modes}. @ifset GENERIC @cindex init file name @@ -7570,7 +7898,7 @@ want. @c because it is not in ANSI. Print @var{text}. Nonprinting characters can be included in @var{text} using C escape sequences, such as @samp{\n} to print a -newline. @strong{No newline will be printed unless you specify one.} +newline. @strong{No newline is printed unless you specify one.} In addition to the standard C escape sequences, a backslash followed by a space stands for a space. This is useful for displaying a string with spaces at the beginning or the end, since leading and @@ -7676,18 +8004,18 @@ source display, and splits the screen to show both your @value{GDBN} session and the source. Explicit @value{GDBN} @code{list} or search commands still produce output as -usual, but you probably will have no reason to use them. +usual, but you probably have no reason to use them from Emacs. @quotation @emph{Warning:} If the directory where your program resides is not your current directory, it can be easy to confuse Emacs about the location of -the source files, in which case the auxiliary display buffer will not +the source files, in which case the auxiliary display buffer does not appear to show your source. @value{GDBN} can find programs by searching your environment's @code{PATH} variable, so the @value{GDBN} input and output -session will proceed normally; but Emacs does not get enough information +session proceeds normally; but Emacs does not get enough information back from @value{GDBN} to locate the source files in this situation. To avoid this problem, either start @value{GDBN} mode from the directory where -your program resides, or specify a full path name when prompted for the +your program resides, or specify an absolute file name when prompted for the @kbd{M-x gdb} argument. A similar confusion can result if you use the @value{GDBN} @code{file} command to @@ -7706,7 +8034,7 @@ Emacs variable @code{gdb-command-name}; for example, @noindent (preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or -in your @file{.emacs} file) will make Emacs call the program named +in your @file{.emacs} file) makes Emacs call the program named ``@code{mygdb}'' instead. In the @value{GDBN} I/O buffer, you can use these special Emacs commands in @@ -7766,8 +8094,8 @@ argument for @code{disassemble} by typing @kbd{C-x &}. You can customize this further by defining elements of the list @code{gdb-print-command}; once it is defined, you can format or otherwise process numbers picked up by @kbd{C-x &} before they are -inserted. A numeric argument to @kbd{C-x &} will both indicate that you -wish special formatting, and act as an index to pick an element of the +inserted. A numeric argument to @kbd{C-x &} indicates that you +wish special formatting, and also acts as an index to pick an element of the list. If the list element is a string, the number to be inserted is formatted using the Emacs function @code{format}; otherwise the number is passed as an argument to the corresponding list element. @@ -7778,7 +8106,7 @@ tells @value{GDBN} to set a breakpoint on the source line point is on. If you accidentally delete the source-display buffer, an easy way to get it back is to type the command @code{f} in the @value{GDBN} buffer, to -request a frame display; when you run under Emacs, this will recreate +request a frame display; when you run under Emacs, this recreates the source buffer if necessary to show you the context of the current frame. @@ -7786,7 +8114,7 @@ The source files displayed in Emacs are in ordinary Emacs buffers which are visiting the source files in the usual way. You can edit the files with these buffers if you wish; but keep in mind that @value{GDBN} communicates with Emacs in terms of line numbers. If you add or -delete lines from the text, the line numbers that @value{GDBN} knows will cease +delete lines from the text, the line numbers that @value{GDBN} knows cease to correspond properly with the code. @c The following dropped because Epoch is nonstandard. Reactivate @@ -8028,7 +8356,7 @@ We recommend that you save your time for something else. Of course, if you can find a simpler example to report @emph{instead} of the original one, that is a convenience for us. Errors in the output will be easier to spot, running under the debugger will take -less time, etc. +less time, and so on. However, simplification is not vital; if you do not want to do this, report the bug anyway and send us the entire test case you used. @@ -8192,10 +8520,10 @@ unset &&\rm(No longer an alias for delete)\cr @cindex GDB reference card @cindex reference card The GDB 4 release includes an already-formatted reference card, ready -for printing with PostScript or GhostScript, in the @file{gdb} +for printing with PostScript or Ghostscript, in the @file{gdb} subdirectory of the main source directory@footnote{In @file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} -release.}. If you can use PostScript or GhostScript with your printer, +release.}. If you can use PostScript or Ghostscript with your printer, you can print the reference card immediately with @file{refcard.ps}. The release also includes the source for the reference card. You @@ -8405,7 +8733,7 @@ with the @samp{--srcdir} option to specify where to find the source. (You also need to specify a path to find @code{configure} itself from your working directory. If the path to @code{configure} would be the same as the argument to @samp{--srcdir}, you can leave out -the @samp{--srcdir} option; it will be assumed.) +the @samp{--srcdir} option; it is assumed.) For example, with version @value{GDBVN}, you can build GDB in a separate directory for a Sun 4 like this: @@ -8440,7 +8768,7 @@ called @code{configure} (or one of its subdirectories). The @code{Makefile} that @code{configure} generates in each source directory also runs recursively. If you type @code{make} in a source directory such as @file{gdb-@value{GDBVN}} (or in a separate configured -directory configured with @samp{--srcdir=@var{path}/gdb-@value{GDBVN}}), you +directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you will build all the required libraries, and then build GDB. When you have multiple hosts or targets configured in separate @@ -8503,7 +8831,7 @@ Does,,configure.info}, for a full explanation of @code{configure}. @example configure @r{[}--help@r{]} @r{[}--prefix=@var{dir}@r{]} - @r{[}--srcdir=@var{path}@r{]} + @r{[}--srcdir=@var{dirname}@r{]} @r{[}--norecursion@r{]} @r{[}--rm@r{]} @r{[}--target=@var{target}@r{]} @var{host} @end example @@ -8521,7 +8849,9 @@ Display a quick summary of how to invoke @code{configure}. Configure the source to install programs and files under directory @file{@var{dir}}. -@item --srcdir=@var{path} +@c avoid splitting the warning from the explanation: +@need 2000 +@item --srcdir=@var{dirname} @strong{Warning: using this option requires GNU @code{make}, or another @code{make} that implements the @code{VPATH} feature.}@* Use this option to make configurations in directories separate from the @@ -8529,9 +8859,9 @@ GDB source directories. Among other things, you can use this to build (or maintain) several configurations simultaneously, in separate directories. @code{configure} writes configuration specific files in the current directory, but arranges for them to use the source in the -directory @var{path}. @code{configure} will create directories under +directory @var{dirname}. @code{configure} creates directories under the working directory in parallel to the source directories below -@var{path}. +@var{dirname}. @item --norecursion Configure only the directory level where @code{configure} is executed; do not diff --git a/gnu/usr.bin/gdb/doc/gdbint.texinfo b/gnu/usr.bin/gdb/doc/gdbint.texinfo index a2f625771e9..59e5a7f548e 100644 --- a/gnu/usr.bin/gdb/doc/gdbint.texinfo +++ b/gnu/usr.bin/gdb/doc/gdbint.texinfo @@ -1,6 +1,6 @@ \input texinfo @setfilename gdbint.info -@c $Id: gdbint.texinfo,v 1.1.1.1 1993/10/30 21:59:41 jkh Exp $ +@c $Id: gdbint.texinfo,v 1.76 1994/07/17 21:17:18 shebs Exp $ @ifinfo @format @@ -13,7 +13,7 @@ END-INFO-DIR-ENTRY @ifinfo This file documents the internals of the GNU debugger GDB. -Copyright 1990, 1991, 1992, 1993 Free Software Foundation, Inc. +Copyright 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. Contributed by Cygnus Support. Written by John Gilmore. Permission is granted to make and distribute verbatim copies of @@ -42,7 +42,7 @@ regarded as a program in the language TeX). @page @tex \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 1.1.1.1 $} % For use in headers, footers too +\xdef\manvers{\$Revision: 1.76 $} % For use in headers, footers too {\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par @@ -51,7 +51,7 @@ regarded as a program in the language TeX). @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 1990, 1991, 1992, 1993 Free Software Foundation, Inc. +Copyright @copyright{} 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -201,17 +201,17 @@ Good luck! @node Debugging GDB @chapter Debugging GDB with itself -If gdb is limping on your machine, this is the preferred way to get it +If GDB is limping on your machine, this is the preferred way to get it fully functional. Be warned that in some ancient Unix systems, like Ultrix 4.2, a program can't be running in one process while it is being debugged in another. Rather than typing the command @code{@w{./gdb ./gdb}}, which works on Suns and such, you can copy @file{gdb} to @file{gdb2} and then type @code{@w{./gdb ./gdb2}}. -When you run gdb in the gdb source directory, it will read a +When you run GDB in the GDB source directory, it will read a @file{.gdbinit} file that sets up some simple things to make debugging gdb easier. The @code{info} command, when executed without a subcommand -in a gdb being debugged by gdb, will pop you back up to the top level +in a GDB being debugged by gdb, will pop you back up to the top level gdb. See @file{.gdbinit} for details. If you use emacs, you will probably want to do a @code{make TAGS} after @@ -219,7 +219,7 @@ you configure your distribution; this will put the machine dependent routines for your local machine where they will be accessed first by @kbd{M-.} -Also, make sure that you've either compiled gdb with your local cc, or +Also, make sure that you've either compiled GDB with your local cc, or have run @code{fixincludes} if you are compiling with gcc. @node New Architectures @@ -347,7 +347,7 @@ Then edit @file{bfd/configure.host}. Add a line to recognize your @code{my_host} to @var{xxx} when you recognize it. This will cause your file @file{h-@var{xxx}.h} to be linked to @file{sysdep.h} at configuration time. When creating the line that recognizes your configuration, -only match the fields that you really need to match; e.g. don't match +only match the fields that you really need to match; e.g. don't match the architecture or manufacturer if the OS is sufficient to distinguish the configuration that your @file{h-@var{xxx}.h} file supports. Don't match the manufacturer name unless you really need to. @@ -452,7 +452,7 @@ Now, you are now ready to try configuring GDB to compile using your system as its host. From the top level (above @file{bfd}, @file{gdb}, etc), do: @example -./configure @var{xxx} +target=vxworks960 +./configure @var{xxx} --target=vxworks960 @end example This will configure your system to cross-compile for VxWorks on @@ -933,14 +933,14 @@ more work. Fundamental Types (e.g., FT_VOID, FT_BOOLEAN). -These are the fundamental types that gdb uses internally. Fundamental +These are the fundamental types that GDB uses internally. Fundamental types from the various debugging formats (stabs, ELF, etc) are mapped into one of these. They are basically a union of all fundamental types that -gdb knows about for all the languages that gdb knows about. +gdb knows about for all the languages that GDB knows about. Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY). -Each time gdb builds an internal type, it marks it with one of these +Each time GDB builds an internal type, it marks it with one of these types. The type may be a fundamental type, such as TYPE_CODE_INT, or a derived type, such as TYPE_CODE_PTR which is a pointer to another type. Typically, several FT_* types map to one TYPE_CODE_* type, and @@ -950,7 +950,7 @@ the type is signed or unsigned, and how many bits it uses. Builtin Types (e.g., builtin_type_void, builtin_type_char). These are instances of type structs that roughly correspond to fundamental -types and are created as global types for gdb to use for various ugly +types and are created as global types for GDB to use for various ugly historical reasons. We eventually want to eliminate these. Note for example that builtin_type_int initialized in gdbtypes.c is basically the same as a TYPE_CODE_INT type that is initialized in c-lang.c for an @@ -997,7 +997,7 @@ string table, etc. @chapter Symbol Reading GDB reads symbols from "symbol files". The usual symbol file is the -file containing the program which gdb is debugging. GDB can be directed +file containing the program which GDB is debugging. GDB can be directed to use a different file for symbols (with the ``symbol-file'' command), and it can also read more symbols via the ``add-file'' and ``load'' commands, or while reading symbols from shared libraries. @@ -1490,23 +1490,30 @@ available somehow (e.g. anonymous FTP), and announce it on When GDB is configured and compiled, various macros are defined or left undefined, to control compilation based on the attributes of the host -system. These macros and their meanings are: +system. These macros and their meanings (or if the meaning is not +documented here, then one of the source files where they are used is +indicated) are: @emph{NOTE: For now, both host and target conditionals are here. Eliminate target conditionals from this list as they are identified.} @table @code + @item BLOCK_ADDRESS_FUNCTION_RELATIVE dbxread.c + @item GDBINIT_FILENAME The default name of GDB's initialization file (normally @file{.gdbinit}). + @item KERNELDEBUG tm-hppa.h + @item MEM_FNS_DECLARED Your host config file defines this if it includes declarations of @code{memcpy} and @code{memset}. Define this to avoid conflicts between the native include files and the declarations in @file{defs.h}. + @item NO_SYS_FILE dbxread.c @item PYRAMID_CONTROL_FRAME_DEBUGGING @@ -1533,8 +1540,6 @@ altos-xdep.c xm-altos.h @item ASCII_COFF remote-adapt.c -@item BADMAG -coffread.c @item BCS tm-delta88.h @item BEFORE_MAIN_LOOP_HOOK @@ -1551,28 +1556,20 @@ solib.c dbxread.c @item BPT_VECTOR tm-m68k.h -@item BREAKPOINT -tm-m68k.h -@item BREAKPOINT_DEBUG -breakpoint.c + @item BROKEN_LARGE_ALLOCA Avoid large @code{alloca}'s. For example, on sun's, Large alloca's fail because the attempt to increase the stack limit in main() fails because shared libraries are allocated just below the initial stack limit. The SunOS kernel will not allow the stack to grow into the area occupied by the shared libraries. -@item BSTRING -regex.c + @item CALL_DUMMY valops.c @item CALL_DUMMY_LOCATION inferior.h @item CALL_DUMMY_STACK_ADJUST valops.c -@item CANNOT_FETCH_REGISTER -hppabsd-xdep.c -@item CANNOT_STORE_REGISTER -findvar.c @item CFRONT_PRODUCER dwarfread.c @item CHILD_PREPARE_TO_STORE @@ -1589,8 +1586,6 @@ symm-tdep.c stack.c @item CPLUS_MARKER cplus-dem.c -@item CREATE_INFERIOR_HOOK -infrun.c @item C_ALLOCA regex.c @item C_GLBLREG @@ -1599,16 +1594,16 @@ coffread.c partial-stab.h @item DBX_PARM_SYMBOL_CLASS stabsread.c -@item DEBUG -remote-adapt.c @item DEBUG_INFO partial-stab.h @item DEBUG_PTRACE hppabsd-xdep.c @item DECR_PC_AFTER_BREAK breakpoint.c + @item DEFAULT_PROMPT The default value of the prompt string (normally @code{"(gdb) "}). + @item DELTA88 m88k-xdep.c @item DEV_TTY @@ -1637,24 +1632,6 @@ target.c infcmd.c @item FOPEN_RB defs.h -@item FRAMELESS_FUNCTION_INVOCATION -blockframe.c -@item FRAME_ARGS_ADDRESS_CORRECT -stack.c -@item FRAME_CHAIN_COMBINE -blockframe.c -@item FRAME_CHAIN_VALID -frame.h -@item FRAME_CHAIN_VALID_ALTERNATE -frame.h -@item FRAME_FIND_SAVED_REGS -stack.c -@item FRAME_GET_BASEREG_VALUE -frame.h -@item FRAME_NUM_ARGS -tm-m68k.h -@item FRAME_SPECIFICATION_DYADIC -stack.c @item FUNCTION_EPILOGUE_SIZE coffread.c @item F_OK @@ -1673,9 +1650,11 @@ findvar.c dwarfread.c @item HANDLE_RBRAC partial-stab.h + @item HAVE_MMAP In some cases, use the system call @code{mmap} for reading symbol tables. For some machines this allows for sharing and quick updates. + @item HAVE_REGISTER_WINDOWS findvar.c @item HAVE_SIGSETMASK @@ -1687,7 +1666,7 @@ arm-tdep.c @item HOSTING_ONLY xm-rtbsd.h @item HOST_BYTE_ORDER -ieee-float.c +findvar.c @item HPUX_ASM xm-hp300hpux.h @item HPUX_VERSION_5 @@ -1696,8 +1675,6 @@ hp300ux-xdep.c infrun.c @item I80960 remote-vx.c -@item IEEE_DEBUG -ieee-float.c @item IEEE_FLOAT valprint.c @item IGNORE_SYMBOL @@ -1728,20 +1705,24 @@ values.c dbxread.c @item KERNEL_DEBUGGING tm-ultra3.h + @item KERNEL_U_ADDR Define this to the address of the @code{u} structure (the ``user struct'', also known as the ``u-page'') in kernel virtual memory. GDB needs to know this so that it can subtract this address from absolute addresses in the upage, that are obtained via ptrace or from core files. On systems that don't need this value, set it to zero. + @item KERNEL_U_ADDR_BSD Define this to cause GDB to determine the address of @code{u} at runtime, by using Berkeley-style @code{nlist} on the kernel's image in the root directory. + @item KERNEL_U_ADDR_HPUX Define this to cause GDB to determine the address of @code{u} at runtime, by using HP-style @code{nlist} on the kernel's image in the root directory. + @item LCC_PRODUCER dwarfread.c @item LOG_FILE @@ -1760,25 +1741,33 @@ defs.h source.c @item L_LNNO32 coffread.c + @item L_SET This macro is used as the argument to lseek (or, most commonly, bfd_seek). -FIXME, it should be replaced by SEEK_SET instead, which is the POSIX equivalent. +FIXME, should be replaced by SEEK_SET instead, which is the POSIX equivalent. + @item MACHKERNELDEBUG hppabsd-tdep.c @item MAINTENANCE dwarfread.c + @item MAINTENANCE_CMDS If the value of this is 1, then a number of optional maintenance commands are compiled in. + @item MALLOC_INCOMPATIBLE Define this if the system's prototype for @code{malloc} differs from the @sc{ANSI} definition. + @item MIPSEL mips-tdep.c + @item MMAP_BASE_ADDRESS When using HAVE_MMAP, the first mapping should go at this address. + @item MMAP_INCREMENT when using HAVE_MMAP, this is the increment between mappings. + @item MONO ser-go32.c @item MOTOROLA @@ -1791,8 +1780,10 @@ infrun.c exec.c @item NFAILURES regex.c + @item NORETURN (in defs.h - is this really useful to define/undefine?) + @item NOTDEF regex.c @item NOTDEF @@ -1805,6 +1796,7 @@ infrun.c remote-mm.c @item NO_JOB_CONTROL signals.h + @item NO_MMALLOC GDB will use the @code{mmalloc} library for memory allocation for symbol reading, unless this symbol is defined. Define it on systems @@ -1816,9 +1808,11 @@ to override the setting of @code{MMALLOC_LIB} to empty, in the Makefile. Therefore, this define is usually set on the command line by overriding @code{MMALLOC_DISABLE} in @file{config/*/*.mh}, rather than by defining it in @file{xm-*.h}. + @item NO_MMALLOC_CHECK Define this if you are using @code{mmalloc}, but don't want the overhead of checking the heap with @code{mmcheck}. + @item NO_SIGINTERRUPT remote-adapt.c @item NO_SINGLE_STEP @@ -1887,6 +1881,7 @@ state.c state.c @item SEM coffread.c + @item SET_STACK_LIMIT_HUGE When defined, stack limits will be raised to their maximum. Use this if your host supports @code{setrlimit} and you have trouble with @@ -1894,6 +1889,7 @@ if your host supports @code{setrlimit} and you have trouble with Also used in @file{fork-child.c} to return stack limits before child processes are forked. + @item SHELL_COMMAND_CONCAT infrun.c @item SHELL_FILE @@ -1904,24 +1900,16 @@ breakpoint.c regex.c @item SIGTRAP_STOP_AFTER_LOAD infrun.c -@item SKIP_PROLOGUE -tm-m68k.h -@item SKIP_PROLOGUE_FRAMELESS_P -blockframe.c @item SKIP_TRAMPOLINE_CODE infrun.c @item SOLIB_ADD core.c -@item SOLIB_CREATE_INFERIOR_HOOK -infrun.c @item STACK_ALIGN valops.c @item START_INFERIOR_TRAPS_EXPECTED infrun.c @item STOP_SIGNAL main.c -@item STORE_RETURN_VALUE -tm-m68k.h @item SUN4_COMPILER_FEATURE infrun.c @item SUN_FIXED_LBRAC_BUG @@ -1938,8 +1926,6 @@ symfile.c regex.c @item Sword regex.c -@item TDESC -infrun.c @item TIOCGETC inflow.c @item TIOCGLTC @@ -1968,10 +1954,12 @@ xm-news.h inflow.c @item USE_STRUCT_CONVENTION values.c + @item USG Means that System V (prior to SVR4) include files are in use. (FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c}, @file{remote-nindy.c}, and @file{utils.c} for other things, at the moment.) + @item USIZE xm-m88k.h @item U_FPSTATE @@ -1980,10 +1968,6 @@ i386-xdep.c dbxread.c @item WRS_ORIG remote-vx.c -@item _LANG_c -language.c -@item _LANG_m2 -language.c @item __GNUC__ news-xdep.c @item __GO32__ @@ -2041,10 +2025,13 @@ system. These macros and their meanings are: Eliminate host conditionals from this list as they are identified.} @table @code + @item PUSH_DUMMY_FRAME Used in @samp{call_function_by_hand} to create an artificial stack frame. + @item POP_FRAME Used in @samp{call_function_by_hand} to remove an artificial stack frame. + @item BLOCK_ADDRESS_FUNCTION_RELATIVE dbxread.c @item KERNELDEBUG @@ -2073,12 +2060,8 @@ altos-xdep.c xm-altos.h @item ASCII_COFF remote-adapt.c -@item BADMAG -coffread.c @item BCS tm-delta88.h -@item BEFORE_MAIN_LOOP_HOOK -main.c @item BELIEVE_PCC_PROMOTION coffread.c @item BELIEVE_PCC_PROMOTION_TYPE @@ -2093,20 +2076,25 @@ dbxread.c tm-m68k.h @item BREAKPOINT tm-m68k.h -@item BREAKPOINT_DEBUG -breakpoint.c -@item BSTRING -regex.c @item CALL_DUMMY valops.c @item CALL_DUMMY_LOCATION inferior.h @item CALL_DUMMY_STACK_ADJUST valops.c -@item CANNOT_FETCH_REGISTER -hppabsd-xdep.c -@item CANNOT_STORE_REGISTER -findvar.c + +@item CANNOT_FETCH_REGISTER (regno) +A C expression that should be nonzero if @var{regno} cannot be +fetched from an inferior process. +This is only relevant if @code{FETCH_INFERIOR_REGISTERS} is not +defined. + +@item CANNOT_STORE_REGISTER (regno) +A C expression that should be nonzero if @var{regno} should not be +written to the target. This is often the case for program counters, +status words, and other special registers. If this is not defined, +GDB will assume that all registers may be written. + @item CFRONT_PRODUCER dwarfread.c @item CHILD_PREPARE_TO_STORE @@ -2123,18 +2111,12 @@ symm-tdep.c stack.c @item CPLUS_MARKER cplus-dem.c -@item CREATE_INFERIOR_HOOK -infrun.c -@item C_ALLOCA -regex.c @item C_GLBLREG coffread.c @item DBXREAD_ONLY partial-stab.h @item DBX_PARM_SYMBOL_CLASS stabsread.c -@item DEBUG -remote-adapt.c @item DEBUG_INFO partial-stab.h @item DEBUG_PTRACE @@ -2155,9 +2137,11 @@ remote.c infrun.c @item DO_REGISTERS_INFO infcmd.c + @item END_OF_TEXT_DEFAULT This is an expression that should designate the end of the text section (? FIXME ?) + @item EXTRACT_RETURN_VALUE tm-m68k.h @item EXTRACT_STRUCT_VALUE_ADDRESS @@ -2178,14 +2162,14 @@ a68v-xdep.c mach386-xdep.c @item FP_REGNUM parse.c -@item FPU -Unused? 6-oct-92 rich@@cygnus.com. FIXME. @item FRAMELESS_FUNCTION_INVOCATION blockframe.c @item FRAME_ARGS_ADDRESS_CORRECT stack.c + @item FRAME_CHAIN Given FRAME, return a pointer to the calling frame. + @item FRAME_CHAIN_COMBINE blockframe.c @item FRAME_CHAIN_VALID @@ -2196,12 +2180,17 @@ frame.h stack.c @item FRAME_GET_BASEREG_VALUE frame.h -@item FRAME_NUM_ARGS -tm-m68k.h + +@item FRAME_NUM_ARGS (val, fi) +For the frame described by fi, set val to the number of arguments +that are being passed. + @item FRAME_SPECIFICATION_DYADIC stack.c + @item FRAME_SAVED_PC Given FRAME, return the pc saved there. That is, the return address. + @item FUNCTION_EPILOGUE_SIZE coffread.c @item F_OK @@ -2214,16 +2203,19 @@ dbxread.c symtab.c @item GCC_PRODUCER dwarfread.c + @item GDB_TARGET_IS_HPPA This determines whether horrible kludge code in dbxread.c and partial-stab.h is used to mangle multiple-symbol-table files from HPPA's. This should all be ripped out, and a scheme like elfread.c used. + @item GDB_TARGET_IS_MACH386 mach386-xdep.c @item GDB_TARGET_IS_SUN3 a68v-xdep.c @item GDB_TARGET_IS_SUN386 sun386-xdep.c + @item GET_LONGJMP_TARGET For most machines, this is a target-dependent parameter. On the DECstation and the Iris, this is a native-dependent parameter, since is @@ -2233,6 +2225,7 @@ This macro determines the target PC address that longjmp() will jump to, assuming that we have just stopped at a longjmp breakpoint. It takes a CORE_ADDR * as argument, and stores the target PC value through this pointer. It examines the current state of the machine as needed. + @item GET_SAVED_REGISTER findvar.c @item GPLUS_PRODUCER @@ -2255,8 +2248,6 @@ inflow.c arm-tdep.c @item HOSTING_ONLY xm-rtbsd.h -@item HOST_BYTE_ORDER -ieee-float.c @item HPUX_ASM xm-hp300hpux.h @item HPUX_VERSION_5 @@ -2265,12 +2256,12 @@ hp300ux-xdep.c infrun.c @item I80960 remote-vx.c + @item IBM6000_TARGET Shows that we are configured for an IBM RS/6000 target. This conditional should be eliminated (FIXME) and replaced by feature-specific macros. It was introduced in haste and we are repenting at leisure. -@item IEEE_DEBUG -ieee-float.c + @item IEEE_FLOAT valprint.c @item IGNORE_SYMBOL @@ -2331,13 +2322,9 @@ altos-xdep.c infrun.c @item NEED_TEXT_START_END exec.c -@item NFAILURES -regex.c @item NNPC_REGNUM infrun.c @item NOTDEF -regex.c -@item NOTDEF remote-adapt.c @item NOTDEF remote-mm.c @@ -2397,15 +2384,15 @@ tm-a29k.h exec.c @item REG_STRUCT_HAS_ADDR findvar.c -@item RE_NREGS -regex.h @item R_FP dwarfread.c @item R_OK xm-altos.h + @item SDB_REG_TO_REGNUM Define this to convert sdb register numbers -into gdb regnums. If not defined, no conversion will be done. +into GDB regnums. If not defined, no conversion will be done. + @item SEEK_END state.c @item SEEK_SET @@ -2418,73 +2405,91 @@ infrun.c infrun.c @item SHIFT_INST_REGS breakpoint.c -@item SIGN_EXTEND_CHAR -regex.c @item SIGTRAP_STOP_AFTER_LOAD infrun.c + @item SKIP_PROLOGUE -tm-m68k.h +A C statement that advances the PC across any function entry +prologue instructions so as to reach ``real'' code. + @item SKIP_PROLOGUE_FRAMELESS_P -blockframe.c +A C statement that should behave similarly, but that can stop +as soon as the function is known to have a frame. +If not defined, @code{SKIP_PROLOGUE} will be used instead. + @item SKIP_TRAMPOLINE_CODE infrun.c @item SOLIB_ADD core.c -@item SOLIB_CREATE_INFERIOR_HOOK -infrun.c @item SP_REGNUM parse.c + @item STAB_REG_TO_REGNUM Define this to convert stab register numbers (as gotten from `r' declarations) -into gdb regnums. If not defined, no conversion will be done. +into GDB regnums. If not defined, no conversion will be done. + @item STACK_ALIGN valops.c @item START_INFERIOR_TRAPS_EXPECTED infrun.c @item STOP_SIGNAL main.c -@item STORE_RETURN_VALUE -tm-m68k.h + +@item STORE_RETURN_VALUE (type, valbuf) +A C expression that stores a function return value of type @var{type}, +where @var{valbuf} is the address of the value to be stored. + @item SUN4_COMPILER_FEATURE infrun.c @item SUN_FIXED_LBRAC_BUG dbxread.c @item SVR4_SHARED_LIBS solib.c -@item SWITCH_ENUM_BUG -regex.c @item SYM1 tm-ultra3.h @item SYMBOL_RELOADING_DEFAULT symfile.c -@item SYNTAX_TABLE -regex.c -@item Sword -regex.c + @item TARGET_BYTE_ORDER -defs.h +The ordering of bytes in the target. +This must be defined to be either @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. + @item TARGET_CHAR_BIT -defs.h +Number of bits in a char; defaults to 8. + @item TARGET_COMPLEX_BIT -defs.h +Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}. + @item TARGET_DOUBLE_BIT -defs.h +Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}. + @item TARGET_DOUBLE_COMPLEX_BIT -defs.h +Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}. + @item TARGET_FLOAT_BIT -defs.h +Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}. + @item TARGET_INT_BIT -defs.h +Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}. + @item TARGET_LONG_BIT -defs.h +Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}. + @item TARGET_LONG_DOUBLE_BIT -defs.h +Number of bits in a long double float; +defaults to @code{2 * TARGET_DOUBLE_BIT}. + @item TARGET_LONG_LONG_BIT -defs.h +Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}. + @item TARGET_PTR_BIT -defs.h +Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}. + +@item TARGET_SHORT_BIT +Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. + @item TARGET_READ_PC -@item TARGET_WRITE_PC +@item TARGET_WRITE_PC (val, pid) @item TARGET_READ_SP @item TARGET_WRITE_SP @item TARGET_READ_FP @@ -2498,10 +2503,6 @@ These macros are useful when a target keeps one of these registers in a hard to get at place; for example, part in a segment register and part in an ordinary register. -@item TARGET_SHORT_BIT -defs.h -@item TDESC -infrun.c @item T_ARG coffread.c @item T_VOID @@ -2522,10 +2523,6 @@ i386-xdep.c dbxread.c @item WRS_ORIG remote-vx.c -@item _LANG_c -language.c -@item _LANG_m2 -language.c @item __GO32__ inflow.c @item __HPUX_ASM__ @@ -2548,14 +2545,14 @@ m68k-stub.c ns32k-opcode.h @item sgi mips-tdep.c -@item sparc -regex.c @item sun m68k-tdep.c @item sun386 tm-sun386.h + @item test (Define this to enable testing code in regex.c.) + @end table @node Native Conditionals @@ -2567,9 +2564,11 @@ are the same. These macros should be defined (or left undefined) in @file{nm-@var{system}.h}. @table @code + @item ATTACH_DETACH -If defined, then gdb will include support for the @code{attach} and +If defined, then GDB will include support for the @code{attach} and @code{detach} commands. + @item FETCH_INFERIOR_REGISTERS Define this if the native-dependent code will provide its own routines @@ -2578,6 +2577,7 @@ own routines If this symbol is @emph{not} defined, and @file{infptrace.c} is included in this configuration, the default routines in @file{infptrace.c} are used for these functions. + @item GET_LONGJMP_TARGET For most machines, this is a target-dependent parameter. On the DECstation and the Iris, this is a native-dependent parameter, since is @@ -2587,22 +2587,32 @@ This macro determines the target PC address that longjmp() will jump to, assuming that we have just stopped at a longjmp breakpoint. It takes a CORE_ADDR * as argument, and stores the target PC value through this pointer. It examines the current state of the machine as needed. + @item PROC_NAME_FMT Defines the format for the name of a @file{/proc} device. Should be defined in @file{nm.h} @emph{only} in order to override the default definition in @file{procfs.c}. + @item PTRACE_FP_BUG mach386-xdep.c + @item PTRACE_ARG3_TYPE The type of the third argument to the @code{ptrace} system call, if it exists and is different from @code{int}. + @item REGISTER_U_ADDR Defines the offset of the registers in the ``u area''; @pxref{Host}. + +@item SOLIB_CREATE_INFERIOR_HOOK +Define this to expand into any shared-library-relocation code +that you want to be run just after the child process has been forked. + @item USE_PROC_FS This determines whether small routines in @file{*-tdep.c}, which translate register values between GDB's internal representation and the /proc representation, are compiled. + @item U_REGS_OFFSET This is the offset of the registers in the upage. It need only be defined if the generic ptrace register access routines in @@ -2614,6 +2624,7 @@ from @file{infptrace.c} is good enough, leave it undefined. The default value means that u.u_ar0 @emph{points to} the location of the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means that u.u_ar0 @emph{is} the location of the registers. + @end table @node Obsolete Conditionals diff --git a/gnu/usr.bin/gdb/doc/inc-hist.texi b/gnu/usr.bin/gdb/doc/inc-hist.texi new file mode 100644 index 00000000000..539e372c5d4 --- /dev/null +++ b/gnu/usr.bin/gdb/doc/inc-hist.texi @@ -0,0 +1,155 @@ +@ignore +This file is completely identical to hsuser.texinfo, except that it has the +reference to the programming manual removed. There are definately better ways +to do this! + +This file documents the user interface to the GNU History library. + +Copyright (C) 1988, 1991 Free Software Foundation, Inc. +Authored by Brian Fox. + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on +all copies. + +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +GNU Copyright statement is available to the distributee, and provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ignore + +@node Using History Interactively +@appendix Using History Interactively + +This chapter describes how to use the GNU History Library interactively, +from a user's standpoint. + +@menu +* History Interaction:: What it feels like using History as a user. +@end menu + +@node History Interaction +@section History Interaction +@cindex expansion + +The History library provides a history expansion feature that is similar +to the history expansion in Csh. The following text describes the sytax +that you use to manipulate the history information. + +History expansion takes place in two parts. The first is to determine +which line from the previous history should be used during substitution. +The second is to select portions of that line for inclusion into the +current one. The line selected from the previous history is called the +@dfn{event}, and the portions of that line that are acted upon are +called @dfn{words}. The line is broken into words in the same fashion +that the Bash shell does, so that several English (or Unix) words +surrounded by quotes are considered as one word. + +@menu +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of susbstitution. +@end menu + +@node Event Designators +@subsection Event Designators +@cindex event designators + +An event designator is a reference to a command line entry in the +history list. + +@table @asis + +@item @code{!} +Start a history subsititution, except when followed by a space, tab, or +the end of the line... @key{=} or @key{(}. + +@item @code{!!} +Refer to the previous command. This is a synonym for @code{!-1}. + +@item @code{!n} +Refer to command line @var{n}. + +@item @code{!-n} +Refer to the command line @var{n} lines back. + +@item @code{!string} +Refer to the most recent command starting with @var{string}. + +@item @code{!?string}[@code{?}] +Refer to the most recent command containing @var{string}. + +@end table + +@node Word Designators +@subsection Word Designators + +A @key{:} separates the event specification from the word designator. It +can be omitted if the word designator begins with a @key{^}, @key{$}, +@key{*} or @key{%}. Words are numbered from the beginning of the line, +with the first word being denoted by a 0 (zero). + +@table @code + +@item 0 (zero) +The zero'th word. For many applications, this is the command word. + +@item n +The @var{n}'th word. + +@item ^ +The first argument. that is, word 1. + +@item $ +The last argument. + +@item % +The word matched by the most recent @code{?string?} search. + +@item x-y +A range of words; @code{-@var{y}} Abbreviates @code{0-@var{y}}. + +@item * +All of the words, excepting the zero'th. This is a synonym for @code{1-$}. +It is not an error to use @key{*} if there is just one word in the event. +The empty string is returned in that case. + +@end table + +@node Modifiers +@subsection Modifiers + +After the optional word designator, you can add a sequence of one or more +of the following modifiers, each preceded by a @key{:}. + +@table @code + +@item # +The entire command line typed so far. This means the current command, +not the previous command, so it really isn't a word designator, and doesn't +belong in this section. + +@item h +Remove a trailing pathname component, leaving only the head. + +@item r +Remove a trailing suffix of the form @samp{.}@var{suffix}, leaving the basename. + +@item e +Remove all but the suffix. + +@item t +Remove all leading pathname components, leaving the tail. + +@item p +Print the new command but do not execute it. +@end table diff --git a/gnu/usr.bin/gdb/doc/remote.texi b/gnu/usr.bin/gdb/doc/remote.texi index 5b7ec90e1e8..422379dd893 100644 --- a/gnu/usr.bin/gdb/doc/remote.texi +++ b/gnu/usr.bin/gdb/doc/remote.texi @@ -69,13 +69,13 @@ For @sc{sparc} architectures. @item m68k-stub.c @kindex m68k-stub.c @cindex Motorola 680x0 -@cindex 680x0 +@cindex m680x0 For Motorola 680x0 architectures. @item i386-stub.c @kindex i386-stub.c @cindex Intel -@cindex 386 +@cindex i386 For Intel 386 and compatible architectures. @end table @@ -131,12 +131,12 @@ Use this auxiliary subroutine to make your program contain a breakpoint. Depending on the particular situation, this may be the only way for @value{GDBN} to get control. For instance, if your target machine has some sort of interrupt button, you won't need to call this; -pressing the interrupt button will transfer control to +pressing the interrupt button transfers control to @code{handle_exception}---in effect, to @value{GDBN}. On some machines, simply receiving characters on the serial port may also trigger a trap; again, in that situation, you don't need to call @code{breakpoint} from your own program---simply running @samp{target remote} from the host -@value{GDBN} session will get control. +@value{GDBN} session gets control. Call @code{breakpoint} if none of these is true, or if you simply want to make certain your program stops at a predetermined point for the @@ -149,8 +149,10 @@ start of your debugging session. @cindex remote stub, support routines The debugging stubs that come with @value{GDBN} are set up for a particular chip architecture, but they have no information about the rest of your -debugging target machine. To allow the stub to work, you must supply -these special low-level subroutines: +debugging target machine. + +First of all you need to tell the stub how to communicate with the +serial port. @table @code @item int getDebugChar() @@ -164,7 +166,24 @@ different name is used to allow you to distinguish the two if you wish. Write this subroutine to write a single character to the serial port. It may be identical to @code{putchar} for your target system; a different name is used to allow you to distinguish the two if you wish. +@end table +@cindex control C, and remote debugging +@cindex interrupting remote targets +If you want @value{GDBN} to be able to stop your program while it is +running, you need to use an interrupt-driven serial driver, and arrange +for it to stop when it receives a @code{^C} (@samp{\003}, the control-C +character). That is the character which @value{GDBN} uses to tell the +remote system to stop. + +Getting the debugging target to return the proper status to @value{GDBN} +probably requires changes to the standard stub; one quick and dirty way +is to just execute a breakpoint instruction (the ``dirty'' part is that +@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). + +Other routines you need to supply are: + +@table @code @item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) @kindex exceptionHandler Write this function to install @var{exception_address} in the exception @@ -177,7 +196,7 @@ its meaning is architecture-dependent (for example, different numbers might represent divide by zero, misaligned access, etc). When this exception occurs, control should be transferred directly to @var{exception_address}, and the processor state (stack, registers, -etc.) should be just as it is when a processor exception occurs. So if +and so on) should be just as it is when a processor exception occurs. So if you want to use a jump instruction to reach @var{exception_address}, it should be a simple jump, not a jump to subroutine. @@ -210,7 +229,7 @@ either obtain it from your hardware manufacturer, or write your own. @end table If you do not use the GNU C compiler, you may need other standard -library subroutines as well; this will vary from one stub to another, +library subroutines as well; this varies from one stub to another, but in general the stubs are likely to use any of the common library subroutines which @code{gcc} generates as inline code. @@ -320,7 +339,7 @@ remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} goes back to waiting. @node Protocol -@subsubsection Outline of the communication protocol +@subsubsection Communication protocol @cindex debugging stub, example @cindex remote stub, example @@ -382,10 +401,12 @@ Read @var{count} bytes at location @var{addr}. @item M@var{addr},@var{count}:@dots{} Write @var{count} bytes at location @var{addr}. +@need 500 @item c @itemx c@var{addr} Resume execution at the current address (or at @var{addr} if supplied). +@need 500 @item s @itemx s@var{addr} Step the target program for one instruction, from either the current @@ -409,7 +430,7 @@ If you have trouble with the serial connection, you can use the command back and forth across the serial line to the remote machine. The packet-debugging information is printed on the @value{GDBN} standard output stream. @code{set remotedebug off} turns it off, and @code{show -remotedebug} will show you its current state. +remotedebug} shows you its current state. @ifset GDBSERVER @node Server @@ -425,23 +446,28 @@ allows you to connect your program with a remote @value{GDBN} via because it requires essentially the same operating-system facilities that @value{GDBN} itself does. In fact, a system that can run @code{gdbserver} to connect to a remote @value{GDBN} could also run -@var{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, +@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, because it is a much smaller program than @value{GDBN} itself. It is -also easier to port than all of @var{GDBN}, so you may be able to get +also easier to port than all of @value{GDBN}, so you may be able to get started more quickly on a new system by using @code{gdbserver}. +Finally, if you develop code for real-time systems, you may find that +the tradeoffs involved in real-time operation make it more convenient to +do as much development work as possible on another system, for example +by cross-compiling. You can use @code{gdbserver} to make a similar +choice for debugging. @value{GDBN} and @code{gdbserver} communicate via either a serial line or a TCP connection, using the standard @value{GDBN} remote serial protocol. @table @emph -@item On the target, +@item On the target machine, you need to have a copy of the program you want to debug. @code{gdbserver} does not need your program's symbol table, so you can strip the program if necessary to save space. @value{GDBN} on the host system does all the symbol handling. -To use the server, you must tell it how to communicate with @value{GDB}; +To use the server, you must tell it how to communicate with @value{GDBN}; the name of your program; and the arguments for your program. The syntax is: @@ -450,7 +476,7 @@ target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] @end smallexample @var{comm} is either a device name (to use a serial line) or a TCP -hostname and portnumber. For example, to debug emacs with the argument +hostname and portnumber. For example, to debug Emacs with the argument @samp{foo.txt} and communicate with @value{GDBN} over the serial port @file{/dev/com1}: @@ -473,20 +499,22 @@ TCP. The @samp{host:2345} argument means that @code{gdbserver} is to expect a TCP connection from machine @samp{host} to local TCP port 2345. (Currently, the @samp{host} part is ignored.) You can choose any number you want for the port number as long as it does not conflict with any -TCP ports already in use on the target system.@footnote{If you choose a -port number that conflicts with another service, @code{gdbserver} prints -an error message and exits.} You must use the same port number with the -host @value{GDBN} @code{target remote} command. +TCP ports already in use on the target system (for example, @code{23} is +reserved for @code{telnet}).@footnote{If you choose a port number that +conflicts with another service, @code{gdbserver} prints an error message +and exits.} You must use the same port number with the host @value{GDBN} +@code{target remote} command. -@item On the host, -you need an unstripped copy of your program, since -@value{GDBN} needs symbols and debugging information. Start up -@value{GDBN} as usual, using the name of the local copy of your program -as the first argument. (You may also need the -@samp{--baud} option if the serial line is running at anything other than 9600 bps.) -After that, use @code{target remote} to establish communications with @code{gdbserver}. Its argument is either -a device name (usually a serial device, like @file{/dev/ttyb}), or a TCP -port descriptof in the form @code{@var{host}:@var{PORT}}. For example: +@item On the @value{GDBN} host machine, +you need an unstripped copy of your program, since @value{GDBN} needs +symbols and debugging information. Start up @value{GDBN} as usual, +using the name of the local copy of your program as the first argument. +(You may also need the @w{@samp{--baud}} option if the serial line is +running at anything other than 9600 bps.) After that, use @code{target +remote} to establish communications with @code{gdbserver}. Its argument +is either a device name (usually a serial device, like +@file{/dev/ttyb}), or a TCP port descriptor in the form +@code{@var{host}:@var{PORT}}. For example: @smallexample (@value{GDBP}) target remote /dev/ttyb @@ -500,7 +528,7 @@ communicates with the server via serial line @file{/dev/ttyb}, and @end smallexample @noindent -communicates via a TCP connection to port 2345 on host @file{the-target}. +communicates via a TCP connection to port 2345 on host @w{@file{the-target}}. For TCP connections, you must start up @code{gdbserver} prior to using the @code{target remote} command. Otherwise you may get an error whose text depends on the host system, but which usually looks something like @@ -617,7 +645,7 @@ a break is detected. @ifset AMD29K @node UDI29K Remote -@subsection @value{GDBN} and the UDI protocol for AMD29K +@subsection The UDI protocol for AMD29K @cindex UDI @cindex AMD29K via UDI @@ -640,7 +668,7 @@ to its pathname. @end table @node EB29K Remote -@subsection @value{GDBN} and the EBMON protocol for AMD29K +@subsection The EBMON protocol for AMD29K @cindex EB29K board @cindex running 29K programs @@ -760,7 +788,7 @@ Byte Write Available = Yes @end example Then exit the @code{cu} or @code{tip} program (done in the example by -typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} will keep +typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps running, ready for @value{GDBN} to take over. For this example, we've assumed what is probably the most convenient @@ -769,7 +797,7 @@ system: a PC/NFS connection that establishes ``drive @code{G:}'' on the PC as a file system on the Unix host. If you do not have PC/NFS or something similar connecting the two systems, you must arrange some other way---perhaps floppy-disk transfer---of getting the 29K program -from the Unix system to the PC; @value{GDBN} will @emph{not} download it over the +from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the serial line. @node gdb-EB29K @@ -784,6 +812,7 @@ cd /usr/joe/work29k @value{GDBP} myfoo @end example +@need 500 Now you can use the @code{target} command: @example @@ -849,7 +878,7 @@ concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}. The @code{load} and @code{attach} commands are @emph{not} defined for this target; you must load your program into the ST2000 as you normally -would for standalone operation. @value{GDBN} will read debugging information +would for standalone operation. @value{GDBN} reads debugging information (such as symbols) from a separate, debugging version of the program available on your host computer. @c FIXME!! This is terribly vague; what little content is here is @@ -871,7 +900,7 @@ manual for available commands. @cindex connect (to STDBUG) Connect the controlling terminal to the STDBUG command monitor. When you are done interacting with STDBUG, typing either of two character -sequences will get you back to the @value{GDBN} command prompt: +sequences gets you back to the @value{GDBN} command prompt: @kbd{@key{RET}~.} (Return, followed by tilde and period) or @kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D). @end table @@ -894,23 +923,21 @@ The following information on connecting to VxWorks was current when this manual was produced; newer releases of VxWorks may use revised procedures. -The remote debugging interface (RDB) routines are installed and executed -on the VxWorks target. These routines are included in the VxWorks library -@file{rdb.a} and are incorporated into the system image when source-level -debugging is enabled in the VxWorks configuration. - @kindex INCLUDE_RDB -If you wish, you can define @code{INCLUDE_RDB} in the VxWorks -configuration file @file{configAll.h} to include the RDB interface -routines and spawn the source debugging task @code{tRdbTask} when -VxWorks is booted. For more information on configuring and remaking -VxWorks, see the manufacturer's manual. +To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel +to include the remote debugging interface routines in the VxWorks +library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the +VxWorks configuration file @file{configAll.h} and rebuild your VxWorks +kernel. The resulting kernel contains @file{rdb.a}, and spawns the +source debugging task @code{tRdbTask} when VxWorks is booted. For more +information on configuring and remaking VxWorks, see the manufacturer's +manual. @c VxWorks, see the @cite{VxWorks Programmer's Guide}. -Once you have included the RDB interface in your VxWorks system image -and set your Unix execution search path to find @value{GDBN}, you are ready -to run @value{GDBN}. From your Unix host, run @code{gdb} (or -@code{vxgdb}, depending on your installation). +Once you have included @file{rdb.a} in your VxWorks system image and set +your Unix execution search path to find @value{GDBN}, you are ready to +run @value{GDBN}. From your Unix host, run @code{gdb} (or @code{vxgdb}, +depending on your installation). @value{GDBN} comes up showing the prompt: @@ -934,6 +961,7 @@ network. To connect to a target whose host name is ``@code{tt}'', type: (vxgdb) target vxworks tt @end example +@need 750 @value{GDBN} displays messages like these: @smallexample @@ -941,6 +969,7 @@ Attaching remote machine across net... Connected to tt. @end smallexample +@need 1000 @value{GDBN} then attempts to read the symbol tables of any object modules loaded into the VxWorks target since it was last booted. @value{GDBN} locates these files by searching the directories listed in the command search @@ -994,7 +1023,7 @@ Reading symbol data from wherever/vw/demo/rdb/prog.o... done. You can also use the @code{load} command to reload an object module after editing and recompiling the corresponding source file. Note that -this will cause @value{GDBN} to delete all currently-defined breakpoints, +this makes @value{GDBN} delete all currently-defined breakpoints, auto-displays, and convenience variables, and to clear the value history. (This is necessary in order to preserve the integrity of debugger data structures that reference the target system's symbol @@ -1013,33 +1042,44 @@ follows: @noindent where @var{task} is the VxWorks hexadecimal task ID. The task can be running -or suspended when you attach to it. If running, it will be suspended at +or suspended when you attach to it. Running tasks are suspended at the time of attachment. @end ifset @ifset H8 @node Hitachi Remote -@subsection @value{GDBN} and Hitachi Microprocessors +@subsection @value{GDBN} and Hitachi microprocessors @value{GDBN} needs to know these things to talk to your Hitachi SH, H8/300, or H8/500: @enumerate @item that you want to use @samp{target hms}, the remote debugging interface -for Hitachi microprocessors (this is the default when GDB is configured -specifically for the Hitachi SH, H8/300, or H8/500); +for Hitachi microprocessors, or @samp{target e7000}, the in-circuit +emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is +the default when GDB is configured specifically for the Hitachi SH, +H8/300, or H8/500.) @item what serial device connects your host to your Hitachi board (the first -serial device available on your host is the default); +serial device available on your host is the default). -@ignore -@c this is only for Unix hosts, not currently of interest. +@ifclear H8EXCLUSIVE +@c this is only for Unix hosts, not of interest to Hitachi @item what speed to use over the serial device. -@end ignore +@end ifclear @end enumerate +@menu +* Hitachi Boards:: Connecting to Hitachi boards. +* Hitachi ICE:: Using the E7000 In-Circuit Emulator. +* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros. +@end menu + +@node Hitachi Boards +@subsubsection Connecting to Hitachi boards + @ifclear H8EXCLUSIVE @c only for Unix hosts @kindex device @@ -1150,9 +1190,55 @@ normally. The communications protocol provides no other way for @value{GDBN} to detect program completion. @end itemize -In either case, @value{GDBN} will see the effect of a @sc{reset} on the +In either case, @value{GDBN} sees the effect of a @sc{reset} on the development board as a ``normal exit'' of your program. @end ifset + +@node Hitachi ICE +@subsubsection Using the E7000 in-circuit emulator + +@kindex target e7000 +You can use the E7000 in-circuit emulator to develop code for either the +Hitachi SH or the H8/300H. Use one of these forms of the @samp{target +e7000} command to connect @value{GDBN} to your E7000: + +@table @code +@item target e7000 @var{port} @var{speed} +Use this form if your E7000 is connected to a serial port. The +@var{port} argument identifies what serial port to use (for example, +@samp{com2}). The third argument is the line speed in bits per second +(for example, @samp{9600}). + +@item target e7000 @var{hostname} +If your E7000 is installed as a host on a TCP/IP network, you can just +specify its hostname; @value{GDBN} uses @code{telnet} to connect. +@end table + +@node Hitachi Special +@subsubsection Special @value{GDBN} commands for Hitachi micros + +Some @value{GDBN} commands are available only on the H8/300 or the +H8/500 configurations: + +@table @code +@kindex set machine +@kindex show machine +@item set machine h8300 +@itemx set machine h8300h +Condition @value{GDBN} for one of the two variants of the H8/300 +architecture with @samp{set machine}. You can use @samp{show machine} +to check which variant is currently in effect. + +@kindex set memory @var{mod} +@cindex memory models, H8/500 +@item set memory @var{mod} +@itemx show memory +Specify which H8/500 memory model (@var{mod}) you are using with +@samp{set memory}; check which memory model is in effect with @samp{show +memory}. The accepted values for @var{mod} are @code{small}, +@code{big}, @code{medium}, and @code{compact}. +@end table + @end ifset @ifset MIPS @@ -1164,6 +1250,11 @@ development board as a ``normal exit'' of your program. MIPS board attached to a serial line. This is available when you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. +@need 1000 +Use these @value{GDBN} commands to specify the connection to your target board: + +@table @code +@item target mips @var{port} @kindex target mips @var{port} To run a program on the board, start up @code{@value{GDBP}} with the name of your program as the argument. To connect to the board, use the @@ -1172,19 +1263,62 @@ the serial port connected to the board. If the program has not already been downloaded to the board, you may use the @code{load} command to download it. You can then use all the usual @value{GDBN} commands. -You can also specify @var{port} as a TCP connection (for instance, to a -serial line managed by a terminal concentrator), using the syntax -@code{@var{hostname}:@var{portnumber}}. +For example, this sequence connects to the target board through a serial +port, and loads and runs a program called @var{prog} through the +debugger: +@example +host$ @value{GDBP} @var{prog} +GDB is free software and @dots{} +(gdb) target mips /dev/ttyb +(gdb) load @var{prog} +(gdb) run +@end example + +@item target mips @var{hostname}:@var{portnumber} +On some @value{GDBN} host configurations, you can specify a TCP +connection (for instance, to a serial line managed by a terminal +concentrator) instead of a serial port, using the syntax +@samp{@var{hostname}:@var{portnumber}}. +@end table + +@noindent +@value{GDBN} also supports these special commands for MIPS targets: + +@table @code +@item set mipsfpu off +@itemx show mipsfpu +@kindex set mipsfpu off +@kindex show mipsfpu +@cindex MIPS remote floating point +@cindex floating point, MIPS remote +If your target board does not support the MIPS floating point +coprocessor, you should use the command @samp{set mipsfpu off} (if you +need this, you may wish to put the command in your @value{GDBINIT} +file). This tells @value{GDBN} how to find the return value of +functions which return floating point values. It also allows +@value{GDBN} to avoid saving the floating point registers when calling +functions on the board. (As usual, you can inquire about the +@code{mipsfpu} variable with @samp{show mipsfpu}.) + +@item set remotedebug @var{n} +@itemx show remotedebug +@kindex set remotedebug +@kindex show remotedebug @cindex @code{remotedebug}, MIPS protocol +@cindex MIPS @code{remotedebug} protocol @c FIXME! For this to be useful, you must know something about the MIPS @c FIXME...protocol. Where is it described? You can see some debugging information about communications with the board -by setting the @code{remotedebug} variable. If you set it to 1 using -@samp{set remotedebug 1} every packet will be displayed. If you set it -to 2 every character will be displayed. You can check the current value +by setting the @code{remotedebug} variable. If you set it to @code{1} using +@samp{set remotedebug 1}, every packet is displayed. If you set it +to @code{2}, every character is displayed. You can check the current value at any time with the command @samp{show remotedebug}. +@item set timeout @var{seconds} +@itemx set retransmit-timeout @var{seconds} +@itemx show timeout +@itemx show retransmit-timeout @cindex @code{timeout}, MIPS protocol @cindex @code{retransmit-timeout}, MIPS protocol @kindex set timeout @@ -1200,15 +1334,11 @@ You can inspect both values with @code{show timeout} and @code{show retransmit-timeout}. (These commands are @emph{only} available when @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.) -@kindex set mipsfpu off -@cindex MIPS remote floating point -@cindex floating point, MIPS remote -If your target board does not support the MIPS floating point -coprocessor, you should use the command @samp{set mipsfpu off} (you may -wish to put this in your @value{GDBINIT} file). This tells @value{GDBN} -how to find the return value of functions which return floating point -values. It also allows @value{GDBN} to avoid saving the floating point -registers when calling functions on the board. +The timeout set by @code{set timeout} does not apply when @value{GDBN} +is waiting for your program to stop. In that case, @value{GDBN} waits +forever because it has no way of knowing how long the program is going +to run before stopping. +@end table @end ifset @ifset SIMS @@ -1289,6 +1419,6 @@ Execution time in 60ths of a second. You can refer to these values in @value{GDBN} expressions with the usual conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a -conditional breakpoint that will suspend only after at least 5000 +conditional breakpoint that suspends only after at least 5000 simulated clock ticks. @end ifset diff --git a/gnu/usr.bin/gdb/doc/stabs.texinfo b/gnu/usr.bin/gdb/doc/stabs.texinfo index 23d8e7baa99..1c8d4071a41 100644 --- a/gnu/usr.bin/gdb/doc/stabs.texinfo +++ b/gnu/usr.bin/gdb/doc/stabs.texinfo @@ -6,7 +6,7 @@ @ifinfo @format START-INFO-DIR-ENTRY -* Stabs:: The "stabs" debugging information format. +* Stabs: (stabs). The "stabs" debugging information format. END-INFO-DIR-ENTRY @end format @end ifinfo @@ -43,7 +43,7 @@ regarded as a program in the language TeX). @page @tex \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 1.1.1.1 $} % For use in headers, footers too +\xdef\manvers{\$Revision: 2.120 $} % For use in headers, footers too {\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par @@ -84,7 +84,8 @@ This document describes the stabs debugging format. and GNU stabs in XCOFF * Sun Differences:: Differences between GNU stabs and Sun native stabs -* Stabs In ELF:: Stabs in an ELF file. +* Stab Sections:: In some object file formats, stabs are + in sections. * Symbol Types Index:: Index of symbolic stab symbol type names. @end menu @end ifinfo @@ -95,7 +96,7 @@ This document describes the stabs debugging format. @dfn{Stabs} refers to a format for information that describes a program to a debugger. This format was apparently invented by -@c FIXME! <> at +Peter Kessler at the University of California at Berkeley, for the @code{pdx} Pascal debugger; the format has spread widely since then. @@ -106,11 +107,14 @@ descriptors (@pxref{Type Descriptors}) are believed to be completely comprehensive. Stabs for COBOL-specific features and for variant records (used by Pascal and Modula-2) are poorly documented here. +@c FIXME: Need to document all OS9000 stuff in GDB; see all references +@c to os9k_stabs in stabsread.c. + Other sources of information on stabs are @cite{Dbx and Dbxtool Interfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files Reference}, Fourth Edition, September 1992, "dbx Stabstring Grammar" in the a.out section, page 2-31. This document is believed to incorporate -the information from those two sources except where it explictly directs +the information from those two sources except where it explicitly directs you to them for more information. @menu @@ -202,14 +206,14 @@ The overall format of the string field for most stab types is: "@var{name}:@var{symbol-descriptor} @var{type-information}" @end example -@var{name} is the name of the symbol represented by the stab. -@var{name} can be omitted, which means the stab represents an unnamed -object. For example, @samp{:t10=*2} defines type 10 as a pointer to -type 2, but does not give the type a name. Omitting the @var{name} -field is supported by AIX dbx and GDB after about version 4.8, but not -other debuggers. GCC sometimes uses a single space as the name instead -of omitting the name altogether; apparently that is supported by most -debuggers. +@var{name} is the name of the symbol represented by the stab; it can +contain a pair of colons (@pxref{Nested Symbols}). @var{name} can be +omitted, which means the stab represents an unnamed object. For +example, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does +not give the type a name. Omitting the @var{name} field is supported by +AIX dbx and GDB after about version 4.8, but not other debuggers. GCC +sometimes uses a single space as the name instead of omitting the name +altogether; apparently that is supported by most debuggers. The @var{symbol-descriptor} following the @samp{:} is an alphabetic character that tells more specifically what kind of symbol the stab @@ -226,7 +230,9 @@ reference, referring directly to a type that has already been defined. The @samp{@var{type-number}=} form is a type definition, where the number represents a new type which is about to be defined. The type definition may refer to other types by number, and those type numbers -may be followed by @samp{=} and nested definitions. +may be followed by @samp{=} and nested definitions. Also, the Lucid +compiler will repeat @samp{@var{type-number}=} more than once if it +wants to define several type numbers at once. In a type definition, if the character that follows the equals sign is non-numeric then it is a @var{type-descriptor}, and tells what kind of @@ -250,9 +256,6 @@ those from the C++ type descriptor @samp{@@}. The attributes are: @var{boundary} is an integer specifying the alignment. I assume it applies to all variables of this type. -@item s@var{size} -Size in bits of a variable of this type. - @item p@var{integer} Pointer class (for checking). Not sure what this means, or how @var{integer} is interpreted. @@ -261,19 +264,31 @@ Pointer class (for checking). Not sure what this means, or how Indicate this is a packed type, meaning that structure fields or array elements are placed more closely in memory, to save memory at the expense of speed. + +@item s@var{size} +Size in bits of a variable of this type. This is fully supported by GDB +4.11 and later. + +@item S +Indicate that this type is a string instead of an array of characters, +or a bitstring instead of a set. It doesn't change the layout of the +data being represented, but does enable the debugger to know which type +it is. @end table -All of this can make the string field quite long. All -versions of GDB, and some versions of dbx, can handle arbitrarily long -strings. But many versions of dbx cretinously limit the strings to -about 80 characters, so compilers which must work with such dbx's need -to split the @code{.stabs} directive into several @code{.stabs} -directives. Each stab duplicates exactly all but the -string field. The string field of -every stab except the last is marked as continued with a -double-backslash at the end. Removing the backslashes and concatenating -the string fields of each stab produces the original, -long string. +All of this can make the string field quite long. All versions of GDB, +and some versions of dbx, can handle arbitrarily long strings. But many +versions of dbx (or assemblers or linkers, I'm not sure which) +cretinously limit the strings to about 80 characters, so compilers which +must work with such systems need to split the @code{.stabs} directive +into several @code{.stabs} directives. Each stab duplicates every field +except the string field. The string field of every stab except the last +is marked as continued with a backslash at the end (in the assembly code +this may be written as a double backslash, depending on the assembler). +Removing the backslashes and concatenating the string fields of each +stab produces the original, long string. Just to be incompatible (or so +they don't have to worry about what the assembler does with +backslashes), AIX can use @samp{?} instead of backslash. @node C Example @section A Simple Example in C Source @@ -370,6 +385,7 @@ blocks of code. * Procedures:: * Nested Procedures:: * Block Structure:: +* Alternate Entry Points:: Entering procedures except at the beginning. @end menu @node Main Program @@ -472,10 +488,10 @@ file. @code{C_BINCL} and @code{C_EINCL} do not nest. @findex N_SLINE An @code{N_SLINE} symbol represents the start of a source line. The -desc field contains the line number and the value -contains the code address for the start of that source line. On most -machines the address is absolute; for Sun's stabs-in-ELF, it is relative -to the function in which the @code{N_SLINE} symbol occurs. +desc field contains the line number and the value contains the code +address for the start of that source line. On most machines the address +is absolute; for stabs in sections (@pxref{Stab Sections}), it is +relative to the function in which the @code{N_SLINE} symbol occurs. @findex N_DSLINE @findex N_BSLINE @@ -517,7 +533,7 @@ one has complained). A function is represented by an @samp{F} symbol descriptor for a global (extern) function, and @samp{f} for a static (local) function. The -value is the address of the start of the function. For @code{a.out}, it +value is the address of the start of the function. For a.out, it is already relocated. For stabs in ELF, the SunPRO compiler version 2.0.1 and GCC put out an address which gets relocated by the linker. In a future release SunPRO is planning to put out zero, in which case the @@ -526,8 +542,8 @@ things up in the ELF symbols would probably be slow, I'm not sure how to find which symbol of that name is the right one, and this doesn't provide any way to deal with nested functions, it would probably be better to make the value of the stab an address relative to the start of -the file. See @ref{Stabs In ELF} for more information on linker -relocation of stabs in ELF files. +the file, or just absolute. See @ref{ELF Linker Relocation} for more +information on linker relocation of stabs in ELF files. The type information of the stab represents the return type of the function; thus @samp{foo:f5} means that foo is a function returning type @@ -639,6 +655,11 @@ produces the stabs: @findex N_LBRAC @findex N_RBRAC +@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of +@c function relative (as documented below). But GDB has never been able +@c to deal with that (it had wanted them to be relative to the file, but +@c I just fixed that (between GDB 4.12 and 4.13)), so it is function +@c relative just like ELF and SOM and the below documentation. The program's block structure is represented by the @code{N_LBRAC} (left brace) and the @code{N_RBRAC} (right brace) stab types. The variables defined inside a block precede the @code{N_LBRAC} symbol for most @@ -648,8 +669,8 @@ RISC machine, and Sun @code{acc} compilers, put the variables after the @code{N_RBRAC} symbols are the start and end addresses of the code of the block, respectively. For most machines, they are relative to the starting address of this source file. For the Gould NP1, they are -absolute. For Sun's stabs-in-ELF, they are relative to the function in -which they occur. +absolute. For stabs in sections (@pxref{Stab Sections}), they are +relative to the function in which they occur. The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block scope of a procedure are located after the @code{N_FUN} stab that @@ -660,6 +681,19 @@ Sun documents the desc field of @code{N_LBRAC} and However, dbx seems to not care, and GCC always sets desc to zero. +@node Alternate Entry Points +@section Alternate Entry Points + +Some languages, like Fortran, have the ability to enter procedures at +some place other than the beginning. One can declare an alternate entry +point. The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN compiler +doesn't use it. According to AIX documentation, only the name of a +@code{C_ENTRY} stab is significant; the address of the alternate entry +point comes from the corresponding external symbol. A previous revision +of this document said that the value of an @code{N_ENTRY} stab was the +address of the alternate entry point, but I don't know the source for +that information. + @node Constants @chapter Constants @@ -822,6 +856,11 @@ from the external symbol for the global variable. In the example above, the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to produce an external symbol. +Some compilers, like GCC, output @code{N_GSYM} stabs only once, where +the variable is defined. Other compilers, like SunOS4 /bin/cc, output a +@code{N_GSYM} stab for each compilation unit which references the +variable. + @node Register Variables @section Register Variables @@ -884,7 +923,9 @@ type declarations using @code{C_DECL}) can also be between the Initialized static variables are represented by the @samp{S} and @samp{V} symbol descriptors. @samp{S} means file scope static, and -@samp{V} means procedure scope static. +@samp{V} means procedure scope static. One exception: in XCOFF, IBM's +xlc compiler always uses @samp{V}, and whether it is file scope or not +is distinguished by whether the stab is located within a function. @c This is probably not worth mentioning; it is only true on the sparc @c for `double' variables which although declared const are actually in @@ -920,8 +961,15 @@ yield the following stabs: .stabs "var_noinit:S1",40,0,0,_var_noinit # @r{40 is N_LCSYM} @end example -In XCOFF files, each symbol has a section number, so the stab type -need not indicate the section. +In XCOFF files, the stab type need not indicate the section; +@code{C_STSYM} can be used for all statics. Also, each static variable +is enclosed in a static block. A @code{C_BSTAT} (emitted with a +@samp{.bs} assembler directive) symbol begins the static block; its +value is the symbol number of the csect symbol whose value is the +address of the static block, its section is the section of the variables +in that static block, and its name is @samp{.bs}. A @code{C_ESTAT} +(emitted with a @samp{.es} assembler directive) symbol ends the static +block; its name is @samp{.es} and its value and section are ignored. In ECOFF files, the storage class is used to specify the section, so the stab type need not indicate the section. @@ -937,7 +985,7 @@ The clean way to do all this would be to have a the value of a symbol descriptor @samp{S} symbol be an offset relative to the start of the file, just like everything else, but that introduces obvious compatibility problems. For more information on linker stab relocation, -@xref{Stabs In ELF}. +@xref{ELF Linker Relocation}. @node Based Variables @section Fortran Based Variables @@ -1091,15 +1139,34 @@ happens when the argument was passed in a register and then the compiler stores it as a local variable. If possible, the compiler should claim that it's in a register, but this isn't always done. -@findex N_LSYM, for parameter -Some compilers use the pair of symbols approach described above -(@samp{@var{arg}:p} followed by @samp{@var{arg}:}); this includes GCC1 -(not GCC2) on the sparc when passing a small structure and GCC2 -(sometimes) when the argument type is @code{float} and it is passed as a -@code{double} and converted to @code{float} by the prologue (in the -latter case the type of the @samp{@var{arg}:p} symbol is @code{double} -and the type of the @samp{@var{arg}:} symbol is @code{float}). +If a parameter is passed as one type and converted to a smaller type by +the prologue (for example, the parameter is declared as a @code{float}, +but the calling conventions specify that it is passed as a +@code{double}), then GCC2 (sometimes) uses a pair of symbols. The first +symbol uses symbol descriptor @samp{p} and the type which is passed. +The second symbol has the type and location which the parameter actually +has after the prologue. For example, suppose the following C code +appears with no prototypes involved: +@example +void +subr (f) + float f; +@{ +@end example + +if @code{f} is passed as a double at stack offset 8, and the prologue +converts it to a float in register number 0, then the stabs look like: + +@example +.stabs "f:p13",160,0,3,8 # @r{160 is @code{N_PSYM}, here 13 is @code{double}} +.stabs "f:r12",64,0,3,0 # @r{64 is @code{N_RSYM}, here 12 is @code{float}} +@end example + +In both stabs 3 is the line number where @code{f} is declared +(@pxref{Line Numbers}). + +@findex N_LSYM, for parameter GCC, at least on the 960, has another solution to the same problem. It uses a single @samp{p} symbol descriptor for an argument which is stored as a local variable but uses @code{N_LSYM} instead of @code{N_PSYM}. In @@ -1503,9 +1570,9 @@ use a new negative type number. @code{integer}. 32 bit signed integral type. @item -16 -@code{boolean}. 32 bit type. How is the truth value encoded? Is it -the least significant bit or is it a question of whether the whole value -is zero or non-zero? +@code{boolean}. 32 bit type. GDB and GCC assume that zero is false, +one is true, and other values have unspecified meaning. I hope this +agrees with how the IBM tools use the type. @item -17 @code{short real}. IEEE single precision. @@ -1604,6 +1671,9 @@ Pascal set type. @var{type-information} must be a small type such as an enumeration or a subrange, and the type is a bitmask whose length is specified by the number of elements in @var{type-information}. +In CHILL, if it is a bitstring instead of a set, also use the @samp{S} +type attribute (@pxref{String Field}). + @item * @var{type-information} Pointer to @var{type-information}. @end table @@ -1618,6 +1688,10 @@ yet been defined. Another way is with the @samp{x} type descriptor, which is followed by @samp{s} for a structure tag, @samp{u} for a union tag, or @samp{e} for a enumerator tag, followed by the name of the tag, followed by @samp{:}. +If the name contains @samp{::} between a @samp{<} and @samp{>} pair (for +C++ templates), such a @samp{::} does not end the name---only a single +@samp{:} ends the name; see @ref{Nested Symbols}. + For example, the following C declarations: @example @@ -1798,6 +1872,10 @@ string. I don't know the difference. Pascal Stringptr. What is this? This is an AIX feature. @end table +Languages, such as CHILL which have a string type which is basically +just an array of characters use the @samp{S} type attribute +(@pxref{String Field}). + @node Enumerations @section Enumerations @@ -1829,13 +1907,29 @@ structure, enumeration, or union tag. The type descriptor @samp{e}, following the @samp{22=} of the type definition narrows it down to an enumeration type. Following the @samp{e} is a list of the elements of the enumeration. The format is @samp{@var{name}:@var{value},}. The -list of elements ends with @samp{;}. +list of elements ends with @samp{;}. The fact that @var{value} is +specified as an integer can cause problems if the value is large. GCC +2.5.2 tries to output it in octal in that case with a leading zero, +which is probably a good thing, although GDB 4.11 supports octal only in +cases where decimal is perfectly good. Negative decimal values are +supported by both GDB and dbx. There is no standard way to specify the size of an enumeration type; it is determined by the architecture (normally all enumerations types are -32 bits). There should be a way to specify an enumeration type of -another size; type attributes would be one way to do this. @xref{Stabs -Format}. +32 bits). Type attributes can be used to specify an enumeration type of +another size for debuggers which support them; see @ref{String Field}. + +Enumeration types are unusual in that they define symbols for the +enumeration values (@code{first}, @code{second}, and @code{third} in the +above example), and even though these symbols are visible in the file as +a whole (rather than being in a more local namespace like structure +member names), they are defined in the type definition for the +enumeration type rather than each having their own symbol. In order to +be fast, GDB will only get symbols from such types (in its initial scan +of the stabs) if the type is the first thing defined after a @samp{T} or +@samp{t} symbol descriptor (the above example fulfills this +requirement). If the type does not have a name, the compiler should +emit it in a nameless stab (@pxref{String Field}); GCC does this. @node Structures @section Structures @@ -1891,6 +1985,15 @@ The @code{s_next} field is a pointer to the same kind of structure that the field is an element of. So the definition of structure type 16 contains a type definition for an element which is a pointer to type 16. +If a field is a static member (this is a C++ feature in which a single +variable appears to be a field of every structure of a given type) it +still starts out with the field name, a colon, and the type, but then +instead of a comma, bit position, comma, and bit size, there is a colon +followed by the name of the variable which each such field refers to. + +If the structure has methods (a C++ feature), they follow the non-method +fields; see @ref{Cplusplus}. + @node Typedefs @section Giving a Type a Name @@ -2084,7 +2187,8 @@ relocatable address and the linker turns it into an absolute address. @menu * Transformations On Static Variables:: * Transformations On Global Variables:: -* ELF Transformations:: In ELF, things are a bit different. +* Stab Section Transformations:: For some object file formats, + things are a bit different. @end menu @node Transformations On Static Variables @@ -2160,16 +2264,17 @@ entry now holds an absolute address: 0000e008 D _g_foo @end example -@node ELF Transformations -@subsection Transformations of Stabs in ELF Files +@node Stab Section Transformations +@subsection Transformations of Stabs in separate sections -For ELF files, use @code{objdump --stabs} instead of @code{nm} to show -the stabs in an object or executable file. @code{objdump} is a GNU -utility; Sun does not provide any equivalent. +For object file formats using stabs in separate sections (@pxref{Stab +Sections}), use @code{objdump --stabs} instead of @code{nm} to show the +stabs in an object or executable file. @code{objdump} is a GNU utility; +Sun does not provide any equivalent. The following example is for a stab whose value is an address is -relative to the compilation unit (@pxref{Stabs In ELF}). For example, -if the source line +relative to the compilation unit (@pxref{ELF Linker Relocation}). For +example, if the source line @example static int ld = 5; @@ -2207,10 +2312,14 @@ Symnum n_type n_othr n_desc n_value n_strx String @chapter GNU C++ Stabs @menu +* Class Names:: C++ class names are both tags and typedefs. +* Nested Symbols:: C++ symbol names can be within other types. * Basic Cplusplus Types:: * Simple Classes:: * Class Instance:: * Methods:: Method definition +* Method Type Descriptor:: The @samp{#} type descriptor +* Member Type Descriptor:: The @samp{@@} type descriptor * Protections:: * Method Modifiers:: * Virtual Methods:: @@ -2219,24 +2328,53 @@ Symnum n_type n_othr n_desc n_value n_strx String * Static Members:: @end menu -Type descriptors added for C++ descriptions: +@node Class Names +@section C++ Class Names -@table @code -@item # -method type (@code{##} if minimal debug) +In C++, a class name which is declared with @code{class}, @code{struct}, +or @code{union}, is not only a tag, as in C, but also a type name. Thus +there should be stabs with both @samp{t} and @samp{T} symbol descriptors +(@pxref{Typedefs}). -@item @@ -Member (class and variable) type. It is followed by type information -for the offset basetype, a comma, and type information for the type of -the field being pointed to. (FIXME: this is acknowledged to be -gibberish. Can anyone say what really goes here?). +To save space, there is a special abbreviation for this case. If the +@samp{T} symbol descriptor is followed by @samp{t}, then the stab +defines both a type name and a tag. -Note that there is a conflict between this and type attributes -(@pxref{String Field}); both use type descriptor @samp{@@}. -Fortunately, the @samp{@@} type descriptor used in this C++ sense always -will be followed by a digit, @samp{(}, or @samp{-}, and type attributes -never start with those things. -@end table +For example, the C++ code + +@example +struct foo @{int x;@}; +@end example + +can be represented as either + +@example +.stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # @r{128 is N_LSYM} +.stabs "foo:t19",128,0,0,0 +@end example + +or + +@example +.stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 +@end example + +@node Nested Symbols +@section Defining a Symbol Within Another Type + +In C++, a symbol (such as a type name) can be defined within another type. +@c FIXME: Needs example. + +In stabs, this is sometimes represented by making the name of a symbol +which contains @samp{::}. Such a pair of colons does not end the name +of the symbol, the way a single colon would (@pxref{String Field}). I'm +not sure how consistently used or well thought out this mechanism is. +So that a pair of colons in this position always has this meaning, +@samp{:} cannot be used as a symbol descriptor. + +For example, if the string for a stab is @samp{foo::bar::baz:t5=*6}, +then @code{foo::bar::baz} is the name of the symbol, @samp{t} is the +symbol descriptor, and @samp{5=*6} is the type information. @node Basic Cplusplus Types @section Basic Types For C++ @@ -2333,12 +2471,11 @@ method. When the field name is a method name it is followed by two colons rather than one. This is followed by a new type definition for the method. -This is a number followed by an equal sign and the type descriptor -@samp{#}, indicating a method type, and a second @samp{#}, indicating -that this is the @dfn{minimal} type of method definition used by GCC2, -not larger method definitions used by earlier versions of GCC. This is -followed by a type reference showing the return type of the method and a -semi-colon. +This is a number followed by an equal sign and the type of the method. +Normally this will be a type declared using the @samp{#} type +descriptor; see @ref{Method Type Descriptor}; static member functions +are declared using the @samp{f} type descriptor instead; see +@ref{Function Types}. The format of an overloaded operator method name differs from that of other methods. It is @samp{op$::@var{operator-name}.} where @@ -2475,49 +2612,86 @@ pointer. << The examples that follow are based on A1.C >> +@node Method Type Descriptor +@section The @samp{#} Type Descriptor + +This is like the @samp{f} type descriptor for functions (@pxref{Function +Types}), except that a function which uses the @samp{#} type descriptor +takes an extra argument as its first argument, for the @code{this} +pointer. The @samp{#} type descriptor is optionally followed by the +types of the arguments, then another @samp{#}. If the types of the +arguments are omitted, so that the second @samp{#} immediately follows +the @samp{#} which is the type descriptor, the arguments are being +omitted (to save space) and can be deduced from the mangled name of the +method. After the second @samp{#} there is type information for the +return type of the method and a semicolon. + +Note that although such a type will normally be used to describe fields +in structures, unions, or classes, for at least some versions of the +compiler it can also be used in other contexts. + +@node Member Type Descriptor +@section The @samp{@@} Type Descriptor + +The @samp{@@} type descriptor is for a member (class and variable) type. +It is followed by type information for the offset basetype, a comma, and +type information for the type of the field being pointed to. (FIXME: +this is acknowledged to be gibberish. Can anyone say what really goes +here?). + +Note that there is a conflict between this and type attributes +(@pxref{String Field}); both use type descriptor @samp{@@}. +Fortunately, the @samp{@@} type descriptor used in this C++ sense always +will be followed by a digit, @samp{(}, or @samp{-}, and type attributes +never start with those things. + @node Protections @section Protections - In the simple class definition shown above all member data and functions were publicly accessable. The example that follows contrasts public, protected and privately accessable fields and shows how these protections are encoded in C++ stabs. -@c FIXME: What does "part of the string" mean? -Protections for class member data are signified by two characters -embedded in the stab defining the class type. These characters are -located after the name: part of the string. @samp{/0} means private, -@samp{/1} means protected, and @samp{/2} means public. If these -characters are omited this means that the member is public. The -following C++ source: +If the character following the @samp{@var{field-name}:} part of the +string is @samp{/}, then the next character is the visibility. @samp{0} +means private, @samp{1} means protected, and @samp{2} means public. +Debuggers should ignore visibility characters they do not recognize, and +assume a reasonable default (such as public) (GDB 4.11 does not, but +this should be fixed in the next GDB release). If no visibility is +specified the field is public. The visibility @samp{9} means that the +field has been optimized out and is public (there is no way to specify +an optimized out field with a private or protected visibility). +Visibility @samp{9} is not supported by GDB 4.11; this should be fixed +in the next GDB release. + +The following C++ source: @example -class all_data @{ +class vis @{ private: - int priv_dat; + int priv; protected: - char prot_dat; + char prot; public: - float pub_dat; + float pub; @}; @end example @noindent -generates the following stab to describe the class type all_data. +generates the following stab: -@display -.stabs "class_name:sym_desc(type)type_def(19)=type_desc(struct)struct_bytes - data_name:/protection(private)type_ref(int),bit_offset,num_bits; - data_name:/protection(protected)type_ref(char),bit_offset,num_bits; - data_name:(/num omited, private)type_ref(float),bit_offset,num_bits;;" - N_LSYM,NIL,NIL,NIL -@end display +@example +# @r{128 is N_LSYM} +.stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0 +@end example -@smallexample -.stabs "all_data:t19=s12 - priv_dat:/01,0,32;prot_dat:/12,32,8;pub_dat:12,64,32;;",128,0,0,0 -@end smallexample +@samp{vis:T19=s12} indicates that type number 19 is a 12 byte structure +named @code{vis} The @code{priv} field has public visibility +(@samp{/0}), type int (@samp{1}), and offset and size @samp{,0,32;}. +The @code{prot} field has protected visibility (@samp{/1}), type char +(@samp{2}) and offset and size @samp{,32,8;}. The @code{pub} field has +type float (@samp{12}), and offset and size @samp{,64,32;}. Protections for member functions are signified by one digit embeded in the field part of the stab describing the method. The digit is 0 if @@ -2696,14 +2870,21 @@ This additional information is embeded in the class stab following the number of bytes in the struct. First the number of base classes appears bracketed by an exclamation point and a comma. -Then for each base type there repeats a series: two digits, a number, -a comma, another number, and a semi-colon. +Then for each base type there repeats a series: a virtual character, a +visibilty character, a number, a comma, another number, and a +semi-colon. -The first of the two digits is 1 if the base class is virtual and 0 if -not. The second digit is 2 if the derivation is public and 0 if not. +The virtual character is @samp{1} if the base class is virtual and +@samp{0} if not. The visibility character is @samp{2} if the derivation +is public, @samp{1} if it is protected, and @samp{0} if it is private. +Debuggers should ignore virtual or visibility characters they do not +recognize, and assume a reasonable default (such as public and +non-virtual) (GDB 4.11 does not, but this should be fixed in the next +GDB release). -The number following the first two digits is the offset from the start -of the object to the part of the object pertaining to the base class. +The number following the virtual and visibility characters is the offset +from the start of the object to the part of the object pertaining to the +base class. After the comma, the second number is a type_descriptor for the base type. Finally a semi-colon ends the series, which repeats for each @@ -2847,9 +3028,10 @@ description in the class stab shows this ordering. @appendix Table of Stab Types The following are all the possible values for the stab type field, for -@code{a.out} files, in numeric order. This does not apply to XCOFF, but -it does apply to stabs in ELF. Stabs in ECOFF use these values but add -0x8f300 to distinguish them from non-stab symbols. +a.out files, in numeric order. This does not apply to XCOFF, but +it does apply to stabs in sections (@pxref{Stab Sections}). Stabs in +ECOFF use these values but add 0x8f300 to distinguish them from non-stab +symbols. The symbolic names are defined in the file @file{include/aout/stabs.def}. @@ -2909,18 +3091,23 @@ Symbol is indirected to another symbol Common---visible after shared library dynamic link @item 0x14 N_SETA +@itemx 0x15 N_SETA | N_EXT Absolute set element @item 0x16 N_SETT +@itemx 0x17 N_SETT | N_EXT Text segment set element @item 0x18 N_SETD +@itemx 0x19 N_SETD | N_EXT Data segment set element @item 0x1a N_SETB +@itemx 0x1b N_SETB | N_EXT BSS segment set element @item 0x1c N_SETV +@itemx 0x1d N_SETV | N_EXT Pointer to set vector @item 0x1e N_WARNING @@ -3036,7 +3223,7 @@ Parameter variable; see @ref{Parameters}. End of an include file; see @ref{Include Files}. @item 0xa4 N_ENTRY -Alternate entry point; see @ref{N_ENTRY}. +Alternate entry point; see @ref{Alternate Entry Points}. @item 0xc0 N_LBRAC Beginning of a lexical block; see @ref{Block Structure}. @@ -3102,6 +3289,9 @@ for more information about their use. @itemx - Variable on the stack; see @ref{Stack Variables}. +@item : +C++ nested symbol; see @xref{Nested Symbols} + @item a Parameter passed by reference in register; see @ref{Reference Parameters}. @@ -3176,6 +3366,9 @@ Register variable; see @ref{Register Variables}. @item S File scope variable; see @ref{Statics}. +@item s +Local variable (OS9000). + @item t Type name; see @ref{Typedefs}. @@ -3211,7 +3404,7 @@ Type reference; see @ref{String Field}. Reference to builtin type; see @ref{Negative Type Numbers}. @item # -Method (C++); see @ref{Cplusplus}. +Method (C++); see @ref{Method Type Descriptor}. @item * Pointer; see @ref{Miscellaneous Types}. @@ -3221,7 +3414,7 @@ Reference (C++). @item @@ Type Attributes (AIX); see @ref{String Field}. Member (class and variable) -type (GNU C++); see @ref{Cplusplus}. +type (GNU C++); see @ref{Member Type Descriptor}. @item a Array; see @ref{Arrays}. @@ -3231,13 +3424,15 @@ Open array; see @ref{Arrays}. @item b Pascal space type (AIX); see @ref{Miscellaneous Types}. Builtin integer -type (Sun); see @ref{Builtin Type Descriptors}. +type (Sun); see @ref{Builtin Type Descriptors}. Const and volatile +qualfied type (OS9000). @item B Volatile-qualified type; see @ref{Miscellaneous Types}. @item c -Complex builtin type; see @ref{Builtin Type Descriptors}. +Complex builtin type (AIX); see @ref{Builtin Type Descriptors}. +Const-qualified type (OS9000). @item C COBOL Picture type. See AIX documentation for details. @@ -3267,7 +3462,8 @@ Builtin floating point type; see @ref{Builtin Type Descriptors}. COBOL Group. See AIX documentation for details. @item i -Imported type; see @ref{Cross-References}. +Imported type (AIX); see @ref{Cross-References}. Volatile-qualified +type (OS9000). @item k Const-qualified type; see @ref{Miscellaneous Types}. @@ -3322,6 +3518,9 @@ Wide character; see @ref{Builtin Type Descriptors}. @item x Cross-reference; see @ref{Cross-References}. +@item Y +Used by IBM's xlC C++ compiler (for structures, I think). + @item z gstring; see @ref{Strings}. @end table @@ -3347,7 +3546,7 @@ The third line is the stab format with the significant stab fields named and the rest NIL. Subsequent lines expand upon the meaning and possible values for each -significant stab field. @samp{#} stands in for the type descriptor. +significant stab field. Finally, any further information. @@ -3362,7 +3561,6 @@ Finally, any further information. * N_MOD2:: Modula2 information "for imc" * N_CATCH:: GNU C++ "catch" clause * N_SSYM:: Structure or union element -* N_ENTRY:: Alternate entry point * N_SCOPE:: Modula2 scope information (Sun only) * Gould:: non-base register symbols used on Gould systems * N_LENG:: Length of preceding entry @@ -3426,6 +3624,10 @@ desc -> unit_number value -> 0 (main unit) 1 (any other unit) @end example + +See @cite{Dbx and Dbxtool Interfaces}, 2nd edition, by Sun, 1988, for +more information. + @end deffn @node N_BROWS @@ -3502,16 +3704,6 @@ The value is the offset in the structure. <> @end deffn -@node N_ENTRY -@section N_ENTRY - -@deffn @code{.stabn} N_ENTRY -@findex N_ENTRY -Alternate entry point. -The value is its address. -<> -@end deffn - @node N_SCOPE @section N_SCOPE @@ -3628,15 +3820,6 @@ the mapping is @code{N_@var{stabtype}} becomes @code{C_@var{stabtype}}. Some stab types in a.out are not supported in XCOFF; most of these use @code{C_DECL}. -@c FIXME: Get C_* types for the block, figure out whether it is always -@c used (I suspect not), explain clearly, and move to node Statics. -Exception: initialised static @code{N_STSYM} and un-initialized static -@code{N_LCSYM} both map to the @code{C_STSYM} storage class. But the -distinction is preserved because in XCOFF @code{N_STSYM} and -@code{N_LCSYM} must be emited in a named static block. Begin the block -with @samp{.bs s[RW] data_section_name} for @code{N_STSYM} or @samp{.bs -s bss_section_name} for @code{N_LCSYM}. End the block with @samp{.es}. - @c FIXME: I think they are trying to say something about whether the @c assembler defaults the value to the location counter. @item @@ -3708,18 +3891,36 @@ incremented for each new type defined in the compilation. GNU C stabs use the type number alone, with no source file number. @end itemize -@node Stabs In ELF -@appendix Using Stabs With The ELF Object File Format +@node Stab Sections +@appendix Using Stabs in Their Own Sections -The ELF object file format allows tools to create object files with -custom sections containing any arbitrary data. To use stabs in ELF -object files, the tools create two custom sections, a section named -@code{.stab} which contains an array of fixed length structures, one -struct per stab, and a section named @code{.stabstr} containing all the -variable length strings that are referenced by stabs in the @code{.stab} -section. The byte order of the stabs binary data matches the byte order -of the ELF file itself, as determined from the @code{EI_DATA} field in -the @code{e_ident} member of the ELF header. +Many object file formats allow tools to create object files with custom +sections containing any arbitrary data. For any such object file +format, stabs can be embedded in special sections. This is how stabs +are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs +are used with COFF. + +@menu +* Stab Section Basics:: How to embed stabs in sections +* ELF Linker Relocation:: Sun ELF hacks +@end menu + +@node Stab Section Basics +@appendixsec How to Embed Stabs in Sections + +The assembler creates two custom sections, a section named @code{.stab} +which contains an array of fixed length structures, one struct per stab, +and a section named @code{.stabstr} containing all the variable length +strings that are referenced by stabs in the @code{.stab} section. The +byte order of the stabs binary data depends on the object file format. +For ELF, it matches the byte order of the ELF file itself, as determined +from the @code{EI_DATA} field in the @code{e_ident} member of the ELF +header. For SOM, it is always big-endian (is this true??? FIXME). For +COFF, it matches the byte order of the COFF headers. The meaning of the +fields is the same as for a.out (@pxref{Symbol Table Format}), except +that the @code{n_strx} field is relative to the strings for the current +compilation unit (which can be found using the synthetic N_UNDF stab +described below), rather than the entire string table. The first stab in the @code{.stab} section for each compilation unit is synthetic, generated entirely by the assembler, with no corresponding @@ -3735,6 +3936,8 @@ Offset in the @code{.stabstr} section to the source filename. @item n_other Unused field, always zero. +This may eventually be used to hold overflows from the count in +the @code{n_desc} field. @item n_desc Count of upcoming symbols, i.e., the number of remaining stabs for this @@ -3753,38 +3956,75 @@ The ELF section header for the @code{.stab} section has its @code{sh_link} member set to the section number of the @code{.stabstr} section, and the @code{.stabstr} section has its ELF section header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a -string table. +string table. SOM and COFF have no way of linking the sections together +or marking them as string tables. -To keep linking fast, it is a bad idea to have the linker relocating -stabs, so (except for a few cases, see below) none of the addresses in -the @code{n_value} field of the stabs are relocated by the linker. -Instead they are relative to the source file (or some entity smaller -than a source file, like a function). To find the address of each -section corresponding to a given source file, the compiler puts out -symbols giving the address of each section for a given source file. -Since these are ELF (not stab) symbols, the linker relocates them -correctly without having to touch the stabs section. They are named -@code{Bbss.bss} for the bss section, @code{Ddata.data} for the data -section, and @code{Drodata.rodata} for the rodata section. For the text -section, there is no such symbol (but there should be, see below). For -an example of how these symbols work, @xref{ELF Transformations}. GCC -does not provide these symbols; it instead relies on the stabs getting -relocated, which slows down linking. Thus addresses which would -normally be relative to @code{Bbss.bss}, etc., are already relocated. -The Sun linker provided with Solaris 2.2 and earlier relocates stabs -using normal ELF relocation information, as it would do for any section. -Sun has been threatening to kludge their linker to not do this (to speed -up linking), even though the correct way to avoid having the linker do -these relocations is to have the compiler no longer output relocatable -values. Last I heard they had been talked out of the linker kludge. -See Sun point patch 101052-01 and Sun bug 1142109. This affects -@samp{S} symbol descriptor stabs (@pxref{Statics}) and functions -(@pxref{Procedures}). In the latter case, to adopt the clean solution -(making the value of the stab relative to the start of the compilation -unit), it would be necessary to invent a @code{Ttext.text} symbol, -analogous to the @code{Bbss.bss}, etc., symbols. I recommend this -rather than using a zero value and getting the address from the ELF -symbols. +For COFF, the @code{.stab} and @code{.stabstr} sections are simply +concatenated by the linker. GDB then uses the @code{n_desc} fields to +figure out the extent of the original sections. Similarly, the +@code{n_value} fields of the header symbols are added together in order +to get the actual position of the strings in a desired @code{.stabstr} +section. Although this design obviates any need for the linker to relocate +or otherwise manipulate @code{.stab} and @code{.stabstr} sections, it also +requires some care to ensure that the offsets are calculated correctly. +For instance, if the linker were to pad in between the @code{.stabstr} +sections before concatenating, then the offsets to strings in the middle +of the executable's @code{.stabstr} section would be wrong. + +@node ELF Linker Relocation +@appendixsec Having the Linker Relocate Stabs in ELF + +This section describes some Sun hacks for Stabs in ELF; it does not +apply to COFF or SOM. + +To keep linking fast, you don't want the linker to have to relocate very +many stabs. Making sure this is done for @code{N_SLINE}, +@code{N_RBRAC}, and @code{N_LBRAC} stabs is the most important thing +(see the descriptions of those stabs for more information). But Sun's +stabs in ELF has taken this further, to make all addresses in the +@code{n_value} field (functions and static variables) relative to the +source file. For the @code{N_SO} symbol itself, Sun simply omits the +address. To find the address of each section corresponding to a given +source file, the compiler puts out symbols giving the address of each +section for a given source file. Since these are ELF (not stab) +symbols, the linker relocates them correctly without having to touch the +stabs section. They are named @code{Bbss.bss} for the bss section, +@code{Ddata.data} for the data section, and @code{Drodata.rodata} for +the rodata section. For the text section, there is no such symbol (but +there should be, see below). For an example of how these symbols work, +@xref{Stab Section Transformations}. GCC does not provide these symbols; +it instead relies on the stabs getting relocated. Thus addresses which +would normally be relative to @code{Bbss.bss}, etc., are already +relocated. The Sun linker provided with Solaris 2.2 and earlier +relocates stabs using normal ELF relocation information, as it would do +for any section. Sun has been threatening to kludge their linker to not +do this (to speed up linking), even though the correct way to avoid +having the linker do these relocations is to have the compiler no longer +output relocatable values. Last I heard they had been talked out of the +linker kludge. See Sun point patch 101052-01 and Sun bug 1142109. With +the Sun compiler this affects @samp{S} symbol descriptor stabs +(@pxref{Statics}) and functions (@pxref{Procedures}). In the latter +case, to adopt the clean solution (making the value of the stab relative +to the start of the compilation unit), it would be necessary to invent a +@code{Ttext.text} symbol, analogous to the @code{Bbss.bss}, etc., +symbols. I recommend this rather than using a zero value and getting +the address from the ELF symbols. + +Finding the correct @code{Bbss.bss}, etc., symbol is difficult, because +the linker simply concatenates the @code{.stab} sections from each +@file{.o} file without including any information about which part of a +@code{.stab} section comes from which @file{.o} file. The way GDB does +this is to look for an ELF @code{STT_FILE} symbol which has the same +name as the last component of the file name from the @code{N_SO} symbol +in the stabs (for example, if the file name is @file{../../gdb/main.c}, +it looks for an ELF @code{STT_FILE} symbol named @code{main.c}). This +loses if different files have the same name (they could be in different +directories, a library could have been copied from one system to +another, etc.). It would be much cleaner to have the @code{Bbss.bss} +symbols in the stabs themselves. Having the linker relocate them there +is no more work than having the linker relocate ELF symbols, and it +solves the problem of having to associate the ELF and stab symbols. +However, no one has yet designed or implemented such a scheme. @node Symbol Types Index @unnumbered Symbol Types Index