Initial creation of sourceware repository

[external/binutils.git] / gdb / doc / stabs.info-3

This is Info file stabs.info, produced by Makeinfo version 1.68 from
the input file ./stabs.texinfo.

START-INFO-DIR-ENTRY
* Stabs: (stabs).                 The "stabs" debugging information format.
END-INFO-DIR-ENTRY

   This document describes the stabs debugging symbol tables.

   Copyright 1992, 93, 94, 95, 97, 1998 Free Software Foundation, Inc.
Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,
and David MacKenzie.

   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 copy or distribute modified versions of this
manual under the terms of the GPL (for which purpose this text may be
regarded as a program in the language TeX).

\1f
File: stabs.info,  Node: Class Instance,  Next: Methods,  Prev: Simple Classes,  Up: Cplusplus

Class Instance
==============

   As shown above, describing even a simple C++ class definition is
accomplished by massively extending the stab format used in C to
describe structure types.  However, once the class is defined, C stabs
with no modifications can be used to describe class instances.  The
following source:

     main () {
             baseA AbaseA;
     }

yields the following stab describing the class instance.  It looks no
different from a standard C stab describing a local variable.

     .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset

     .stabs "AbaseA:20",128,0,0,-20

\1f
File: stabs.info,  Node: Methods,  Next: Method Type Descriptor,  Prev: Class Instance,  Up: Cplusplus

Method Definition
=================

   The class definition shown above declares Ameth.  The C++ source
below defines Ameth:

     int
     baseA::Ameth(int in, char other)
     {
             return in;
     };

   This method definition yields three stabs following the code of the
method.  One stab describes the method itself and following two describe
its parameters.  Although there is only one formal argument all methods
have an implicit argument which is the `this' pointer.  The `this'
pointer is a pointer to the object on which the method was called.  Note
that the method name is mangled to encode the class name and argument
types.  Name mangling is described in the ARM (`The Annotated C++
Reference Manual', by Ellis and Stroustrup, ISBN 0-201-51459-1);
`gpcompare.texi' in Cygnus GCC distributions describes the differences
between GNU mangling and ARM mangling.

     .stabs "name:symbol_desriptor(global function)return_type(int)",
             N_FUN, NIL, NIL, code_addr_of_method_start
     
     .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic

   Here is the stab for the `this' pointer implicit argument.  The name
of the `this' pointer is always `this'.  Type 19, the `this' pointer is
defined as a pointer to type 20, `baseA', but a stab defining `baseA'
has not yet been emited.  Since the compiler knows it will be emited
shortly, here it just outputs a cross reference to the undefined
symbol, by prefixing the symbol name with `xs'.

     .stabs "name:sym_desc(register param)type_def(19)=
             type_desc(ptr to)type_ref(baseA)=
             type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number
     
     .stabs "this:P19=*20=xsbaseA:",64,0,0,8

   The stab for the explicit integer argument looks just like a
parameter to a C function.  The last field of the stab is the offset
from the argument pointer, which in most systems is the same as the
frame pointer.

     .stabs "name:sym_desc(value parameter)type_ref(int)",
             N_PSYM,NIL,NIL,offset_from_arg_ptr
     
     .stabs "in:p1",160,0,0,72

   << The examples that follow are based on A1.C >>

\1f
File: stabs.info,  Node: Method Type Descriptor,  Next: Member Type Descriptor,  Prev: Methods,  Up: Cplusplus

The `#' Type Descriptor
=======================

   This is used to describe a class method.  This is a function which
takes an extra argument as its first argument, for the `this' pointer.

   If the `#' is immediately followed by another `#', the second one
will be followed by the return type and a semicolon.  The class and
argument types are not specified, and must be determined by demangling
the name of the method if it is available.

   Otherwise, the single `#' is followed by the class type, a comma,
the return type, a comma, and zero or more parameter types separated by
commas.  The list of arguments is terminated by a semicolon.  In the
debugging output generated by gcc, a final argument type of `void'
indicates a method which does not take a variable number of arguments.
If the final argument type of `void' does not appear, the method was
declared with an ellipsis.

   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.

\1f
File: stabs.info,  Node: Member Type Descriptor,  Next: Protections,  Prev: Method Type Descriptor,  Up: Cplusplus

The `@' Type Descriptor
=======================

   The `@' 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
(*note String Field::.); both use type descriptor `@'.  Fortunately,
the `@' type descriptor used in this C++ sense always will be followed
by a digit, `(', or `-', and type attributes never start with those
things.

\1f
File: stabs.info,  Node: Protections,  Next: Method Modifiers,  Prev: Member Type Descriptor,  Up: Cplusplus

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.

   If the character following the `FIELD-NAME:' part of the string is
`/', then the next character is the visibility.  `0' means private, `1'
means protected, and `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 `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 `9' is not supported by
GDB 4.11; this should be fixed in the next GDB release.

   The following C++ source:

     class vis {
     private:
             int   priv;
     protected:
             char  prot;
     public:
             float pub;
     };

generates the following stab:

     # 128 is N_LSYM
     .stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0

   `vis:T19=s12' indicates that type number 19 is a 12 byte structure
named `vis' The `priv' field has public visibility (`/0'), type int
(`1'), and offset and size `,0,32;'.  The `prot' field has protected
visibility (`/1'), type char (`2') and offset and size `,32,8;'.  The
`pub' field has type float (`12'), and offset and size `,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
private, 1 if protected and 2 if public.  Consider the C++ class
definition below:

     class all_methods {
     private:
             int   priv_meth(int in){return in;};
     protected:
             char  protMeth(char in){return in;};
     public:
             float pubMeth(float in){return in;};
     };

   It generates the following stab.  The digit in question is to the
left of an `A' in each case.  Notice also that in this case two symbol
descriptors apply to the class name struct tag and struct type.

     .stabs "class_name:sym_desc(struct tag&type)type_def(21)=
             sym_desc(struct)struct_bytes(1)
             meth_name::type_def(22)=sym_desc(method)returning(int);
             :args(int);protection(private)modifier(normal)virtual(no);
             meth_name::type_def(23)=sym_desc(method)returning(char);
             :args(char);protection(protected)modifier(normal)virual(no);
             meth_name::type_def(24)=sym_desc(method)returning(float);
             :args(float);protection(public)modifier(normal)virtual(no);;",
             N_LSYM,NIL,NIL,NIL

     .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.;
             pubMeth::24=##12;:f;2A.;;",128,0,0,0

\1f
File: stabs.info,  Node: Method Modifiers,  Next: Virtual Methods,  Prev: Protections,  Up: Cplusplus

Method Modifiers (`const', `volatile', `const volatile')
========================================================

   << based on a6.C >>

   In the class example described above all the methods have the normal
modifier.  This method modifier information is located just after the
protection information for the method.  This field has four possible
character values.  Normal methods use `A', const methods use `B',
volatile methods use `C', and const volatile methods use `D'.  Consider
the class definition below:

     class A {
     public:
             int ConstMeth (int arg) const { return arg; };
             char VolatileMeth (char arg) volatile { return arg; };
             float ConstVolMeth (float arg) const volatile {return arg; };
     };

   This class is described by the following stab:

     .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1)
             meth_name(ConstMeth)::type_def(21)sym_desc(method)
             returning(int);:arg(int);protection(public)modifier(const)virtual(no);
             meth_name(VolatileMeth)::type_def(22)=sym_desc(method)
             returning(char);:arg(char);protection(public)modifier(volatile)virt(no)
             meth_name(ConstVolMeth)::type_def(23)=sym_desc(method)
             returning(float);:arg(float);protection(public)modifer(const volatile)
             virtual(no);;", ...

     .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.;
                  ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0

