talexander
/
freebsd_amp_hwpstate
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Install infopages

This commit is contained in:
Andrey A. Chernov 1995-01-11 16:29:45 +00:00
parent dc16046f96
commit eb9747a649
8 changed files with 2290 additions and 1051 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
gnu/usr.bin/gdb/doc/GDBvn.texi Normal file
View File

@ -0,0 +1 @@
@set GDBVN 4.13

342
gnu/usr.bin/gdb/doc/Makefile
View File

@ -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 <bsd.info.mk>

708
gnu/usr.bin/gdb/doc/annotate.texi Normal file
View File

@ -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

952
gnu/usr.bin/gdb/doc/gdb.texinfo
View File

File diff suppressed because it is too large Load Diff

289
gnu/usr.bin/gdb/doc/gdbint.texinfo
View File

@ -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 <setjmp.h> 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 <setjmp.h> 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

155
gnu/usr.bin/gdb/doc/inc-hist.texi Normal file
View File

@ -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

280
gnu/usr.bin/gdb/doc/remote.texi
View File

@ -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

614
gnu/usr.bin/gdb/doc/stabs.texinfo
View File

@ -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! <<name of inventor>> 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.
<<?looking at structs and unions in C I didn't see these>>
@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