Initial creation of sourceware repositorycvs/GDB_4_18

1 files changed, 1390 insertions, 0 deletions

diff --git a/gdb/doc/stabs.info-3 b/gdb/doc/stabs.info-3
new file mode 100644
index 00000000000..c72f5cb53c6
--- /dev/null
+++ b/gdb/doc/stabs.info-3
@@ -0,0 +1,1390 @@
+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).
+
+
+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
+
+
+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 >>
+
+
+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.
+
+
+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.
+
+
+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
+
+
+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
+
+
+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
+
+
+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
+
+
+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.
+
+
+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.  >>
+
+
+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
+
+
+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
+
+
+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::.
+
+
+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::.
+
+
+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::.
+
+
+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
+
+
+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? >>
+
+
+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)
+
+
+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)
+
+
+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.
+
+
+
+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.
+
+
+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?
+
+
+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'.
+
+
+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'  <<?>>
+
+
+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.
+
+
+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>>
+
+
+File: stabs.info,  Node: N_SCOPE,  Next: Gould,  Prev: N_SSYM,  Up: Expanded Reference
+
+N_SCOPE
+=======
+
+ - `.stab?': N_SCOPE
+     Modula2 scope information (Sun linker) <<?>>
+
+
+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   ??
+
+
+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.
+
+
+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.)
+
+
+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
+
+
+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.
+
+
+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.
+