\1f
File: stabs.info,  Node: Virtual Methods,  Next: Inheritence,  Prev: Method Modifiers,  Up: Cplusplus

Virtual Methods
===============

   << The following examples are based on a4.C >>

   The presence of virtual methods in a class definition adds additional
data to the class description.  The extra data is appended to the
description of the virtual method and to the end of the class
description.  Consider the class definition below:

     class A {
     public:
             int Adat;
             virtual int A_virt (int arg) { return arg; };
     };

   This results in the stab below describing class A.  It defines a new
type (20) which is an 8 byte structure.  The first field of the class
struct is `Adat', an integer, starting at structure offset 0 and
occupying 32 bits.

   The second field in the class struct is not explicitly defined by the
C++ class definition but is implied by the fact that the class contains
a virtual method.  This field is the vtable pointer.  The name of the
vtable pointer field starts with `$vf' and continues with a type
reference to the class it is part of.  In this example the type
reference for class A is 20 so the name of its vtable pointer field is
`$vf20', followed by the usual colon.

   Next there is a type definition for the vtable pointer type (21).
This is in turn defined as a pointer to another new type (22).

   Type 22 is the vtable itself, which is defined as an array, indexed
by a range of integers between 0 and 1, and whose elements are of type
17.  Type 17 was the vtable record type defined by the boilerplate C++
type definitions, as shown earlier.

   The bit offset of the vtable pointer field is 32.  The number of bits
in the field are not specified when the field is a vtable pointer.

   Next is the method definition for the virtual member function
`A_virt'.  Its description starts out using the same format as the
non-virtual member functions described above, except instead of a dot
after the `A' there is an asterisk, indicating that the function is
virtual.  Since is is virtual some addition information is appended to
the end of the method description.

   The first number represents the vtable index of the method.  This is
a 32 bit unsigned number with the high bit set, followed by a
semi-colon.

   The second number is a type reference to the first base class in the
inheritence hierarchy defining the virtual member function.  In this
case the class stab describes a base class so the virtual function is
not overriding any other definition of the method.  Therefore the
reference is to the type number of the class that the stab is
describing (20).

   This is followed by three semi-colons.  One marks the end of the
current sub-section, one marks the end of the method field, and the
third marks the end of the struct definition.

   For classes containing virtual functions the very last section of the
string part of the stab holds a type reference to the first base class.
This is preceeded by `~%' and followed by a final semi-colon.

     .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
             field_name(Adat):type_ref(int),bit_offset(0),field_bits(32);
             field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)=
             sym_desc(array)index_type_ref(range of int from 0 to 1);
             elem_type_ref(vtbl elem type),
             bit_offset(32);
             meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int);
             :arg_type(int),protection(public)normal(yes)virtual(yes)
             vtable_index(1);class_first_defining(A);;;~%first_base(A);",
             N_LSYM,NIL,NIL,NIL

     .stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
             A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0

