gnu1987/gdb/sun-dbx.doc

.ds + \v'-0.06i'+\v'0.06i'
.de PR
.sp 1
.in +1.5i
.ti -0.8i
.nh
\s-2\fL\\$1  \s+2\(->\s-2  \\$2\fR\s+2
.hy
.in -1.5i
..
.de PC
.in +1.5i
.ti -0.8i
.nh
.sp 0.05i
\s-2\fL\\$1  \s+2\(->\s-2  \\$2\fR\s+2
.hy
.in -1.5i
..
.OF 'Sun Microsystems'8 Apr 86'Programming Languages Group'
.EF 'Sun Microsystems'8 Apr 86'Programming Languages Group'
.ps 12
.nr PS 12
.vs 14p
.nr VS 14p
.ce
\fB\s20Dbx and Dbxtool Interfaces\s0\fR
.sp 1
.ce
Steven S. Muchnick
.sp 1
.ce
\fI8 April 1986\fR
.sp 2
.NH 1
Introduction and Assumptions
.PP
This document specifies two interfaces, one between Sun's compilers and
the \fIdbx\fR and \fIdbxtool\fR debuggers and the other between the two
processes which make up \fIdbxtool\fR.
The information is current as of the 3.0 Sun Software Release and the
1.0 release of Sun Modula-2 and is intended for compiler implementors.
.PP
The interface languages are expected to grow and evolve over time.
While they may be extended at arbitrary times and bugs fixed in them as needed,
major changes which introduce incompatibilities with previous versions
will generally be synchronized with major system releases.
.PP
This document assumes the reader is familiar with the Sun assembler and linker,
and with \fIdbx\fR and \fIdbxtool\fR.
.PP
.sp 1
.NH 1
\fIDbx\fB and \fIDbxtool\fR
.PP
\fIDbxtool\fR consists of two processes, the debugger process (DP), which is
identical to \fIdbx\fR, and the user interface process (UIP).
When the UIP starts the DP it passes a flag to it telling it that it was
started by the UIP, rather than directly by the user.
Commands are communicated from the UIP to the DP in the same form that they
are typed by the user to \fIdbx\fR, as character strings consisting of the
command name followed by the arguments, and are presented to it via its
standard input.
Commands entered via the mouse are translated by the UIP into the standard
form:  the command button provides the command name to be placed at the
beginning of the string and the selected argument is translated according
to the selection interpretation associated with the command button.
The DP communicates to the UIP in the DP-UIP interface language,
instead of the usual tty-oriented responses used by the DP when it is
invoked directly as \fIdbx\fR.
.PP
The next section presents the syntax and semantics of the language which
compilers use to convey information about data types, variables and the
relationship between source statements and machine instructions to the DP
(or, equivalently, to \fIdbx\fR).
The following section presents the syntax and semantics of the interface
between the DP and the UIP.
Appendix A lists the standard types defined for Sun's supported languages.
Appendix B gives an example of the compiler-debugger interface.
.PP
.sp 1
.NH 1
Overview of the Compiler-Debugger Interface Language
.PP
All information about a compiled module needed by \fIdbx\fR and \fIdbxtool\fR
is contained in the symbol table part of the \fIa.out\fR file.
Some of this information is derived from ordinary linker and assembler
symbols; the rest is passed by the compilers to the assembler via \fL.stab\fR
("symbol table") directives.
The debuggers distinguish the two types of symbols by whether or not any of
the \fLN_STAB\fR* bits are set in the type field of the symbol entry, as
described below in Section 3.31.
.FS
*Symbols beginning with \fLN_\fR are defined in the files
\fL/usr/include/a.out.h\fR and \fL/usr/include/stab.h\fR.
.FE
.PP
The \fL.stab\fR directives have the following forms:
.sp 1
.in +1.0i
\fL .stabs    "\fIname\fR",\fItype\fR,0,\fIdesc\fR,\fIvalue\fR
.sp 1
\fL .stabn    \fItype\fR,0,\fIdesc\fR,\fIvalue\fR
.in -1.0i
.sp 0.6
or
.sp 0.6
.in +1.0i
\fL .stabd    \fItype\fR,0,\fIdesc\fR
.in -1.0i
.sp 1
.LP
The \fL.stabs\fR directives are used to describe types, variables,
procedures, and so on, while the \fL.stabn\fR directives convey
information about scopes and the mapping from source statements to
object code.
A \fL.stabd\fR directive is identical in meaning to a
corresponding \fL.stabn\fR directive with the value field set to "." (dot),
which the assembler uses to mean the current location.
Most of the needed information, for example symbol name and type structure,
is contained in the \fIname\fR field.
The \fItype\fR field identifies the type of symbolic information, for
example source file, global symbol, or source line.
The \fIdesc\fR field specifies the number of bytes occupied by a variable or
type or the nesting level for a scope symbol.
The \fIvalue\fR field specifies an address or an offset.
.PP
The following classes of \fL.stab\fR information are needed to describe
a compiled module or file, with of course considerable variations
depending on the source language:
.IP -
file and module identification and (for Modula-2) the list of imported
separate units
.IP -
program structure information and descriptions of types, variables and scopes
.IP -
code address information for statements
.PP
The \fL.stab\fR directives may be interspersed in the generated assembly
language with relatively few constraints on their ordering.
In particular, the \fLN_SLINE .stabd\fR or \fL.stabn\fR directives which
describe the relationship between the source and object code need to
appear in the same order as the corresponding source lines and
the \fL.stabs\fR directives which describe variables need to be ordered
to correspond to the scope structure of the program.
.PP
The name field in a \fL.stabs\fR entry for a symbol contains the
symbol's name, followed by a colon, a one-character symbol
descriptor, and descriptor-specific information, i.e.
.sp 1
.in +1.0i
\fLsymbol : descriptor debuginfo\fR
.in -1.0i
.sp 0.5
.PP
The linker and assembler symbols and \fL.stab\fR directives expected by
the debuggers and their meanings are described below.
.PP
.sp 1
.NH 2
Syntax Notation
.PP
In the syntax notation used below nonterminal symbols are those in
\fLtypewriter font\fR which are more than one character long and begin with
a capital letter.
The left and right sides of a production are separated by an arrow
"\fL\(->\fR".
Braces "\fL{\fR" and "\fL}\fR" are used to indicate grouping, brackets
"\fL[\fR" and "\fL]\fR"  to indicate optionality, vertical bar "\fL|\fR" for
alternation, asterisk "\fL*\fR" for zero or more repetitions, and plus
"\fL\*+\fR" for one or more repetitions.
All other symbols in \fLtypewriter font\fR which are not part of the notation
denote terminals.
.PP
.sp 1
.NH 2
Lexical Rules
.PP
Lexically \fL.stab\fR directives follow the conventions of ordinary
assembly language lines.
The string in a \fL.stabs\fR directive may be continued from one line to the
next by terminating it with a backslash '\\', completing the other fields
of the directive, and continuing the string in another \fL.stabs\fR
directive on the next line with the same non-string fileds.
Thus, for example,
.in +1.0i
.nf
 \fL\s-2.stabs    "int:t(0,1)=r(0,1);-2147483648;\\",0x80,0,0,0
 .stabs    "2147483647;",0x80,0,0,0\s+2\fR
.fi
.in -1.0i
.LP
and
.in +1.0i
.nf
 \fL\s-2.stabs    "int:t(0,1)=r(0,1);-2147483648;2147483647;",0x80,0,0,0\s+2\fR
.fi
.in -1.0i
.LP
are equivalent.
There may be any number of such continuation lines.
.PP
.sp 1
.NH 2
Linker and Assembler Symbols
.PP
The linker and assembler symbols used by the debuggers are those which
identify object files, procedures, and variables.
These symbols are generated either by the linker (object filenames) or by
the assembler (procedure names and variables) without the compiler having
to supply \fL.stab\fR directives for them.
.PP
Symbols in text space whose names end in "\fL.o\fR" are taken as object
filenames.
The debugger strips off the "\fL.o\fR" and any leading directory names.
The resulting filename becomes associated with following symbols as the
file which contains them, until another object filename or the end of file
is seen.
Text-space symbols other than object filenames are taken by the debugger
as names of procedures.
If the symbol has a leading underscore, it is removed.
If a debugger symbol entry is later encountered for the same symbol, the
assembler symbol is discarded in its favor.
.PP
Data- and bss-space symbols are taken by the debugger as representing
global variables in the corresponding spaces.
Leading underscores are stripped off and the scope information is preserved.
A debugger symbol is also required for such symbols to provide full information
for them (see Section 3.13).
.PP
.sp 1
.NH 2
Top-Level Structure of Debugger Symbols
.PP
.PR DebuggerStabs "{CodeStabs | SourceFileStabs | UnitStab | ProcStab | ScopeBgnStab StructureStabs* ScopeEndStab | TypeStab | GlblVarStab | StaticVarStab | LclVarStab | ParamStab | CommonStabs | ImpExpStab}*"
.PP
.NH 2
Source-to-Object Code Mapping
.PP
.PR CodeStabs "{BlockBgnStab LineStab* BlockEndStab}*"
.PC BlockBgnStab ".stabn N_LBRAC , 0 , Level , CodeAddr"
.PC N_LBRAC 0xc0
.PC LineStab ".stabn N_SLINE , 0 , Line , CodeAddr"
.PC N_SLINE 0x44
.PC BlockEndStab ".stabn N_RBRAC , 0 , Level , CodeAddr"
.PC N_RBRAC 0xe0
.PP
\fLCodeStabs\fR define the relationship between the source code and the
object code.
The object code generated for each block (e.g. a group of statements
delimited by curly braces in C or by \fLbegin\fR and \fLend\fR in Pascal)
is enclosed in \fLBlockBgnStab\fR and \fLBlockEndStab\fR directives.
A \fLLineStab\fR is given for the first instruction generated for
each statement.
\fLLevel\fR identifies the static nesting level of a block, \fLLine\fR
gives the source line number for a statement and \fLCodeAddr\fR
gives the relocatable address of the corresponding object code.
.PP
.NH 2
Source File Identification
.PP
.PR SourceFileStab ".stabs "" SourceFileString "" , N_SO , 0 , 0 , CodeAddr"
.PC SourceFileString String
.PC N_SO 0x64
.PP
A \fLSourceFileStab\fR identifies the source file which was compiled to
produce this object code.
The \fLSourceFileString\fR is the name of the source file in the form it was
given to the compiler.
The \fLCodeAddr\fR gives the relocatable address of the beginning of the
generated object code.
.PP
.NH 2
Unit Identification (Modula-2 only)
.PP
.PR UnitStab ".stabs "" UnitString "" , N_M2C , 0 , UnitNumber , UnitFlag"
.PC UnitString "Name , UnitTimeStamp [, CodeTimeStamp]"
.PC N_M2C 0x42
.PC UnitNumber Number
.PC UnitTimeStamp String
.PC CodeTimeStamp String
.PC UnitFlag "0 | 1"
.PP
A \fLUnitStab\fR provides some debugging information, in addition to
identifying a Modula-2 separate compilation unit for version consistency
checking in the Modula-2 linker \fIm2l\fR .
The \fLName\fR field defines the the name of the module to the
debugger.
The \fLUnitNumber\fR field is used to identify the modules of imported
and exported identifiers (see Section 3.12).
The \fLUnitTimeStamp\fR is used internally in the debugger to provide
unique entries in its module table.
The \fLUnitFlag\fR field is used only to identify the main module
(its \fLUnitFlag\fR is \fL0\fR).
The \fLCodeTimeStamp\fR field is used only for consistency checking.
.PP
.NH 2
Functions and Procedures (C, FORTRAN and Pascal)
.PP
.PR ProcStab ".stabs "" ProcName : ProcClass ProcRtnType "" , N_FUN , 0 , RtnSize , CodeAddr"
.PC ProcClass "F | f"
.PC ProcRtnType TypeRef
.PC N_FUN 0x24
.PP
A \fLProcStab\fR defines the beginning of a C, FORTRAN or Pascal function or
procedure.
It gives the routine's name and storage class, the type and size of the value
it returns, and the address of the beginning of its code.
The class is \fLF\fR for globally defined routines and \fLf\fR for local ones.
For procedures, the return type is \fLvoid\fR.
.PP
.NH 2
Module, Function and Procedure Scopes (Modula-2 only)
.PP
.PR ScopeBgnStab ".stabs "" ScopeBgnString "" , N_SCOPE , 0 , Level , CodeAddr"
.PC ScopeEndStab ".stabs "" ScopeEndString "" , N_SCOPE , 0 , Level , 0"
.PC ScopeBgnString "Name : ScopeId"
.PC ScopeId "M ScopeNumber | Q ScopeNumber ResultType"
.PC ResultType TypeRef
.PC ScopeEndString "Name : E ScopeNumber"
.PC N_SCOPE 0xc4
.PC ScopeNumber Number
.PP
A \fLScopeBgnStab\fR - \fLScopeEndStab\fR pair delimits a module, procedure or
function scope in Modula-2.
The \fLScopeBgnString\fR gives the name of the scope and a \fLScopeId\fR
which identifies it as a module (\fLM\fR) or a function or procedure
(\fLQ\fR) and gives the sequence number (\fLScopeNumber\fR) assigned to it
and, for functions and procedures, the type of its return value; for
procedures the return type is \fLvoid\fR.
The \fLLevel\fR field gives the static nesting level of the scope.
The \fLScopeEndString\fR gives the name of the scope and the assigned sequence
number.
.PP
.NH 2
Type Identifiers
.PP
.PR TypeStab ".stabs "" TypeString "" , TypeScope , 0 , Size , 0"
.PC TypeScope "N_LSYM | N_GSYM"
.PC N_GSYM 0x20
.PC N_LSYM 0x80
.PC TypeString "[Name] : t Type"
.PP
A \fLTypeStab\fR describes a data type, giving its name,
a description of the range of values it comprises and (for Modula-2) the size
in bytes of the storage it occupies.
The \fLSize\fR field is ignored by \fIdbx\fR for languages other than
Modula-2 and the size of a type is determined by its range of values.
The \fLTypeScope\fR indicates whether the type is locally or globally
defined.
See Section 3.20 below for a description of \fLType\fR.
.PP
.NH 2
Local Variables
.PP
.PR LclVarStab ".stabs "" Name : Type "" , N_LSYM , 0 , 0 , DataOffset"
.PP
A \fLLclVarStab\fR describes a local variable, giving its name, kind and type
and the offset from the stack pointer to the local.
.PP
.NH 2
Modula-2 Imports and Exports
.PP
.PR ImpExpStab ".stabs "" ImpExpString "" , N_LSYM , 0 , 0 , 0"
.PC ImpExpString "Name : ImpExpId"
.PC ImpExpId "U UnitNumber  | u UnitNumber | d ScopeNumber"
.PP
An \fLImpExpStab\fR is used by Modula-2 to describe a separately compiled
module and the symbols it defines.
See Table 2 (Section 3.30) below for a description of the letters occurring in
the \fLImpExpId\fR field.
.PP
.NH 2
Global Variables
.PP
.PR GlblVarStab ".stabs "" Name : G Type "" , N_GSYM , 0 , 0 , 0"
.PC N_GSYM 0x20
.PP
A \fLGlblVarStab\fR identifies a global variable.
The address of the variable is gotten from the corresponding assembler symbol.
.PP
.NH 2
Static Variables
.PP
.PR StaticVarStab ".stabs "" Name : StaticKind Type "" , StaticSym , 0 , 0 , DataAddr"
.PC StaticKind "S | V"
.PC StaticSym "N_STSYM | N_LCSYM"
.PC N_STSYM 0x26
.PC N_LCSYM 0x28
.PP
A \fLStaticVarStab\fR identifies a static variable, which may be either
uninitialized or initialized and either global or local.
Global statics are identified by \fLStaticKind\fR \fLS\fR and local ones
by \fLV\fR.
Uninitialized statics are identified by \fLStaticSym\fR \fLN_LCSYM\fR and
initialized ones by \fLN_STSYM\fR.
The \fLDataAddr\fR is the relocatable address assigned to the static
variable.
.PP
.NH 2
Parameters
.PP
.PR ParamStab ".stabs "" Name : ParamKind Type "" , N_PSYM , 0 , 0 , DataOffset"
.PC ParamKind "p | i | v | C | x | pP | pF | X"
.PC N_PSYM 0xa0
.PP
A \fLParamStab\fR describes a procedure or function parameter, giving its
name, kind, type and stack offset.
The kind is as described in Table 2 (Section 3.30) below, except that \fLpP\fR
and \fLpF\fR are used for Pascal procedure and function parameters,
respectively.
For register parameters a \fLRegStab\fR is also generated.
.PP
.NH 2
Register Variables
.PP
.PR RegStab ".stabs "" Name : Type "" , N_RSYM , 0 , RegSize , RegNumber"
.PC RegSize Number
.PC RegNumber Number
.PC N_RSYM 0x40
.PP
A \fLRegStab\fR describes a register variable or parameter, giving its
name, size in bytes, type and register number.
The register numbers are assigned as shown in Table 1.
.KF
.TS
box center;
l | l
l | l.
Register class	Numbers
_	_
Data registers d0 - d7	0 - 7
Address registers a0 - a7	8 - 15
MC68881 registers fp0 - fp7	18 - 25
FPA registers fpa0 - fpa31	31 - 62
.TE
.ce
Table 1.  Register Numbers
.sp 1
.KE
.LP
For register parameters a \fLParamStab\fR is also generated.
.PP
.NH 2
Common Blocks
.PP
.PR CommonStabs "BgnCommonStab GlblVarStab* EndCommonStab"
.PC BgnCommonStab ".stabs ""BlockName"" , N_BCOMM , 0 , 0 , 0"
.PC EndCommonStab ".stabs ""BlockName"" , N_ECOMM , 0 , 0 , 0"
.PC BlockName Name
.PC N_BCOMM 0xe2
.PC N_ECOMM 0xe4
.PP
A \fLBgnCommonStab\fR introduces the symbol list for a common block and the
corresponding \fLEndCommonStab\fR ends it.
.PP
.NH 2
Other Terms
.PP
.PR Level Number
.PC Size Number
.PC Line Number
.PC CodeAddr AddrExpr
.PC DataAddr AddrExpr
.PC DataOffset Number
.PR Number "[-] {DIGIT}\*+ | 0x {HEXDIGIT}\*+"
.PC Name " LETTER {LETTER | DIGIT}*"
.PC String "{CHARACTER}*"
.PP
An \fLAddrExpr\fR is an assembler address expression (see the assembly language
manual).
A \fLDIGIT\fR may be any decimal digit.
A \fLHEXDIGIT\fR may be a decimal digit or an upper or lower case letter in
the range \fLA\fR through \fLF\fR.
A \fLCHARACTER\fR may be any character accepted by the assembler in a string
(see the assembly language manual).
.PP
.sp 1
.NH 2
Specification of Types
.PP
Type information starts with a type descriptor, followed by type-specific
information, which is a sequence of information blocks separated by semicolons.
.sp 1
.in +1.0i
\fLtypedescriptor typeinfoblock ; ... ; typeinfoblock\fR
.in -1.0i
.sp 0.5
.LP
Upon definition of a type, a type number or type number pair is assigned
to it which can be used in later type specifications to refer to the
type definition.
.NH 2
Types, Type Definitions, Type References and Standard Types
.PP
.PR Type "TypeRef | TypeDef | Enumeration | RangeOrFloat | Array | DynArray | ConfArray | Record | Set | Pointer | ProcType | FuncType | FileType | SeparateType"
.PC TypeRef "Number | ( Number , Number )"
.PC TypeDef "TypeRef = Type"
.PP
A type may be any of those allowed by the C, FORTRAN 77, Modula-2 and
Pascal languages.
A \fLTypeRef\fR is the number or pair of numbers assigned to a type.
Whether numbers or pairs are used depends on the compiler.
Currently, C uses pairs and FORTRAN 77, Pascal and Modula-2 use
single numbers.
.PP
In the single number form, the numbers are assigned sequentially by the
compiler as it encounters type definitions during processing a source file and
the files included into it.
In the pair form, the first element identifies the file (the source file is
number 0 and successive include files are given successive numbers) and the
second element identifies successive types defined within each file.
.PP
A \fLTypeDef\fR associates a type number with a type definition.
.PP
Each language defines some standard types by a series of \fL.stabs\fR
lines, as shown in Appendix A.
.PP
.NH 2
Enumeration Types
.PP
.PR Enumeration "e {EnumName : OrdinalValue ,}\*+"
.PC EnumName Name
.PC OrdinalValue Number
.PP
An \fLEnumeration\fR defines an enumeration type by giving the names and values
of its elements.
.PP
.NH 2
Range, Floating-Point and Complex Types
.PP
.PR RangeOrFloat "r Type ; MinValue ; MaxValue"
.PC MinValue RangeValue
.PC MaxValue RangeValue
.PC RangeValue "[ A | J] Number"
.PP
A \fLRangeOrFloat\fR defines a range, floating-point or complex type.
It describes a range type if the number in the \fLMaxValue\fR field is
nonzero and the \fLMinValue\fR number is less than or equal to the
\fLMaxValue\fR number.
In this case, it gives the minimal and maximal values of the range and the
type it is a subrange of.
The letters \fLA\fR or \fLJ\fR occur only for ranges.
An \fLA\fR indicates that the following number, instead of being the range
value is the run-time offset from the frame pointer of the range.
A \fLT\fR indicates that the bound is adjustable at runtime and not
determinable, as may be the case for FORTRAN array arguments.
.PP
It describes a floating-point or complex type if the \fLMaxValue\fR field is
zero and the \fLMinValue\fR is greater than the \fLMaxValue\fR.
In this case, the \fLMinValue\fR field gives the number of bytes occupied by
values of the floating-point or complex type.
The type is interpreted as complex if the name in the \fL.stabs\fR line is
\fLcomplex\fR or \fLdouble complex\fR.
.PP
.NH 2
Array Types
.PP
.PR Array "a IndexType ; ElementType"
.PC IndexType Type
.PC ElementType Type
.PC DynArray "a r IndexType ; 0 ; A HighBound ; ElementType"
.PC ConfArray "a C LowBound , HighBound , IndexType ; ElementType"
.PC LowBound Number
.PC HighBound Number
.PP
An \fLArray\fR defines an array type by giving the types of the indexes and
elements.
Multidimensional arrays are treated as if they were one-dimensional arrays
of arrays.**
.FS
**See Appendix B, line 36 for an example.
.FE
.PP
A \fLDynArray\fR defines a Modula-2 dynamic array type by giving the types
of the indexes and elements and the high bound.
Note that \fLDynArray\fR is identical to an ordinary array whose index is
a range type (see Section 3.22).
.PP
A \fLConfArray\fR defines a Pascal conformant array type by giving the types
of the indexes and elements and the low and high bounds.
.PP
.NH 2
Record Types
.PP
.PR Record "s ByteSize FieldList"
.PC FieldList  "{FieldName : {Type | Variant} , BitOffset , BitSize ;}\*+"
.PC Variant "Selector ; { Case ; }\*+"
.PC Selector "v Flag : Type"
.PC Case "{CaseValue ,}\*+ : FieldList"
.PC FieldName Name
.PC ByteSize Number
.PC BitOffset Number
.PC BitSize Number
.PC CaseValue Number
.PC Flag "0 | 1"
.PP
A \fLRecord\fR defines a record type, giving the size in bytes of an instance
of the type and a description of each field.
A field description includes its name, either a type or a variant description,
bit offset within the record type and length in bits.
A variant consists of the selector name and a series of cases.
The flag in a selector indicates whether a variant record has a discriminant
(\fL1\fR) or not (\fL0\fR).
.PP
.NH 2
Set Types
.PP
.PR Set "S Type"
.PP
A \fLSet\fR defines a set type and specifies its base type.
.PP
.NH 2
Pointer Types
.PP
.PR Pointer "* Type"
.PP
A \fLPointer\fR defines a pointer type and specifies its base type.
.PP
.NH 2
Function and Procedure Types
.PP
.PR FuncType "Q ResultType , ParamNumber {; FormalType}*"
.PC ParamNumber Number
.PC FormalType "DataKind Type"
.PP
A \fLFuncType\fR defines a function or procedure type, giving its result type,
the number of parameters expected and descriptions of the parameters.
The \fLDataKind\fR field may be any of the type descriptors listed in
Table 2 (Section 3.31) below.
.PP
.NH 2
File Types (Pascal only)
.PP
.PR FileType "L Type"
.PP
A \fLFileType\fR describes a Pascal file type by giving its base type.
.PP
.NH 2
Types Defined in Separate Units (Modula-2)
.PP
.PR SeparateType "I UnitNumber , Name"
.PP
A \fLSeparateType\fR describes a type defined in a different compiled unit in
a Modula-2 program, giving its unit number and name.
.PP
.NH 2
Summary of Symbol Descriptors
.PP
Table 2 lists the symbol descriptors currently in use, along with their
meanings and the languages which generate them (C = C, F = FORTRAN 77,
M = Modula-2, P = Pascal).
.KF
.sp 1
.TS
center box;
c | c | c
cfL | l | c.
descriptor	meaning	languages
_
(empty)	local variable	C F M P
d	symbol defined in other scope	M
f	local (function) procedure	C P
i	value parameter by reference (indirect access)	M
p	value parameter	C F M P
r	register variable	C
t	type name	C F M P
u	symbol defined in a separate unit (module)	M
v	variable parameter by reference	F M P
x	conformant array value parameter	P
A	bound value in parameter with specified offset	F M
C	read-only parameter (conformant array bound)	P
E	end of scope	M
F	global (function) procedure	C F P
G	global variable	C F P
M	module	M
Q	procedure or function	M
S	static global variable	C M
T	enumeration or structure type tag	C
U	separate unit (module)	M
V	common / static local variable	F / C
X	function result variable	F P
.TE
.ce
Table 2.  Symbol Descriptors
.sp 1
.KE
.NH 2
Summary of Type Descriptors
.PP
Table 3 lists the type descriptors which are currently in use,
along with their meanings and the languages which generate them (C = C,
F = FORTRAN 77, M = Modula-2, P = Pascal).
.KF
.sp 1
.TS
center box;
c | c | c
cfL | l | c.
descriptor	meaning	languages
_
(empty)	type reference	C F M P
a	array type	C F M P
c	conformant array	P
e	enumeration type	C M P
f	function type	C
r	range type	C F M P
s	record / structure type	C M P
u	union specification	C
v	variant specification	P
C	lower and upper bound of a conformant array	P
F	function parameter type	P
I	separate type	M
L	file type	P
P	procedure parameter type	P
Q	function or procedure type	M
S	set type	M P
*	pointer type	C F M P
.TE
.ce
Table 3.  Type Descriptors
.sp 1
.KE
.PP
.NH 2
Generating Object Code Instead of Assembly Language
.PP
Some compilers prefer to generate object code directly, rather than Sun
assembly language.
This section explains how to generate the appropriate code for the assembler
symbols and \fL.stab\fR directives described above (linker symbols are
generated automatically by the system linker).
.PP
In the Sun-2 and Sun-3 assemblers, the three types of directives
.sp 1
.in +1.0i
\fL .stabs    "\fIname\fL",\fItype\fL,0,\fIdesc\fL,\fIvalue\fR
.sp 1
\fL .stabn    \fItype\fL,0,\fIdesc\fL,\fIvalue\fR
.in -1.0i
.sp 0.6
and
.sp 0.6
.in +1.0i
\fL .stabd    \fItype\fL,0,\fIdesc\fR
.in -1.0i
.sp 1
.LP
generate records in the \fIa.out\fR symbol table which are described by
variations of the C structure
.ne 7
.TS
center;
l l lw(1.5i) lw(1.0i) l lw(2.7i) l.
\s-2\fLstruct	nlist
{	long	 n_strx;	/* \fRstring table index\fL	*/
	unsigned char	 n_type;	/* \fRtype field\fL	*/
	char	 n_other;	/* \fRunused\fL	*/
	short	 n_desc;	/* \fRdesc field\fL	*/
	unsigned long	 n_value;	/* \fRsymbol value or offset\fL	*/
};\fR\s+2
.TE
with the variations as given by the field names, i.e. a \fL.stabs\fR directive
fills all five fields, a \fL.stabn\fR directive defaults the \fLn_strx\fR
field to zero, and a \fL.stabd\fR directive, in addition to defaulting
\fLn_strx\fR, sets the \fLn_value\fR field to the current value of the
assembler location counter.
.PP
Symbols generated by \fL.stab\fR directives are distinguished from assembler
symbols by whether any of the bits in the mask \fLN_STAB\fR (with value
\fL0xe0\fR) are set.
.PP
The \fLn_strx\fR field contains an index into the \fIa.out\fR string table for
the string occurring in a \fL.stabs\fR directive.
The string table consists of a 32-bit word containing the length of the table
in bytes (including the length word) followed by a series of
null-terminated strings.
The index is the offset of the first character of a string from the first
byte of the length word.
.PP
If the value field given in a \fL.stabd\fR directive is a symbol, the offset of
the symbol from the beginning of the appropriate control section (text, data
or bss) is placed in the \fLn_value\fR field.
The current location is handled similarly for the \fL.stabd\fR directive.
.PP
Assembler symbols can be described in terms of the \fL.stabs\fR directives
which would generate the same information.
Their syntax is as follows:
.PP
.PR AssemblerSymbol ".stabs "" SymbolName "" , SymbolType , 0 , 0 , SymbolOffset
.PC SymbolName Name
.PC SymbolType "N_TEXT | TextExternal | N_DATA | DataExternal | N_BSS | BssExternal"
.PC N_TEXT 0x04
.PC TextExternal 0x05
.PC N_DATA 0x06
.PC DataExternal 0x07
.PC N_BSS 0x08
.PC BssExternal 0x09
.PP
The \fLSymbolName\fR and \fLSymbolOffset\fR are simply the text of the symbol
and its offset within the text, data or bss space.
The \fLSymbolType\fR indicates the address space and whether the symbol is
external.
External symbols are indicated by or'ing the value of \fLN_EXT\fR, which is
\fL0x01\fR, with the type for the corresponding space.
.PP
.sp 1
.NH 2
Other Issues
.PP
There are several other things one needs to know to interface to the debuggers:
.sp 0.5
.IP 1.
The debuggers require that a program include a routine named \fL_main\fR.
If none is found, an internal error results.
.IP 2.
The debuggers assume the Sun standard format for the run-time stack.
If yours differs, it may still be possible to interface to them.
Contact us for more information.
.PP
.sp 1
.NH 1
The DP-UIP Interface Language
.PP
As mentioned above in Section 2, \fIdbxtool\fR consists of two processes, the
DP (debugger process) and the UIP (user interface process).
Commands passed from the DP to the UIP pass through a pipe which is created
by the UIP when it starts the DP.
The commands are expressed in the DP-UIP interface language, whose
syntax and semantics appear below.
.NH 2
What the UIP and DP Know About Each Other
.PP
In the current version of \fIdbxtool\fR there are several assumptions which
the UIP makes about the DP and vice versa, as follows:
.IP 1.
The name of the program which the UIP starts is \fLdbx\fR.
To do so, it calls \fLttysw_fork(\ )\fR with its second argument set to a
pointer to an array \fLnargv[ ]\fR of character strings of the form
.TS
center;
lfL l.
nargv[0]	\fLdbx\fR
nargv[1]	\fL-P\fR
nargv[2]	\fIpipenumber\fR
nargv[3]	\v'0.02i'\(rt\v'-0.02i'
  ...	\(rk \fIarguments\fR
nargv[\fIn\fR]	\v'-0.02i'\(rb\v'0.02i'
.TE
where \fIpipenumber\fR is the number of the pipe which the DP uses in writing
to the UIP and \fIarguments\fR are the arguments with which \fIdbxtool\fR
was invoked.
.IP 2.
The sequence of directories to search for source files (provided by
the \fIuse\fR command in \fIdbx\fR and \fIdbxtool\fR) is passed by the
DP to the UIP (via the \fLI_USE\fR command described below) and used by it
to display source in the source window.
.IP 3.
The lineno selection interpretation is expanded into the form
"\fIfilename\fR":\fIlineno\fR before it is passed to the DP.
.IP 4.
The UIP's command button mechanism assumes that the DP expects commands in
prefix form, i.e. with the command name first, and with a blank separating
the name from the following argument (if any).
Further, for the command buttons to be really useful it must be the case that
the DP's most used commands take either zero or one argument, since the
argument selection mechanism cannot accomodate more than one selection per
command.
.PP
.NH 2
Commands and Type Identifiers
.PP
.PR Command "VersionCheck | InitDone | Stopped | Quit | PrintLines | BreakSet | BreakDel | Resume | Use | Reinit | Kill | Chdir | Emphasize | Trace | Display | ToolEnv | Width | SourceLines | CommandLines | DisplayLines | Font | TopMargin | BotMargin | Un





button | Button"
.PP
Each command and argument begins with a type identifier which indicates the
command or the type of the argument.
The mapping between integers and type identifiers is given in Table 4.
.KF
.sp 1
.TS
center box;
n | lfL.
0	I_BADTYPE
1	I_INITDONE
2	I_STOPPED
3	I_STRING
4	I_INT
5	I_QUIT
6	I_PRINTLINES
7	I_BRKSET
8	I_BRKDEL
9	I_RESUME
10	I_USE
11	I_REINIT
12	I_KILL
13	I_CHDIR
14	I_EMPHASIZE
15	I_TRACE
16	I_DISPLAY
17	I_VERSION
18	I_TOOLENV
19	I_WIDTH
20	I_SRCLINES
21	I_CMDLINES
22	I_DISPLINES
23	I_FONT
24	I_TOPMARGIN
25	I_BOTMARGIN
26	I_UNBUTTON
27	I_BUTTON
.TE
.ce
Table 4.  Command and Type Identifiers
.sp 1
.KE
.PP
.NH 2
Version Consistency Checking
.PP
.PR VersionCheck "I_VERSION VersionNumber"
.PP
The DP issues this command during initialization to insure that the versions
of the DP and UIP being run are consistent with each other.
It tells the UIP the version number of the DP, which must match that of the
UIP.
It must be the first command issued.
.PP
.NH 2
Initialization Finished
.PP
.PR InitDone "I_INITDONE FileName LineNumber"
.PP
The DP issues this command to inform the UIP that it has completed initializing
itself.
It tells the UIP the name of the source file to display and the line number of
the line to appear at the top of the source window.
.PP
.NH 2
Breakpoint Reached
.PP
.PR Stopped "I_STOPPED FileName FuncName LineNumber BreakFile BreakFunc BreakLine"
.PP
This command indicates that a breakpoint has been reached and tells the
UIP the filename, function name and line number of the point currently
being displayed and the same information concerning the breakpoint.
.PP
.NH 2
Terminate \fIDbxtool\fR
.PP
.PR Quit "I_QUIT ExitStatus"
.PP
This command tells the UIP to terminate execution of \fIdbxtool\fR and return
the given exit status to the shell which invoked it.
.PP
.NH 2
Print Source Lines
.PP
.PR PrintLines "I_PRINTLINES FileName LineNumber LineNumber"
.PP
This command specifies a filename and two line numbers, the second of which
is ignored by the UIP.
It causes the UIP to display lines from the given file in the source window.
.PP
.NH 2
Set a Breakpoint
.PP
.PR BreakSet "I_BRKSET FileName LineNumber"
.PP
This command tells the UIP to display a stop sign on the given line
of the given file.
.PP
.NH 2
Delete a Breakpoint
.PP
.PR BreakDel "I_BRKDEL FileName LineNumber"
.PP
This command tells the UIP to remove a stop sign from the given line
of the given file.
.PP
.NH 2
Ready to Resume Execution 
.PP
.PR Resume "I_RESUME"
.PP
This command tells the UIP that the DP is ready to resume execution of the
process being debugged.
.PP
.NH 2
Specify Directory Search Path
.PP
.PR Use "I_USE DirNumber Directory*"
.PP
This command specifies to the UIP the search path to be used in locating
source files.
It specifies the number of directories followed by their names. 
.PP
.NH 2
Reinitialize the Debugger
.PP
.PR Reinit "I_REINIT"
.PP
This command indicates that the debugger is being reinitialized to debug
another process.
.PP
.NH 2
Kill the Process Being Debugged
.PP
.PR Kill "I_KILL"
.PP
This command informs the UIP that the process being debugged has been
discarded by the DP.
.PP
.NH 2
Change Directory
.PP
.PR Chdir "I_CHDIR Directory"
.PP
This command tells the UIP to change its notion of the current directory
to the one specified.
.PP
.NH 2
Display and Highlight Source Lines
.PP
.PR Emphasize "I_EMPHASIZE FileName LineNumber"
.PP
This command tells the UIP to highlight the given source line (and to display
it if it is not already displayed).
.PP
.NH 2
Display and Highlight Traced Lines
.PP
.PR Trace "I_TRACE BreakFile BreakFunc  BreakLine"
.PP
This command tells the UIP to highlight the given source line and display the
arrow indicating the execution focus next to it (and to display it if it
is not already displayed).
.PP
.NH 2
Update Variable Display
.PP
.PR Display "I_DISPLAY DisplayFile"
.PP
This command tells the UIP to update the variable display window by
showing the contents of the given file.
.PP
.NH 2
Print the Tool Environment
.PP
.PR ToolEnv "I_TOOLENV"
.PP
This command causes the UIP to print the current tool environment parameters.
.PP
.NH 2
Specify Width of Window
.PP
.PR Width "I_WIDTH Number"
.PP
This command causes the UIP to change the width of the window to the
given number of characters.
.PP
.NH 2
Specify Number of Lines in Source Window
.PP
.PR SourceLines "I_SRCLINES NumberLines"
.PP
This command causes the UIP to set the vertical size of the source window to
the given number of lines.
.PP
.NH 2
Specify Number of Lines in Command Window
.PP
.PR CommandLines "I_CMDLINES NumberLines"
.PP
This command causes the UIP to set the vertical size of the command window to
the given number of lines.
.PP
.NH 2
Specify Number of Lines in Display Window
.PP
.PR DisplayLines "I_DISPLINES NumberLines"
.PP
This command causes the UIP to set the vertical size of the display window to
the given number of lines.
.PP
.NH 2
Change Font
.PP
.PR Font "I_FONT FontFile"
.PP
This command causes the UIP to using the font given in the specified font file.
.PP
.NH 2
Change Top Margin of Source Window
.PP
.PR TopMargin "I_TOPMARGIN NumberLines"
.PP
This command causes the UIP to set the number of lines between the top of the
source window and the first line containing a breakpoint or the current
execution focus.
.PP
.NH 2
Change Bottom Margin of Source Window
.PP
.PR BotMargin "I_BOTMARGIN NumberLines"
.PP
This command causes the UIP to set the number of lines between the bottom
of the source window and the last line containing a breakpoint or the current
execution focus.
.PP
.NH 2
Remove a Button from the Buttons Window
.PP
.PR Unbutton "I_UNBUTTON ButtonName"
.PP
This command causes the UIP to remove from the buttons window the first button
with the given name.
.PP
.NH 2
Add a Button to the Buttons Window
.PP
.PR Button "I_BUTTON SelectionType ButtonName"
.PP
This command causes the UIP to add to the buttons window a button with the
indicated selection interpretation and name.
The mapping between selection type numbers and selection interpretations
and their meanings is given in Table 5.
.KF
.sp 1
.TS
center box;
c | c | cw(3.5i)
n | l | lw(3.5i).
type	name	meaning
_
1	command	T{
the selection, which must be in the command window, is expanded to produce
the command which contains it
T}
_
2	expand	T{
the selection produces exactly the selected text, except that if either
its first or last character is an alphanumeric or an underscore it is
expanded to produce the longest enclosing sequence of alphanumerics and
underscores
T}
_
3	ignore	T{
the selection is ignored, producing the null string
T}
_
4	lineno	T{
the selection, which must be in the source window, produces a string of the
form "\fIfilename\fR":\fIlineno\fR, where \fIfilename\fR is the name of the
file displayed in the source window and \fIlineno\fR is the line number of
the selected line
T}
_
5	literal	T{
the selection produces exactly the selected text
T}
.TE
.ce
Table 5.  Selection Interpretations
.sp 1
.KE
.PP
.NH 2
Other Items
.PP
.PR SelectionType Number
.PC FileName String
.PC LineNumber Number
.PC FuncName String
.PC BreakFile String
.PC BreakFunc String
.PC BreakLine Number
.PC ExitStatus Number
.PC DirNumber Number
.PC Directory String
.PC DisplayFile String
.PC NumberLines Number
.PC FontFile String
.PC ButtonName String
.PP
.NH 2
Numbers and Strings
.PP
.PR Number "I_INT Integer"
.PC String "I_STRING StringLen Character*"
.PC StringLen Integer
.PP
A number is a 32-bit integer.
A string consists of a 32-bit integer followed by a sequence of that many
characters.
.PP
.bp
.ce
\s+2\fBAppendix A.  Standard Types for Sun C, FORTRAN 77, Pascal
.ce
 and Modula-2\fR\s-2
.sp 1
.PP
Each language defines some standard types by a series of \fL.stabs\fR
lines, as follows.
For C***, they are
.FS
***The "\fL???\fR" entry at the end is a debugging artifact.
It serves no purpose in ordinary usage of \fIdbx\fR.
.FE
.sp 1
.in +0.75i
.nf
\fL\s-2
 .stabs    "int:t(0,1)=r(0,1);-2147483648;2147483647;",0x80,0,0,0
 .stabs    "char:t(0,2)=r(0,2);0;127;",0x80,0,0,0
 .stabs    "long:t(0,3)=r(0,1);-2147483648;2147483647;",0x80,0,0,0
 .stabs    "short:t(0,4)=r(0,1);-32768;32767;",0x80,0,0,0
 .stabs    "unsigned char:t(0,5)=r(0,1);0;255;",0x80,0,0,0
 .stabs    "unsigned short:t(0,6)=r(0,1);0;65535;",0x80,0,0,0
 .stabs    "unsigned long:t(0,7)=r(0,1);0;-1;",0x80,0,0,0
 .stabs    "unsigned int:t(0,8)=r(0,1);0;-1;",0x80,0,0,0
 .stabs    "float:t(0,9)=r(0,1);4;0;",0x80,0,0,0
 .stabs    "double:t(0,10)=r(0,1);8;0;",0x80,0,0,0
 .stabs    "void:t(0,11)=(0,11)",0x80,0,0,0
 .stabs    "???:t(0,12)=(0,1)",0x80,0,0,0
\fR\s+2
.fi
.in -0.75i
.sp 1
For FORTRAN 77, they are
.sp 1
.in +0.75i
.nf
\fL\s-2
 .stabs    "integer*2:t2=r2;-32768;32767;",0x20,0,0,0
 .stabs    "integer*4:t3=r3;-2147483648;2147483647;",0x20,0,0,0
 .stabs    "real:t5=r5;4;0;",0x20,0,0,0
 .stabs    "double precision:t6=r6;8;0;",0x20,0,0,0
 .stabs    "complex:t7=r7;8;0;",0x20,0,0,0
 .stabs    "double complex:t8=r8;16;0;",0x20,0,0,0
 .stabs    "logical:t9=3;",0x20,0,0,0
 .stabs    "char:t10=r10;0;127;",0x20,0,0,0
 .stabs    "void:t11=r11;0;0;",0x20,0,0,0
\fR\s+2
.fi
.in -0.75i
.sp 1
For Pascal, they are
.sp 1
.in +0.75i
.nf
\fL\s-2
 .stabs    "boolean:t1=efalse:0,true:1,",0x20,0x0,0x0,0x0
 .stabs    "char:t2=r2;0;127",0x20,0x0,0x0,0x0
 .stabs    "integer:t3=r3;-2147483648;2147483647",0x20,0x0,0x0,0x0
 .stabs    "shortreal:t4=r4;4;0",0x20,0x0,0x0,0x0
 .stabs    "real:t5=r5;8;0",0x20,0x0,0x0,0x0
 .stabs    "(void):t6=6",0x20,0x0,0x0,0x0
 .stabs    "Boolean:t1",0x20,0x0,0x0,0x0
 .stabs    "intset:t7=Sr3;0;127",0x20,0x0,0x0,0x0
 .stabs    "alfa:t8=ar3;1;10;2",0x20,0x0,0x0,0x0
 .stabs    "text:t9=L2",0x20,0x0,0x0,0x0
 .stabs    "longreal:t5",0x20,0x0,0x0,0x0
\fR\s+2
.fi
.in -0.75i
.sp 1
.ne 10
For Modula-2, they are
.sp 1
.in +0.75i
.nf
\fL\s-2
 .stabs    "INTEGER:t1=r1;-2147483648;2147483647", 0x80, 0, 4, 0
 .stabs    "SHORTINT:t2=r1;-32768;32767", 0x80, 0, 2, 0
 .stabs    "CARDINAL:t3=r3;0;-1", 0x80, 0, 4, 0
 .stabs    "SHORTCARD:t4=r3;0;65535", 0x80, 0, 2, 0
 .stabs    "CHAR:t5=r5;0;255", 0x80, 0, 1, 0
 .stabs    "BOOLEAN:t6=eFALSE:0,TRUE:1,", 0x80, 0, 1, 0
 .stabs    "REAL:t7=r7;4;0", 0x80, 0, 4, 0
 .stabs    "(void):t8=8", 0x80, 0, 4, 0
 .stabs    "PROC:t9=Q8,0", 0x80, 0, 4, 0
 .stabs    "BITSET:t10=Sr3;0;31", 0x80, 0, 4, 0
 .stabs    "BYTE:t11=r11;0;255", 0x80, 0, 1, 0
 .stabs    "WORD:t12=r12;0;-1", 0x80, 0, 4, 0
 .stabs    "ADDRESS:t13=r3;0;-1", 0x80, 0, 4, 0
 .stabs    "PROCESS:t14=*12", 0x80, 0, 4, 0
\fR\s+2
.fi
.in -0.75i
.sp 1
.bp
.ce
\s+2\fBAppendix B.  An Example of the Compiler-Debugger Interface\fR\s-2
.sp 1
.PP
This appendix gives an example of the code generated by the Sun C compiler
to interface to the \fIdbx\fR and \fIdbxtool\fR debuggers.
We take as our example the (nonsense) C program
.sp 1
.in +1.0i
.nf
\fL
int a;
static int b;

static void l( );

main (d)
register short int d;
{	int e[10][20];
	static int g = 3;
	register int h;
	struct i {
		int j;
		float k;
	} i;

	a = 2;
	i.j = b;
	l( );
}

static void l()
{
	b = 3;
}
\fR
.fi
.in -1.0i
.LP
Compiling this program with \fLcc -g -S example.c\fR results in the following
assembly code in \fLexample.s\fR (with line numbers supplied at the left):
.TS
nw(0.4i) lw(0.7i)fL lw(0.9i)fL lfL.
\s-2
1		.stabs	"example.c",0x64,0,0,LL0
2	LL0:
3		.data
4		.stabs	"int:t(0,1)=r(0,1);-2147483648;2147483647;",
			0x80,0,0,0
5		.stabs	"char:t(0,2)=r(0,2);0;127;",0x80,0,0,0
6		.stabs	"long:t(0,3)=r(0,1);-2147483648;2147483647;",
			0x80,0,0,0
7		.stabs	"short:t(0,4)=r(0,1);-32768;32767;",0x80,0,0,0
8		.stabs	"unsigned char:t(0,5)=r(0,1);0;255;",
			0x80,0,0,0
9		.stabs	"unsigned short:t(0,6)=r(0,1);0;65535;",
			0x80,0,0,0
10		.stabs	"unsigned long:t(0,7)=r(0,1);0;-1;",0x80,0,0,0
11		.stabs	"unsigned int:t(0,8)=r(0,1);0;-1;",0x80,0,0,0
12		.stabs	"float:t(0,9)=r(0,1);4;0;",0x80,0,0,0
13		.stabs	"double:t(0,10)=r(0,1);8;0;",0x80,0,0,0
14		.stabs	"void:t(0,11)=(0,11)",0x80,0,0,0
15		.stabs	"???:t(0,12)=(0,1)",0x80,0,0,0
16		.stabs	"a:G(0,1)",0x20,0,4,0
17		.comm	_a,0x4
18		.stabs	"b:S(0,1)",0x28,0,4,_b
19		.lcomm	_b,4
20	|||		        no info for l (18) 
21		.stabs	"main:F(0,1)",0x24,0,4,_main
22		.stabs	"d:r(0,4)",0x40,0,2,7
23		.stabs	"d:p(0,4)",0xa0,0,2,8
24		.text
25		.stabn	0x44,0,8,LL1
26	LL1:
27	|	#PROC# 04
28		.globl	_main
29	_main:
30		link	a6,#0
31		addl	#-LF14,sp
32		moveml	#LS14,sp@
33		movw	a6@(10),d7
34		.stabn	0x44,0,8,LL2
35	LL2:
36		.stabs	"e:(0,13)=ar(0,1);0;9;(0,14)=ar(0,1);0;19;(0,1)",
			0x80,0,4,-800
37		.stabs	"g:V(0,1)",0x26,0,4,L16
38		.data
39		.even
40	L16:
41		.text
42		.data
43		.long	0x3
44		.stabs	"h:r(0,1)",0x40,0,4,6
45		.stabs	"i:T(0,15)=s8j:(0,1),0,32;k:(0,9),32,32;;",
			0x80,0,8,-1275
46		.stabs	"i:(0,15)",0x80,0,8,-808
47		.stabn	0xc0,0,2,LL3
48	LL3:
49		.text
50		.stabn	0x44,0,16,LL4
51	LL4:
52		movl	#0x2,_a
53		.stabn	0x44,0,17,LL5
54	LL5:
55		movl	_b,a6@(-0x328)
56		.stabn	0x44,0,18,LL6
57	LL6:
58		jbsr	_l
59		.stabn	0xe0,0,2,LL7
60	LL7:
61		.stabn	0x44,0,19,LL8
62	LL8:
63	LE14:
64		moveml	a6@(-0x32c),#0x80
65		unlk	a6
66		rts
67		LF14	= 812
68		LS14	= 0x80
69		LFF14	= 808
70		LSS14	= 0x0
71		LP14	= 0x8
72		.data
73		.stabs	"l:f(0,11)",0x24,0,0,_l
74		.text
75		.stabn	0x44,0,22,LL9
76	LL9:
77	|	#PROC# 0
78	_l:
79		link	a6,#0
80		addl	#-LF17,sp
81		moveml	#LS17,sp@
82		.stabn	0x44,0,22,LL10
83	LL10:
84		.stabn	0x44,0,23,LL11
85	LL11:
86		movl	#0x3,_b
87		.stabn	0x44,0,24,LL12
88	LL12:
89	LE17:
90		unlk	a6
91		rts
92		LF17	= 0
93		LS17	= 0x0
94		LFF17	= 0
95		LSS17	= 0x0
96		LP17	= 0x8
97		.data
\s+2
.TE
.LP
The following commentary is keyed to the line numbers appearing at the left.
.IP 1: 0.75i
Identifies the source file from which the program was compiled.
.IP "4 - 15:" 0.75i
The C standard types, generated automatically by the compiler.
Line 4, for example, defines \fLint\fR to be type number \fL(0,1)\fR, to be
a subrange of itself with values extending from \fL-2147483648\fR through
\fL2147483647\fR and to be local.
.IP "16 - 17:" 0.75i
The variable \fLa\fR is identified as being a global \fLint\fR
("\fLG(0,1)\fR") and as occupying 4 bytes of storage.
Its address is given by the assembler symbol \fL_a\fR.
.IP "18 - 19:" 0.75i
The variable \fLb\fR is identified as being a static global \fLint\fR
("\fLS(0,1)\fR") occupying 4 bytes of storage an with address \fL_b\fR.
.IP 20: 0.75i
The information about \fLl\fR will come later when it is declared (see
line 73).
.IP 21: 0.75i
The symbol \fLmain\fR is identified as a function returning an \fLint\fR
("\fLF(0,1)\fR") and as beginning at the assembler symbol \fL_main\fR.
.IP "22 - 23:" 0.75i
The symbol \fLd\fR is a \fLshort int\fR parameter ("\fLp(0,4)\fR") and a
register variable ("\fLr(0,4)\fR") occupying in register d7.
.IP 25: 0.75i
This entry represents a bug discovered in the C compiler discovered during
preparation of this document.
The entry on line 34 is the correct one (\fIq.v.\fR)
The bug causes no errors in the debugger since the second (correct) entry for
line 8 simply supplants this one.
.IP 34: 0.75i
Identifies the first line of \fLexample.c\fR for which any executable code is
generated as line 8 and as corresponding to assembly label \fLLL2\fR.
Line 8 is the entry point of \fLmain\fR.
.IP 36: 0.75i
Identifies the symbol \fLe\fR as an array of arrays with anonymous type
\fL(0,13)\fR.
Its subscript is a subrange of \fLint\fR with range \fL0\fR through \fL9\fR
and its elements are arrays with anonymous type \fL(0,14)\fR, which in turn
is an array whose subscript is a subrange of \fLint\fR with range \fL0\fR
through \fL19\fR and element type \fLint\fR.
Its stack offset is -800.
.IP 37: 0.75i
Identifies the symbol \fLg\fR as a static local variable of type \fLint\fR
("\fLV(0,1)\fR") located at label \fLL16\fR.
.IP 44: 0.75i
The variable \fLh\fR is identified as being a \fLregister int\fR
("\fLr(0,1)\fR") occupying register d6.
.IP 45: 0.75i
Identifies the symbol \fLi\fR as a structure tag of anonymous type
\fL(0,15)\fR.
Type \fL(0,15)\fR is defined as a structure type occupying 8 bytes with fields
named \fLj\fR and \fLk\fR.
Field \fLj\fR is of type \fLint\fR, begins at bit offset zero and runs for
32 bits; field \fLk\fR is of type \fLfloat\fR, begins at bit offset 32 and
runs for 32 bits.
.IP 46: 0.75i
Identifies the symbol \fLi\fR as a local variable of type \fL(0,15)\fR
occupying eight bytes and located at stack offset -808.
.IP 47: 0.75i
Identifies a level 2 scope beginning at label \fLLL3\fR.
.IP 59: 0.75i
Identifies a level 2 scope ending at label \fLLL7\fR.
.IP 73: 0.75i
Identifies \fLl\fR as a local function returning \fLvoid\fR and beginning at
symbol \fL_l\fR.
.IP "75 & 82:" 0.75i
These two lines represent the same harmless C compiler bug as do lines 25 and
34.