diff options
Diffstat (limited to 'gdb/doc/stabs.info-3')
| -rw-r--r-- | gdb/doc/stabs.info-3 | 1390 |
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. + |