\1f
File: stabs.info,  Node: Inheritence,  Next: Virtual Base Classes,  Prev: Virtual Methods,  Up: Cplusplus

Inheritence
===========

   Stabs describing C++ derived classes include additional sections that
describe the inheritence hierarchy of the class.  A derived class stab
also encodes the number of base classes.  For each base class it tells
if the base class is virtual or not, and if the inheritence is private
or public.  It also gives the offset into the object of the portion of
the object corresponding to each base class.

   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: a virtual character,
a visibilty character, a number, a comma, another number, and a
semi-colon.

   The virtual character is `1' if the base class is virtual and `0' if
not.  The visibility character is `2' if the derivation is public, `1'
if it is protected, and `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 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
base class.

   The source below defines three base classes `A', `B', and `C' and
the derived class `D'.

     class A {
     public:
             int Adat;
             virtual int A_virt (int arg) { return arg; };
     };
     
     class B {
     public:
             int B_dat;
             virtual int B_virt (int arg) {return arg; };
     };
     
     class C {
     public:
             int Cdat;
             virtual int C_virt (int arg) {return arg; };
     };
     
     class D : A, virtual B, public C {
     public:
             int Ddat;
             virtual int A_virt (int arg ) { return arg+1; };
             virtual int B_virt (int arg)  { return arg+2; };
             virtual int C_virt (int arg)  { return arg+3; };
             virtual int D_virt (int arg)  { return arg; };
     };

   Class stabs similar to the ones described earlier are generated for
each base class.

     .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
             A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
     
     .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1;
             :i;2A*-2147483647;25;;;~%25;",128,0,0,0
     
     .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1;
             :i;2A*-2147483647;28;;;~%28;",128,0,0,0

   In the stab describing derived class `D' below, the information about
the derivation of this class is encoded as follows.

     .stabs "derived_class_name:symbol_descriptors(struct tag&type)=
             type_descriptor(struct)struct_bytes(32)!num_bases(3),
             base_virtual(no)inheritence_public(no)base_offset(0),
             base_class_type_ref(A);
             base_virtual(yes)inheritence_public(no)base_offset(NIL),
             base_class_type_ref(B);
             base_virtual(no)inheritence_public(yes)base_offset(64),
             base_class_type_ref(C); ...

     .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:
             1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt:
             :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;
             28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0

\1f
File: stabs.info,  Node: Virtual Base Classes,  Next: Static Members,  Prev: Inheritence,  Up: Cplusplus

Virtual Base Classes
====================

   A derived class object consists of a concatination in memory of the
data areas defined by each base class, starting with the leftmost and
ending with the rightmost in the list of base classes.  The exception
to this rule is for virtual inheritence.  In the example above, class
`D' inherits virtually from base class `B'.  This means that an
instance of a `D' object will not contain its own `B' part but merely a
pointer to a `B' part, known as a virtual base pointer.

   In a derived class stab, the base offset part of the derivation
information, described above, shows how the base class parts are
ordered.  The base offset for a virtual base class is always given as 0.
Notice that the base offset for `B' is given as 0 even though `B' is
not the first base class.  The first base class `A' starts at offset 0.

   The field information part of the stab for class `D' describes the
field which is the pointer to the virtual base class `B'. The vbase
pointer name is `$vb' followed by a type reference to the virtual base
class.  Since the type id for `B' in this example is 25, the vbase
pointer name is `$vb25'.

     .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1,
            160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i;
            2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt:
            :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0

   Following the name and a semicolon is a type reference describing the
type of the virtual base class pointer, in this case 24.  Type 24 was
defined earlier as the type of the `B' class `this' pointer.  The
`this' pointer for a class is a pointer to the class type.

     .stabs "this:P24=*25=xsB:",64,0,0,8

   Finally the field offset part of the vbase pointer field description
shows that the vbase pointer is the first field in the `D' object,
before any data fields defined by the class.  The layout of a `D' class
object is a follows, `Adat' at 0, the vtable pointer for `A' at 32,
`Cdat' at 64, the vtable pointer for C at 96, the virtual base pointer
for `B' at 128, and `Ddat' at 160.

\1f
File: stabs.info,  Node: Static Members,  Prev: Virtual Base Classes,  Up: Cplusplus

Static Members
==============

   The data area for a class is a concatenation of the space used by the
data members of the class.  If the class has virtual methods, a vtable
pointer follows the class data.  The field offset part of each field
description in the class stab shows this ordering.

   << How is this reflected in stabs?  See Cygnus bug #677 for some
info.  >>

\1f
File: stabs.info,  Node: Stab Types,  Next: Symbol Descriptors,  Prev: Cplusplus,  Up: Top

Table of Stab Types
*******************

   The following are all the possible values for the stab type field,
for a.out files, in numeric order.  This does not apply to XCOFF, but
it does apply to stabs in sections (*note 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 `include/aout/stabs.def'.

* Menu:

* Non-Stab Symbol Types::       Types from 0 to 0x1f
* Stab Symbol Types::           Types from 0x20 to 0xff

\1f
File: stabs.info,  Node: Non-Stab Symbol Types,  Next: Stab Symbol Types,  Up: Stab Types

Non-Stab Symbol Types
=====================

   The following types are used by the linker and assembler, not by stab
directives.  Since this document does not attempt to describe aspects of
object file format other than the debugging format, no details are
given.

`0x0     N_UNDF'
     Undefined symbol

`0x2     N_ABS'
     File scope absolute symbol

`0x3     N_ABS | N_EXT'
     External absolute symbol

`0x4     N_TEXT'
     File scope text symbol

`0x5     N_TEXT | N_EXT'
     External text symbol

`0x6     N_DATA'
     File scope data symbol

`0x7     N_DATA | N_EXT'
     External data symbol

`0x8     N_BSS'
     File scope BSS symbol

`0x9     N_BSS | N_EXT'
     External BSS symbol

`0x0c    N_FN_SEQ'
     Same as `N_FN', for Sequent compilers

`0x0a    N_INDR'
     Symbol is indirected to another symbol

`0x12    N_COMM'
     Common--visible after shared library dynamic link

`0x14 N_SETA'
`0x15 N_SETA | N_EXT'
     Absolute set element

`0x16 N_SETT'
`0x17 N_SETT | N_EXT'
     Text segment set element

`0x18 N_SETD'
`0x19 N_SETD | N_EXT'
     Data segment set element

`0x1a N_SETB'
`0x1b N_SETB | N_EXT'
     BSS segment set element

`0x1c N_SETV'
`0x1d N_SETV | N_EXT'
     Pointer to set vector

`0x1e N_WARNING'
     Print a warning message during linking

`0x1f    N_FN'
     File name of a `.o' file

\1f
File: stabs.info,  Node: Stab Symbol Types,  Prev: Non-Stab Symbol Types,  Up: Stab Types

Stab Symbol Types
=================

   The following symbol types indicate that this is a stab.  This is the
full list of stab numbers, including stab types that are used in
languages other than C.

`0x20     N_GSYM'
     Global symbol; see *Note Global Variables::.

`0x22     N_FNAME'
     Function name (for BSD Fortran); see *Note Procedures::.

`0x24     N_FUN'
     Function name (*note Procedures::.) or text segment variable
     (*note Statics::.).

`0x26 N_STSYM'
     Data segment file-scope variable; see *Note Statics::.

`0x28 N_LCSYM'
     BSS segment file-scope variable; see *Note Statics::.

`0x2a N_MAIN'
     Name of main routine; see *Note Main Program::.

`0x2c N_ROSYM'
     Variable in `.rodata' section; see *Note Statics::.

`0x30     N_PC'
     Global symbol (for Pascal); see *Note N_PC::.

`0x32     N_NSYMS'
     Number of symbols (according to Ultrix V4.0); see *Note N_NSYMS::.

`0x34     N_NOMAP'
     No DST map; see *Note N_NOMAP::.

`0x38 N_OBJ'
     Object file (Solaris2).

`0x3c N_OPT'
     Debugger options (Solaris2).

`0x40     N_RSYM'
     Register variable; see *Note Register Variables::.

`0x42     N_M2C'
     Modula-2 compilation unit; see *Note N_M2C::.

`0x44     N_SLINE'
     Line number in text segment; see *Note Line Numbers::.

`0x46     N_DSLINE'
     Line number in data segment; see *Note Line Numbers::.

`0x48     N_BSLINE'
     Line number in bss segment; see *Note Line Numbers::.

`0x48     N_BROWS'
     Sun source code browser, path to `.cb' file; see *Note N_BROWS::.

`0x4a     N_DEFD'
     GNU Modula2 definition module dependency; see *Note N_DEFD::.

`0x4c N_FLINE'
     Function start/body/end line numbers (Solaris2).

`0x50     N_EHDECL'
     GNU C++ exception variable; see *Note N_EHDECL::.

`0x50     N_MOD2'
     Modula2 info "for imc" (according to Ultrix V4.0); see *Note
     N_MOD2::.

`0x54     N_CATCH'
     GNU C++ `catch' clause; see *Note N_CATCH::.

`0x60     N_SSYM'
     Structure of union element; see *Note N_SSYM::.

`0x62 N_ENDM'
     Last stab for module (Solaris2).

`0x64     N_SO'
     Path and name of source file; see *Note Source Files::.

`0x80 N_LSYM'
     Stack variable (*note Stack Variables::.) or type (*note
     Typedefs::.).

`0x82     N_BINCL'
     Beginning of an include file (Sun only); see *Note Include Files::.

`0x84     N_SOL'
     Name of include file; see *Note Include Files::.

`0xa0     N_PSYM'
     Parameter variable; see *Note Parameters::.

`0xa2     N_EINCL'
     End of an include file; see *Note Include Files::.

`0xa4     N_ENTRY'
     Alternate entry point; see *Note Alternate Entry Points::.

`0xc0     N_LBRAC'
     Beginning of a lexical block; see *Note Block Structure::.

`0xc2     N_EXCL'
     Place holder for a deleted include file; see *Note Include Files::.

`0xc4     N_SCOPE'
     Modula2 scope information (Sun linker); see *Note N_SCOPE::.

`0xe0     N_RBRAC'
     End of a lexical block; see *Note Block Structure::.

`0xe2     N_BCOMM'
     Begin named common block; see *Note Common Blocks::.

`0xe4     N_ECOMM'
     End named common block; see *Note Common Blocks::.

`0xe8     N_ECOML'
     Member of a common block; see *Note Common Blocks::.

`0xea N_WITH'
     Pascal `with' statement: type,,0,0,offset (Solaris2).

`0xf0     N_NBTEXT'
     Gould non-base registers; see *Note Gould::.

`0xf2     N_NBDATA'
     Gould non-base registers; see *Note Gould::.

`0xf4     N_NBBSS'
     Gould non-base registers; see *Note Gould::.

`0xf6     N_NBSTS'
     Gould non-base registers; see *Note Gould::.

`0xf8     N_NBLCS'
     Gould non-base registers; see *Note Gould::.

\1f
File: stabs.info,  Node: Symbol Descriptors,  Next: Type Descriptors,  Prev: Stab Types,  Up: Top

Table of Symbol Descriptors
***************************

   The symbol descriptor is the character which follows the colon in
many stabs, and which tells what kind of stab it is.  *Note String
Field::, for more information about their use.

`DIGIT'
`('
`-'
     Variable on the stack; see *Note Stack Variables::.

`:'
     C++ nested symbol; see *Note Nested Symbols::

`a'
     Parameter passed by reference in register; see *Note Reference
     Parameters::.

`b'
     Based variable; see *Note Based Variables::.

`c'
     Constant; see *Note Constants::.

`C'
     Conformant array bound (Pascal, maybe other languages); *Note
     Conformant Arrays::.  Name of a caught exception (GNU C++).  These
     can be distinguished because the latter uses `N_CATCH' and the
     former uses another symbol type.

`d'
     Floating point register variable; see *Note Register Variables::.

`D'
     Parameter in floating point register; see *Note Register
     Parameters::.

`f'
     File scope function; see *Note Procedures::.

`F'
     Global function; see *Note Procedures::.

`G'
     Global variable; see *Note Global Variables::.

`i'
     *Note Register Parameters::.

`I'
     Internal (nested) procedure; see *Note Nested Procedures::.

`J'
     Internal (nested) function; see *Note Nested Procedures::.

`L'
     Label name (documented by AIX, no further information known).

`m'
     Module; see *Note Procedures::.

`p'
     Argument list parameter; see *Note Parameters::.

`pP'
     *Note Parameters::.

`pF'
     Fortran Function parameter; see *Note Parameters::.

`P'
     Unfortunately, three separate meanings have been independently
     invented for this symbol descriptor.  At least the GNU and Sun
     uses can be distinguished by the symbol type.  Global Procedure
     (AIX) (symbol type used unknown); see *Note Procedures::.
     Register parameter (GNU) (symbol type `N_PSYM'); see *Note
     Parameters::.  Prototype of function referenced by this file (Sun
     `acc') (symbol type `N_FUN').

`Q'
     Static Procedure; see *Note Procedures::.

`R'
     Register parameter; see *Note Register Parameters::.

`r'
     Register variable; see *Note Register Variables::.

`S'
     File scope variable; see *Note Statics::.

`s'
     Local variable (OS9000).

`t'
     Type name; see *Note Typedefs::.

`T'
     Enumeration, structure, or union tag; see *Note Typedefs::.

`v'
     Parameter passed by reference; see *Note Reference Parameters::.

`V'
     Procedure scope static variable; see *Note Statics::.

`x'
     Conformant array; see *Note Conformant Arrays::.

`X'
     Function return variable; see *Note Parameters::.

\1f
File: stabs.info,  Node: Type Descriptors,  Next: Expanded Reference,  Prev: Symbol Descriptors,  Up: Top

Table of Type Descriptors
*************************

   The type descriptor is the character which follows the type number
and an equals sign.  It specifies what kind of type is being defined.
*Note String Field::, for more information about their use.

`DIGIT'
`('
     Type reference; see *Note String Field::.

`-'
     Reference to builtin type; see *Note Negative Type Numbers::.

`#'
     Method (C++); see *Note Method Type Descriptor::.

`*'
     Pointer; see *Note Miscellaneous Types::.

`&'
     Reference (C++).

`@'
     Type Attributes (AIX); see *Note String Field::.  Member (class
     and variable) type (GNU C++); see *Note Member Type Descriptor::.

`a'
     Array; see *Note Arrays::.

`A'
     Open array; see *Note Arrays::.

`b'
     Pascal space type (AIX); see *Note Miscellaneous Types::.  Builtin
     integer type (Sun); see *Note Builtin Type Descriptors::.  Const
     and volatile qualfied type (OS9000).

`B'
     Volatile-qualified type; see *Note Miscellaneous Types::.

`c'
     Complex builtin type (AIX); see *Note Builtin Type Descriptors::.
     Const-qualified type (OS9000).

`C'
     COBOL Picture type.  See AIX documentation for details.

`d'
     File type; see *Note Miscellaneous Types::.

`D'
     N-dimensional dynamic array; see *Note Arrays::.

`e'
     Enumeration type; see *Note Enumerations::.

`E'
     N-dimensional subarray; see *Note Arrays::.

`f'
     Function type; see *Note Function Types::.

`F'
     Pascal function parameter; see *Note Function Types::

`g'
     Builtin floating point type; see *Note Builtin Type Descriptors::.

`G'
     COBOL Group.  See AIX documentation for details.

`i'
     Imported type (AIX); see *Note Cross-References::.
     Volatile-qualified type (OS9000).

`k'
     Const-qualified type; see *Note Miscellaneous Types::.

`K'
     COBOL File Descriptor.  See AIX documentation for details.

`M'
     Multiple instance type; see *Note Miscellaneous Types::.

`n'
     String type; see *Note Strings::.

`N'
     Stringptr; see *Note Strings::.

`o'
     Opaque type; see *Note Typedefs::.

`p'
     Procedure; see *Note Function Types::.

`P'
     Packed array; see *Note Arrays::.

`r'
     Range type; see *Note Subranges::.

`R'
     Builtin floating type; see *Note Builtin Type Descriptors:: (Sun).
     Pascal subroutine parameter; see *Note Function Types:: (AIX).
     Detecting this conflict is possible with careful parsing (hint: a
     Pascal subroutine parameter type will always contain a comma, and
     a builtin type descriptor never will).

`s'
     Structure type; see *Note Structures::.

`S'
     Set type; see *Note Miscellaneous Types::.

`u'
     Union; see *Note Unions::.

`v'
     Variant record.  This is a Pascal and Modula-2 feature which is
     like a union within a struct in C.  See AIX documentation for
     details.

`w'
     Wide character; see *Note Builtin Type Descriptors::.

`x'
     Cross-reference; see *Note Cross-References::.

`Y'
     Used by IBM's xlC C++ compiler (for structures, I think).

`z'
     gstring; see *Note Strings::.

\1f
File: stabs.info,  Node: Expanded Reference,  Next: Questions,  Prev: Type Descriptors,  Up: Top

Expanded Reference by Stab Type
*******************************

   For a full list of stab types, and cross-references to where they are
described, see *Note Stab Types::.  This appendix just covers certain
stabs which are not yet described in the main body of this document;
eventually the information will all be in one place.

   Format of an entry:

   The first line is the symbol type (see `include/aout/stab.def').

   The second line describes the language constructs the symbol type
represents.

   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.

   Finally, any further information.

* Menu:

* N_PC::                        Pascal global symbol
* N_NSYMS::                     Number of symbols
* N_NOMAP::                     No DST map
* N_M2C::                       Modula-2 compilation unit
* N_BROWS::                     Path to .cb file for Sun source code browser
* N_DEFD::                      GNU Modula2 definition module dependency
* N_EHDECL::                    GNU C++ exception variable
* N_MOD2::                      Modula2 information "for imc"
* N_CATCH::                     GNU C++ "catch" clause
* N_SSYM::                      Structure or union element
* N_SCOPE::                     Modula2 scope information (Sun only)
* Gould::                       non-base register symbols used on Gould systems
* N_LENG::                      Length of preceding entry

\1f
File: stabs.info,  Node: N_PC,  Next: N_NSYMS,  Up: Expanded Reference

N_PC
====

 - `.stabs': N_PC
     Global symbol (for Pascal).

          "name" -> "symbol_name"  <<?>>
          value  -> supposedly the line number (stab.def is skeptical)

          `stabdump.c' says:
          
          global pascal symbol: name,,0,subtype,line
          << subtype? >>

\1f
File: stabs.info,  Node: N_NSYMS,  Next: N_NOMAP,  Prev: N_PC,  Up: Expanded Reference

N_NSYMS
=======

 - `.stabn': N_NSYMS
     Number of symbols (according to Ultrix V4.0).

                  0, files,,funcs,lines (stab.def)

\1f
File: stabs.info,  Node: N_NOMAP,  Next: N_M2C,  Prev: N_NSYMS,  Up: Expanded Reference

N_NOMAP
=======

 - `.stabs': N_NOMAP
     No DST map for symbol (according to Ultrix V4.0).  I think this
     means a variable has been optimized out.

                  name, ,0,type,ignored (stab.def)

\1f
File: stabs.info,  Node: N_M2C,  Next: N_BROWS,  Prev: N_NOMAP,  Up: Expanded Reference

N_M2C
=====

 - `.stabs': N_M2C
     Modula-2 compilation unit.

          "string" -> "unit_name,unit_time_stamp[,code_time_stamp]"
          desc   -> unit_number
          value  -> 0 (main unit)
                    1 (any other unit)

     See `Dbx and Dbxtool Interfaces', 2nd edition, by Sun, 1988, for
     more information.


\1f
File: stabs.info,  Node: N_BROWS,  Next: N_DEFD,  Prev: N_M2C,  Up: Expanded Reference

N_BROWS
=======

 - `.stabs': N_BROWS
     Sun source code browser, path to `.cb' file

     <<?>> "path to associated `.cb' file"

     Note: N_BROWS has the same value as N_BSLINE.

\1f
File: stabs.info,  Node: N_DEFD,  Next: N_EHDECL,  Prev: N_BROWS,  Up: Expanded Reference

N_DEFD
======

 - `.stabn': N_DEFD
     GNU Modula2 definition module dependency.

     GNU Modula-2 definition module dependency.  The value is the
     modification time of the definition file.  The other field is
     non-zero if it is imported with the GNU M2 keyword `%INITIALIZE'.
     Perhaps `N_M2C' can be used if there are enough empty fields?

\1f
File: stabs.info,  Node: N_EHDECL,  Next: N_MOD2,  Prev: N_DEFD,  Up: Expanded Reference

N_EHDECL
========

 - `.stabs': N_EHDECL
     GNU C++ exception variable <<?>>.

     "STRING is variable name"

     Note: conflicts with `N_MOD2'.

\1f
File: stabs.info,  Node: N_MOD2,  Next: N_CATCH,  Prev: N_EHDECL,  Up: Expanded Reference

N_MOD2
======

 - `.stab?': N_MOD2
     Modula2 info "for imc" (according to Ultrix V4.0)

     Note: conflicts with `N_EHDECL'  <<?>>

\1f
File: stabs.info,  Node: N_CATCH,  Next: N_SSYM,  Prev: N_MOD2,  Up: Expanded Reference

N_CATCH
=======

 - `.stabn': N_CATCH
     GNU C++ `catch' clause

     GNU C++ `catch' clause.  The value is its address.  The desc field
     is nonzero if this entry is immediately followed by a `CAUGHT' stab
     saying what exception was caught.  Multiple `CAUGHT' stabs means
     that multiple exceptions can be caught here.  If desc is 0, it
     means all exceptions are caught here.

\1f
File: stabs.info,  Node: N_SSYM,  Next: N_SCOPE,  Prev: N_CATCH,  Up: Expanded Reference

N_SSYM
======

 - `.stabn': N_SSYM
     Structure or union element.

     The value is the offset in the structure.

     <<?looking at structs and unions in C I didn't see these>>

\1f
File: stabs.info,  Node: N_SCOPE,  Next: Gould,  Prev: N_SSYM,  Up: Expanded Reference

N_SCOPE
=======

 - `.stab?': N_SCOPE
     Modula2 scope information (Sun linker) <<?>>

\1f
File: stabs.info,  Node: Gould,  Next: N_LENG,  Prev: N_SCOPE,  Up: Expanded Reference

Non-base registers on Gould systems
===================================

 - `.stab?': N_NBTEXT
 - `.stab?': N_NBDATA
 - `.stab?': N_NBBSS
 - `.stab?': N_NBSTS
 - `.stab?': N_NBLCS
     These are used on Gould systems for non-base registers syms.

     However, the following values are not the values used by Gould;
     they are the values which GNU has been documenting for these
     values for a long time, without actually checking what Gould uses.
     I include these values only because perhaps some someone actually
     did something with the GNU information (I hope not, why GNU
     knowingly assigned wrong values to these in the header file is a
     complete mystery to me).

          240    0xf0     N_NBTEXT  ??
          242    0xf2     N_NBDATA  ??
          244    0xf4     N_NBBSS   ??
          246    0xf6     N_NBSTS   ??
          248    0xf8     N_NBLCS   ??

\1f
File: stabs.info,  Node: N_LENG,  Prev: Gould,  Up: Expanded Reference

N_LENG
======

 - `.stabn': N_LENG
     Second symbol entry containing a length-value for the preceding
     entry.  The value is the length.

\1f
File: stabs.info,  Node: Questions,  Next: Stab Sections,  Prev: Expanded Reference,  Up: Top

Questions and Anomalies
***********************

   * For GNU C stabs defining local and global variables (`N_LSYM' and
     `N_GSYM'), the desc field is supposed to contain the source line
     number on which the variable is defined.  In reality the desc
     field is always 0.  (This behavior is defined in `dbxout.c' and
     putting a line number in desc is controlled by `#ifdef
     WINNING_GDB', which defaults to false). GDB supposedly uses this
     information if you say `list VAR'.  In reality, VAR can be a
     variable defined in the program and GDB says `function VAR not
     defined'.

   * In GNU C stabs, there seems to be no way to differentiate tag
     types: structures, unions, and enums (symbol descriptor `T') and
     typedefs (symbol descriptor `t') defined at file scope from types
     defined locally to a procedure or other more local scope.  They
     all use the `N_LSYM' stab type.  Types defined at procedure scope
     are emited after the `N_RBRAC' of the preceding function and
     before the code of the procedure in which they are defined.  This
     is exactly the same as types defined in the source file between
     the two procedure bodies.  GDB overcompensates by placing all
     types in block #1, the block for symbols of file scope.  This is
     true for default, `-ansi' and `-traditional' compiler options.
     (Bugs gcc/1063, gdb/1066.)

   * What ends the procedure scope?  Is it the proc block's `N_RBRAC'
     or the next `N_FUN'?  (I believe its the first.)

\1f
File: stabs.info,  Node: Stab Sections,  Next: Symbol Types Index,  Prev: Questions,  Up: Top

Using Stabs in Their Own Sections
*********************************

   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

\1f
File: stabs.info,  Node: Stab Section Basics,  Next: ELF Linker Relocation,  Up: Stab Sections

How to Embed Stabs in Sections
==============================

   The assembler creates two custom sections, a section named `.stab'
which contains an array of fixed length structures, one struct per stab,
and a section named `.stabstr' containing all the variable length
strings that are referenced by stabs in the `.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 `EI_DATA' field in the `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 (*note Symbol Table Format::.), except that
the `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 `.stab' section for each compilation unit is
synthetic, generated entirely by the assembler, with no corresponding
`.stab' directive as input to the assembler.  This stab contains the
following fields:

`n_strx'
     Offset in the `.stabstr' section to the source filename.

`n_type'
     `N_UNDF'.

`n_other'
     Unused field, always zero.  This may eventually be used to hold
     overflows from the count in the `n_desc' field.

`n_desc'
     Count of upcoming symbols, i.e., the number of remaining stabs for
     this source file.

`n_value'
     Size of the string table fragment associated with this source
     file, in bytes.

   The `.stabstr' section always starts with a null byte (so that string
offsets of zero reference a null string), followed by random length
strings, each of which is null byte terminated.

   The ELF section header for the `.stab' section has its `sh_link'
member set to the section number of the `.stabstr' section, and the
`.stabstr' section has its ELF section header `sh_type' member set to
`SHT_STRTAB' to mark it as a string table.  SOM and COFF have no way of
linking the sections together or marking them as string tables.

   For COFF, the `.stab' and `.stabstr' sections may be simply
concatenated by the linker.  GDB then uses the `n_desc' fields to
figure out the extent of the original sections.  Similarly, the
`n_value' fields of the header symbols are added together in order to
get the actual position of the strings in a desired `.stabstr' section.
Although this design obviates any need for the linker to relocate or
otherwise manipulate `.stab' and `.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 `.stabstr' sections
before concatenating, then the offsets to strings in the middle of the
executable's `.stabstr' section would be wrong.

   The GNU linker is able to optimize stabs information by merging
duplicate strings and removing duplicate header file information (*note
Include Files::.).  When some versions of the GNU linker optimize stabs
in sections, they remove the leading `N_UNDF' symbol and arranges for
all the `n_strx' fields to be relative to the start of the `.stabstr'
section.

\1f
File: stabs.info,  Node: ELF Linker Relocation,  Prev: Stab Section Basics,  Up: Stab Sections

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 `N_SLINE', `N_RBRAC',
and `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 `n_value' field (functions
and static variables) relative to the source file.  For the `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
`Bbss.bss' for the bss section, `Ddata.data' for the data section, and
`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, *Note 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
`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 `S' symbol descriptor stabs (*note Statics::.) and functions
(*note 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 `Ttext.text' symbol, analogous
to the `Bbss.bss', etc., symbols.  I recommend this rather than using a
zero value and getting the address from the ELF symbols.

   Finding the correct `Bbss.bss', etc., symbol is difficult, because
the linker simply concatenates the `.stab' sections from each `.o' file
without including any information about which part of a `.stab' section
comes from which `.o' file.  The way GDB does this is to look for an
ELF `STT_FILE' symbol which has the same name as the last component of
the file name from the `N_SO' symbol in the stabs (for example, if the
file name is `../../gdb/main.c', it looks for an ELF `STT_FILE' symbol
named `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 `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.