diff options
Diffstat (limited to 'gdb/doc/stabs.info-2')
| -rw-r--r-- | gdb/doc/stabs.info-2 | 1286 |
1 files changed, 1286 insertions, 0 deletions
diff --git a/gdb/doc/stabs.info-2 b/gdb/doc/stabs.info-2 new file mode 100644 index 00000000000..7e4e40e2200 --- /dev/null +++ b/gdb/doc/stabs.info-2 @@ -0,0 +1,1286 @@ +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: Conformant Arrays, Prev: Reference Parameters, Up: Parameters + +Passing Conformant Array Parameters +----------------------------------- + + Conformant arrays are a feature of Modula-2, and perhaps other +languages, in which the size of an array parameter is not known to the +called function until run-time. Such parameters have two stabs: a `x' +for the array itself, and a `C', which represents the size of the +array. The value of the `x' stab is the offset in the argument list +where the address of the array is stored (it this right? it is a +guess); the value of the `C' stab is the offset in the argument list +where the size of the array (in elements? in bytes?) is stored. + + +File: stabs.info, Node: Types, Next: Symbol Tables, Prev: Variables, Up: Top + +Defining Types +************** + + The examples so far have described types as references to previously +defined types, or defined in terms of subranges of or pointers to +previously defined types. This chapter describes the other type +descriptors that may follow the `=' in a type definition. + +* Menu: + +* Builtin Types:: Integers, floating point, void, etc. +* Miscellaneous Types:: Pointers, sets, files, etc. +* Cross-References:: Referring to a type not yet defined. +* Subranges:: A type with a specific range. +* Arrays:: An aggregate type of same-typed elements. +* Strings:: Like an array but also has a length. +* Enumerations:: Like an integer but the values have names. +* Structures:: An aggregate type of different-typed elements. +* Typedefs:: Giving a type a name. +* Unions:: Different types sharing storage. +* Function Types:: + + +File: stabs.info, Node: Builtin Types, Next: Miscellaneous Types, Up: Types + +Builtin Types +============= + + Certain types are built in (`int', `short', `void', `float', etc.); +the debugger recognizes these types and knows how to handle them. +Thus, don't be surprised if some of the following ways of specifying +builtin types do not specify everything that a debugger would need to +know about the type--in some cases they merely specify enough +information to distinguish the type from other types. + + The traditional way to define builtin types is convolunted, so new +ways have been invented to describe them. Sun's `acc' uses special +builtin type descriptors (`b' and `R'), and IBM uses negative type +numbers. GDB accepts all three ways, as of version 4.8; dbx just +accepts the traditional builtin types and perhaps one of the other two +formats. The following sections describe each of these formats. + +* Menu: + +* Traditional Builtin Types:: Put on your seatbelts and prepare for kludgery +* Builtin Type Descriptors:: Builtin types with special type descriptors +* Negative Type Numbers:: Builtin types using negative type numbers + + +File: stabs.info, Node: Traditional Builtin Types, Next: Builtin Type Descriptors, Up: Builtin Types + +Traditional Builtin Types +------------------------- + + This is the traditional, convoluted method for defining builtin +types. There are several classes of such type definitions: integer, +floating point, and `void'. + +* Menu: + +* Traditional Integer Types:: +* Traditional Other Types:: + + +File: stabs.info, Node: Traditional Integer Types, Next: Traditional Other Types, Up: Traditional Builtin Types + +Traditional Integer Types +......................... + + Often types are defined as subranges of themselves. If the bounding +values fit within an `int', then they are given normally. For example: + + .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 # 128 is N_LSYM + .stabs "char:t2=r2;0;127;",128,0,0,0 + + Builtin types can also be described as subranges of `int': + + .stabs "unsigned short:t6=r1;0;65535;",128,0,0,0 + + If the lower bound of a subrange is 0 and the upper bound is -1, the +type is an unsigned integral type whose bounds are too big to describe +in an `int'. Traditionally this is only used for `unsigned int' and +`unsigned long': + + .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 + + For larger types, GCC 2.4.5 puts out bounds in octal, with one or +more leading zeroes. In this case a negative bound consists of a number +which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in +the number (except the sign bit), and a positive bound is one which is a +1 bit for each bit in the number (except possibly the sign bit). All +known versions of dbx and GDB version 4 accept this (at least in the +sense of not refusing to process the file), but GDB 3.5 refuses to read +the whole file containing such symbols. So GCC 2.3.3 did not output the +proper size for these types. As an example of octal bounds, the string +fields of the stabs for 64 bit integer types look like: + + long int:t3=r1;001000000000000000000000;000777777777777777777777; + long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777; + + If the lower bound of a subrange is 0 and the upper bound is +negative, the type is an unsigned integral type whose size in bytes is +the absolute value of the upper bound. I believe this is a Convex +convention for `unsigned long long'. + + If the lower bound of a subrange is negative and the upper bound is +0, the type is a signed integral type whose size in bytes is the +absolute value of the lower bound. I believe this is a Convex +convention for `long long'. To distinguish this from a legitimate +subrange, the type should be a subrange of itself. I'm not sure whether +this is the case for Convex. + + +File: stabs.info, Node: Traditional Other Types, Prev: Traditional Integer Types, Up: Traditional Builtin Types + +Traditional Other Types +....................... + + If the upper bound of a subrange is 0 and the lower bound is +positive, the type is a floating point type, and the lower bound of the +subrange indicates the number of bytes in the type: + + .stabs "float:t12=r1;4;0;",128,0,0,0 + .stabs "double:t13=r1;8;0;",128,0,0,0 + + However, GCC writes `long double' the same way it writes `double', +so there is no way to distinguish. + + .stabs "long double:t14=r1;8;0;",128,0,0,0 + + Complex types are defined the same way as floating-point types; +there is no way to distinguish a single-precision complex from a +double-precision floating-point type. + + The C `void' type is defined as itself: + + .stabs "void:t15=15",128,0,0,0 + + I'm not sure how a boolean type is represented. + + +File: stabs.info, Node: Builtin Type Descriptors, Next: Negative Type Numbers, Prev: Traditional Builtin Types, Up: Builtin Types + +Defining Builtin Types Using Builtin Type Descriptors +----------------------------------------------------- + + This is the method used by Sun's `acc' for defining builtin types. +These are the type descriptors to define builtin types: + +`b SIGNED CHAR-FLAG WIDTH ; OFFSET ; NBITS ;' + Define an integral type. SIGNED is `u' for unsigned or `s' for + signed. CHAR-FLAG is `c' which indicates this is a character + type, or is omitted. I assume this is to distinguish an integral + type from a character type of the same size, for example it might + make sense to set it for the C type `wchar_t' so the debugger can + print such variables differently (Solaris does not do this). Sun + sets it on the C types `signed char' and `unsigned char' which + arguably is wrong. WIDTH and OFFSET appear to be for small + objects stored in larger ones, for example a `short' in an `int' + register. WIDTH is normally the number of bytes in the type. + OFFSET seems to always be zero. NBITS is the number of bits in + the type. + + Note that type descriptor `b' used for builtin types conflicts with + its use for Pascal space types (*note Miscellaneous Types::.); + they can be distinguished because the character following the type + descriptor will be a digit, `(', or `-' for a Pascal space type, or + `u' or `s' for a builtin type. + +`w' + Documented by AIX to define a wide character type, but their + compiler actually uses negative type numbers (*note Negative Type + Numbers::.). + +`R FP-TYPE ; BYTES ;' + Define a floating point type. FP-TYPE has one of the following + values: + + `1 (NF_SINGLE)' + IEEE 32-bit (single precision) floating point format. + + `2 (NF_DOUBLE)' + IEEE 64-bit (double precision) floating point format. + + `3 (NF_COMPLEX)' + + `4 (NF_COMPLEX16)' + + `5 (NF_COMPLEX32)' + These are for complex numbers. A comment in the GDB source + describes them as Fortran `complex', `double complex', and + `complex*16', respectively, but what does that mean? (i.e., + Single precision? Double precison?). + + `6 (NF_LDOUBLE)' + Long double. This should probably only be used for Sun format + `long double', and new codes should be used for other floating + point formats (`NF_DOUBLE' can be used if a `long double' is + really just an IEEE double, of course). + + BYTES is the number of bytes occupied by the type. This allows a + debugger to perform some operations with the type even if it + doesn't understand FP-TYPE. + +`g TYPE-INFORMATION ; NBITS' + Documented by AIX to define a floating type, but their compiler + actually uses negative type numbers (*note Negative Type + Numbers::.). + +`c TYPE-INFORMATION ; NBITS' + Documented by AIX to define a complex type, but their compiler + actually uses negative type numbers (*note Negative Type + Numbers::.). + + The C `void' type is defined as a signed integral type 0 bits long: + .stabs "void:t19=bs0;0;0",128,0,0,0 + The Solaris compiler seems to omit the trailing semicolon in this +case. Getting sloppy in this way is not a swift move because if a type +is embedded in a more complex expression it is necessary to be able to +tell where it ends. + + I'm not sure how a boolean type is represented. + + +File: stabs.info, Node: Negative Type Numbers, Prev: Builtin Type Descriptors, Up: Builtin Types + +Negative Type Numbers +--------------------- + + This is the method used in XCOFF for defining builtin types. Since +the debugger knows about the builtin types anyway, the idea of negative +type numbers is simply to give a special type number which indicates +the builtin type. There is no stab defining these types. + + There are several subtle issues with negative type numbers. + + One is the size of the type. A builtin type (for example the C types +`int' or `long') might have different sizes depending on compiler +options, the target architecture, the ABI, etc. This issue doesn't +come up for IBM tools since (so far) they just target the RS/6000; the +sizes indicated below for each size are what the IBM RS/6000 tools use. +To deal with differing sizes, either define separate negative type +numbers for each size (which works but requires changing the debugger, +and, unless you get both AIX dbx and GDB to accept the change, +introduces an incompatibility), or use a type attribute (*note String +Field::.) to define a new type with the appropriate size (which merely +requires a debugger which understands type attributes, like AIX dbx or +GDB). For example, + + .stabs "boolean:t10=@s8;-16",128,0,0,0 + + defines an 8-bit boolean type, and + + .stabs "boolean:t10=@s64;-16",128,0,0,0 + + defines a 64-bit boolean type. + + A similar issue is the format of the type. This comes up most often +for floating-point types, which could have various formats (particularly +extended doubles, which vary quite a bit even among IEEE systems). +Again, it is best to define a new negative type number for each +different format; changing the format based on the target system has +various problems. One such problem is that the Alpha has both VAX and +IEEE floating types. One can easily imagine one library using the VAX +types and another library in the same executable using the IEEE types. +Another example is that the interpretation of whether a boolean is true +or false can be based on the least significant bit, most significant +bit, whether it is zero, etc., and different compilers (or different +options to the same compiler) might provide different kinds of boolean. + + The last major issue is the names of the types. The name of a given +type depends *only* on the negative type number given; these do not +vary depending on the language, the target system, or anything else. +One can always define separate type numbers--in the following list you +will see for example separate `int' and `integer*4' types which are +identical except for the name. But compatibility can be maintained by +not inventing new negative type numbers and instead just defining a new +type with a new name. For example: + + .stabs "CARDINAL:t10=-8",128,0,0,0 + + Here is the list of negative type numbers. The phrase "integral +type" is used to mean twos-complement (I strongly suspect that all +machines which use stabs use twos-complement; most machines use +twos-complement these days). + +`-1' + `int', 32 bit signed integral type. + +`-2' + `char', 8 bit type holding a character. Both GDB and dbx on AIX + treat this as signed. GCC uses this type whether `char' is signed + or not, which seems like a bad idea. The AIX compiler (`xlc') + seems to avoid this type; it uses -5 instead for `char'. + +`-3' + `short', 16 bit signed integral type. + +`-4' + `long', 32 bit signed integral type. + +`-5' + `unsigned char', 8 bit unsigned integral type. + +`-6' + `signed char', 8 bit signed integral type. + +`-7' + `unsigned short', 16 bit unsigned integral type. + +`-8' + `unsigned int', 32 bit unsigned integral type. + +`-9' + `unsigned', 32 bit unsigned integral type. + +`-10' + `unsigned long', 32 bit unsigned integral type. + +`-11' + `void', type indicating the lack of a value. + +`-12' + `float', IEEE single precision. + +`-13' + `double', IEEE double precision. + +`-14' + `long double', IEEE double precision. The compiler claims the size + will increase in a future release, and for binary compatibility + you have to avoid using `long double'. I hope when they increase + it they use a new negative type number. + +`-15' + `integer'. 32 bit signed integral type. + +`-16' + `boolean'. 32 bit type. GDB and GCC assume that zero is false, + one is true, and other values have unspecified meaning. I hope + this agrees with how the IBM tools use the type. + +`-17' + `short real'. IEEE single precision. + +`-18' + `real'. IEEE double precision. + +`-19' + `stringptr'. *Note Strings::. + +`-20' + `character', 8 bit unsigned character type. + +`-21' + `logical*1', 8 bit type. This Fortran type has a split + personality in that it is used for boolean variables, but can also + be used for unsigned integers. 0 is false, 1 is true, and other + values are non-boolean. + +`-22' + `logical*2', 16 bit type. This Fortran type has a split + personality in that it is used for boolean variables, but can also + be used for unsigned integers. 0 is false, 1 is true, and other + values are non-boolean. + +`-23' + `logical*4', 32 bit type. This Fortran type has a split + personality in that it is used for boolean variables, but can also + be used for unsigned integers. 0 is false, 1 is true, and other + values are non-boolean. + +`-24' + `logical', 32 bit type. This Fortran type has a split personality + in that it is used for boolean variables, but can also be used for + unsigned integers. 0 is false, 1 is true, and other values are + non-boolean. + +`-25' + `complex'. A complex type consisting of two IEEE single-precision + floating point values. + +`-26' + `complex'. A complex type consisting of two IEEE double-precision + floating point values. + +`-27' + `integer*1', 8 bit signed integral type. + +`-28' + `integer*2', 16 bit signed integral type. + +`-29' + `integer*4', 32 bit signed integral type. + +`-30' + `wchar'. Wide character, 16 bits wide, unsigned (what format? + Unicode?). + +`-31' + `long long', 64 bit signed integral type. + +`-32' + `unsigned long long', 64 bit unsigned integral type. + +`-33' + `logical*8', 64 bit unsigned integral type. + +`-34' + `integer*8', 64 bit signed integral type. + + +File: stabs.info, Node: Miscellaneous Types, Next: Cross-References, Prev: Builtin Types, Up: Types + +Miscellaneous Types +=================== + +`b TYPE-INFORMATION ; BYTES' + Pascal space type. This is documented by IBM; what does it mean? + + This use of the `b' type descriptor can be distinguished from its + use for builtin integral types (*note Builtin Type Descriptors::.) + because the character following the type descriptor is always a + digit, `(', or `-'. + +`B TYPE-INFORMATION' + A volatile-qualified version of TYPE-INFORMATION. This is a Sun + extension. References and stores to a variable with a + volatile-qualified type must not be optimized or cached; they must + occur as the user specifies them. + +`d TYPE-INFORMATION' + File of type TYPE-INFORMATION. As far as I know this is only used + by Pascal. + +`k TYPE-INFORMATION' + A const-qualified version of TYPE-INFORMATION. This is a Sun + extension. A variable with a const-qualified type cannot be + modified. + +`M TYPE-INFORMATION ; LENGTH' + Multiple instance type. The type seems to composed of LENGTH + repetitions of TYPE-INFORMATION, for example `character*3' is + represented by `M-2;3', where `-2' is a reference to a character + type (*note Negative Type Numbers::.). I'm not sure how this + differs from an array. This appears to be a Fortran feature. + LENGTH is a bound, like those in range types; see *Note + Subranges::. + +`S TYPE-INFORMATION' + Pascal set type. TYPE-INFORMATION must be a small type such as an + enumeration or a subrange, and the type is a bitmask whose length + is specified by the number of elements in TYPE-INFORMATION. + + In CHILL, if it is a bitstring instead of a set, also use the `S' + type attribute (*note String Field::.). + +`* TYPE-INFORMATION' + Pointer to TYPE-INFORMATION. + + +File: stabs.info, Node: Cross-References, Next: Subranges, Prev: Miscellaneous Types, Up: Types + +Cross-References to Other Types +=============================== + + A type can be used before it is defined; one common way to deal with +that situation is just to use a type reference to a type which has not +yet been defined. + + Another way is with the `x' type descriptor, which is followed by +`s' for a structure tag, `u' for a union tag, or `e' for a enumerator +tag, followed by the name of the tag, followed by `:'. If the name +contains `::' between a `<' and `>' pair (for C++ templates), such a +`::' does not end the name--only a single `:' ends the name; see *Note +Nested Symbols::. + + For example, the following C declarations: + + struct foo; + struct foo *bar; + +produce: + + .stabs "bar:G16=*17=xsfoo:",32,0,0,0 + + Not all debuggers support the `x' type descriptor, so on some +machines GCC does not use it. I believe that for the above example it +would just emit a reference to type 17 and never define it, but I +haven't verified that. + + Modula-2 imported types, at least on AIX, use the `i' type +descriptor, which is followed by the name of the module from which the +type is imported, followed by `:', followed by the name of the type. +There is then optionally a comma followed by type information for the +type. This differs from merely naming the type (*note Typedefs::.) in +that it identifies the module; I don't understand whether the name of +the type given here is always just the same as the name we are giving +it, or whether this type descriptor is used with a nameless stab (*note +String Field::.), or what. The symbol ends with `;'. + + +File: stabs.info, Node: Subranges, Next: Arrays, Prev: Cross-References, Up: Types + +Subrange Types +============== + + The `r' type descriptor defines a type as a subrange of another +type. It is followed by type information for the type of which it is a +subrange, a semicolon, an integral lower bound, a semicolon, an +integral upper bound, and a semicolon. The AIX documentation does not +specify the trailing semicolon, in an effort to specify array indexes +more cleanly, but a subrange which is not an array index has always +included a trailing semicolon (*note Arrays::.). + + Instead of an integer, either bound can be one of the following: + +`A OFFSET' + The bound is passed by reference on the stack at offset OFFSET + from the argument list. *Note Parameters::, for more information + on such offsets. + +`T OFFSET' + The bound is passed by value on the stack at offset OFFSET from + the argument list. + +`a REGISTER-NUMBER' + The bound is pased by reference in register number REGISTER-NUMBER. + +`t REGISTER-NUMBER' + The bound is passed by value in register number REGISTER-NUMBER. + +`J' + There is no bound. + + Subranges are also used for builtin types; see *Note Traditional +Builtin Types::. + + +File: stabs.info, Node: Arrays, Next: Strings, Prev: Subranges, Up: Types + +Array Types +=========== + + Arrays use the `a' type descriptor. Following the type descriptor +is the type of the index and the type of the array elements. If the +index type is a range type, it ends in a semicolon; otherwise (for +example, if it is a type reference), there does not appear to be any +way to tell where the types are separated. In an effort to clean up +this mess, IBM documents the two types as being separated by a +semicolon, and a range type as not ending in a semicolon (but this is +not right for range types which are not array indexes, *note +Subranges::.). I think probably the best solution is to specify that a +semicolon ends a range type, and that the index type and element type +of an array are separated by a semicolon, but that if the index type is +a range type, the extra semicolon can be omitted. GDB (at least +through version 4.9) doesn't support any kind of index type other than a +range anyway; I'm not sure about dbx. + + It is well established, and widely used, that the type of the index, +unlike most types found in the stabs, is merely a type definition, not +type information (*note String Field::.) (that is, it need not start +with `TYPE-NUMBER=' if it is defining a new type). According to a +comment in GDB, this is also true of the type of the array elements; it +gives `ar1;1;10;ar1;1;10;4' as a legitimate way to express a two +dimensional array. According to AIX documentation, the element type +must be type information. GDB accepts either. + + The type of the index is often a range type, expressed as the type +descriptor `r' and some parameters. It defines the size of the array. +In the example below, the range `r1;0;2;' defines an index type which +is a subrange of type 1 (integer), with a lower bound of 0 and an upper +bound of 2. This defines the valid range of subscripts of a +three-element C array. + + For example, the definition: + + char char_vec[3] = {'a','b','c'}; + +produces the output: + + .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0 + .global _char_vec + .align 4 + _char_vec: + .byte 97 + .byte 98 + .byte 99 + + If an array is "packed", the elements are spaced more closely than +normal, saving memory at the expense of speed. For example, an array +of 3-byte objects might, if unpacked, have each element aligned on a +4-byte boundary, but if packed, have no padding. One way to specify +that something is packed is with type attributes (*note String +Field::.). In the case of arrays, another is to use the `P' type +descriptor instead of `a'. Other than specifying a packed array, `P' +is identical to `a'. + + An open array is represented by the `A' type descriptor followed by +type information specifying the type of the array elements. + + An N-dimensional dynamic array is represented by + + D DIMENSIONS ; TYPE-INFORMATION + + DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies +the type of the array elements. + + A subarray of an N-dimensional array is represented by + + E DIMENSIONS ; TYPE-INFORMATION + + DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies +the type of the array elements. + + +File: stabs.info, Node: Strings, Next: Enumerations, Prev: Arrays, Up: Types + +Strings +======= + + Some languages, like C or the original Pascal, do not have string +types, they just have related things like arrays of characters. But +most Pascals and various other languages have string types, which are +indicated as follows: + +`n TYPE-INFORMATION ; BYTES' + BYTES is the maximum length. I'm not sure what TYPE-INFORMATION + is; I suspect that it means that this is a string of + TYPE-INFORMATION (thus allowing a string of integers, a string of + wide characters, etc., as well as a string of characters). Not + sure what the format of this type is. This is an AIX feature. + +`z TYPE-INFORMATION ; BYTES' + Just like `n' except that this is a gstring, not an ordinary + string. I don't know the difference. + +`N' + Pascal Stringptr. What is this? This is an AIX feature. + + Languages, such as CHILL which have a string type which is basically +just an array of characters use the `S' type attribute (*note String +Field::.). + + +File: stabs.info, Node: Enumerations, Next: Structures, Prev: Strings, Up: Types + +Enumerations +============ + + Enumerations are defined with the `e' type descriptor. + + The source line below declares an enumeration type at file scope. +The type definition is located after the `N_RBRAC' that marks the end of +the previous procedure's block scope, and before the `N_FUN' that marks +the beginning of the next procedure's block scope. Therefore it does +not describe a block local symbol, but a file local one. + + The source line: + + enum e_places {first,second=3,last}; + +generates the following stab: + + .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0 + + The symbol descriptor (`T') says that the stab describes a +structure, enumeration, or union tag. The type descriptor `e', +following the `22=' of the type definition narrows it down to an +enumeration type. Following the `e' is a list of the elements of the +enumeration. The format is `NAME:VALUE,'. The list of elements ends +with `;'. The fact that VALUE is specified as an integer can cause +problems if the value is large. GCC 2.5.2 tries to output it in octal +in that case with a leading zero, which is probably a good thing, +although GDB 4.11 supports octal only in cases where decimal is +perfectly good. Negative decimal values are supported by both GDB and +dbx. + + There is no standard way to specify the size of an enumeration type; +it is determined by the architecture (normally all enumerations types +are 32 bits). Type attributes can be used to specify an enumeration +type of another size for debuggers which support them; see *Note String +Field::. + + Enumeration types are unusual in that they define symbols for the +enumeration values (`first', `second', and `third' in the above +example), and even though these symbols are visible in the file as a +whole (rather than being in a more local namespace like structure +member names), they are defined in the type definition for the +enumeration type rather than each having their own symbol. In order to +be fast, GDB will only get symbols from such types (in its initial scan +of the stabs) if the type is the first thing defined after a `T' or `t' +symbol descriptor (the above example fulfills this requirement). If +the type does not have a name, the compiler should emit it in a +nameless stab (*note String Field::.); GCC does this. + + +File: stabs.info, Node: Structures, Next: Typedefs, Prev: Enumerations, Up: Types + +Structures +========== + + The encoding of structures in stabs can be shown with an example. + + The following source code declares a structure tag and defines an +instance of the structure in global scope. Then a `typedef' equates the +structure tag with a new type. Seperate stabs are generated for the +structure tag, the structure `typedef', and the structure instance. The +stabs for the tag and the `typedef' are emited when the definitions are +encountered. Since the structure elements are not initialized, the +stab and code for the structure variable itself is located at the end +of the program in the bss section. + + struct s_tag { + int s_int; + float s_float; + char s_char_vec[8]; + struct s_tag* s_next; + } g_an_s; + + typedef struct s_tag s_typedef; + + The structure tag has an `N_LSYM' stab type because, like the +enumeration, the symbol has file scope. Like the enumeration, the +symbol descriptor is `T', for enumeration, structure, or tag type. The +type descriptor `s' following the `16=' of the type definition narrows +the symbol type to structure. + + Following the `s' type descriptor is the number of bytes the +structure occupies, followed by a description of each structure element. +The structure element descriptions are of the form NAME:TYPE, BIT +OFFSET FROM THE START OF THE STRUCT, NUMBER OF BITS IN THE ELEMENT. + + # 128 is N_LSYM + .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32; + s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0 + + In this example, the first two structure elements are previously +defined types. For these, the type following the `NAME:' part of the +element description is a simple type reference. The other two structure +elements are new types. In this case there is a type definition +embedded after the `NAME:'. The type definition for the array element +looks just like a type definition for a standalone array. The `s_next' +field is a pointer to the same kind of structure that the field is an +element of. So the definition of structure type 16 contains a type +definition for an element which is a pointer to type 16. + + If a field is a static member (this is a C++ feature in which a +single variable appears to be a field of every structure of a given +type) it still starts out with the field name, a colon, and the type, +but then instead of a comma, bit position, comma, and bit size, there +is a colon followed by the name of the variable which each such field +refers to. + + If the structure has methods (a C++ feature), they follow the +non-method fields; see *Note Cplusplus::. + + +File: stabs.info, Node: Typedefs, Next: Unions, Prev: Structures, Up: Types + +Giving a Type a Name +==================== + + To give a type a name, use the `t' symbol descriptor. The type is +specified by the type information (*note String Field::.) for the stab. +For example, + + .stabs "s_typedef:t16",128,0,0,0 # 128 is N_LSYM + + specifies that `s_typedef' refers to type number 16. Such stabs +have symbol type `N_LSYM' (or `C_DECL' for XCOFF). (The Sun +documentation mentions using `N_GSYM' in some cases). + + If you are specifying the tag name for a structure, union, or +enumeration, use the `T' symbol descriptor instead. I believe C is the +only language with this feature. + + If the type is an opaque type (I believe this is a Modula-2 feature), +AIX provides a type descriptor to specify it. The type descriptor is +`o' and is followed by a name. I don't know what the name means--is it +always the same as the name of the type, or is this type descriptor +used with a nameless stab (*note String Field::.)? There optionally +follows a comma followed by type information which defines the type of +this type. If omitted, a semicolon is used in place of the comma and +the type information, and the type is much like a generic pointer +type--it has a known size but little else about it is specified. + + +File: stabs.info, Node: Unions, Next: Function Types, Prev: Typedefs, Up: Types + +Unions +====== + + union u_tag { + int u_int; + float u_float; + char* u_char; + } an_u; + + This code generates a stab for a union tag and a stab for a union +variable. Both use the `N_LSYM' stab type. If a union variable is +scoped locally to the procedure in which it is defined, its stab is +located immediately preceding the `N_LBRAC' for the procedure's block +start. + + The stab for the union tag, however, is located preceding the code +for the procedure in which it is defined. The stab type is `N_LSYM'. +This would seem to imply that the union type is file scope, like the +struct type `s_tag'. This is not true. The contents and position of +the stab for `u_type' do not convey any infomation about its procedure +local scope. + + # 128 is N_LSYM + .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;", + 128,0,0,0 + + The symbol descriptor `T', following the `name:' means that the stab +describes an enumeration, structure, or union tag. The type descriptor +`u', following the `23=' of the type definition, narrows it down to a +union type definition. Following the `u' is the number of bytes in the +union. After that is a list of union element descriptions. Their +format is NAME:TYPE, BIT OFFSET INTO THE UNION, NUMBER OF BYTES FOR THE +ELEMENT;. + + The stab for the union variable is: + + .stabs "an_u:23",128,0,0,-20 # 128 is N_LSYM + + `-20' specifies where the variable is stored (*note Stack +Variables::.). + + +File: stabs.info, Node: Function Types, Prev: Unions, Up: Types + +Function Types +============== + + Various types can be defined for function variables. These types are +not used in defining functions (*note Procedures::.); they are used for +things like pointers to functions. + + The simple, traditional, type is type descriptor `f' is followed by +type information for the return type of the function, followed by a +semicolon. + + This does not deal with functions for which the number and types of +the parameters are part of the type, as in Modula-2 or ANSI C. AIX +provides extensions to specify these, using the `f', `F', `p', and `R' +type descriptors. + + First comes the type descriptor. If it is `f' or `F', this type +involves a function rather than a procedure, and the type information +for the return type of the function follows, followed by a comma. Then +comes the number of parameters to the function and a semicolon. Then, +for each parameter, there is the name of the parameter followed by a +colon (this is only present for type descriptors `R' and `F' which +represent Pascal function or procedure parameters), type information +for the parameter, a comma, 0 if passed by reference or 1 if passed by +value, and a semicolon. The type definition ends with a semicolon. + + For example, this variable definition: + + int (*g_pf)(); + +generates the following code: + + .stabs "g_pf:G24=*25=f1",32,0,0,0 + .common _g_pf,4,"bss" + + The variable defines a new type, 24, which is a pointer to another +new type, 25, which is a function returning `int'. + + +File: stabs.info, Node: Symbol Tables, Next: Cplusplus, Prev: Types, Up: Top + +Symbol Information in Symbol Tables +*********************************** + + This chapter describes the format of symbol table entries and how +stab assembler directives map to them. It also describes the +transformations that the assembler and linker make on data from stabs. + +* Menu: + +* Symbol Table Format:: +* Transformations On Symbol Tables:: + + +File: stabs.info, Node: Symbol Table Format, Next: Transformations On Symbol Tables, Up: Symbol Tables + +Symbol Table Format +=================== + + Each time the assembler encounters a stab directive, it puts each +field of the stab into a corresponding field in a symbol table entry of +its output file. If the stab contains a string field, the symbol table +entry for that stab points to a string table entry containing the +string data from the stab. Assembler labels become relocatable +addresses. Symbol table entries in a.out have the format: + + struct internal_nlist { + unsigned long n_strx; /* index into string table of name */ + unsigned char n_type; /* type of symbol */ + unsigned char n_other; /* misc info (usually empty) */ + unsigned short n_desc; /* description field */ + bfd_vma n_value; /* value of symbol */ + }; + + If the stab has a string, the `n_strx' field holds the offset in +bytes of the string within the string table. The string is terminated +by a NUL character. If the stab lacks a string (for example, it was +produced by a `.stabn' or `.stabd' directive), the `n_strx' field is +zero. + + Symbol table entries with `n_type' field values greater than 0x1f +originated as stabs generated by the compiler (with one random +exception). The other entries were placed in the symbol table of the +executable by the assembler or the linker. + + +File: stabs.info, Node: Transformations On Symbol Tables, Prev: Symbol Table Format, Up: Symbol Tables + +Transformations on Symbol Tables +================================ + + The linker concatenates object files and does fixups of externally +defined symbols. + + You can see the transformations made on stab data by the assembler +and linker by examining the symbol table after each pass of the build. +To do this, use `nm -ap', which dumps the symbol table, including +debugging information, unsorted. For stab entries the columns are: +VALUE, OTHER, DESC, TYPE, STRING. For assembler and linker symbols, +the columns are: VALUE, TYPE, STRING. + + The low 5 bits of the stab type tell the linker how to relocate the +value of the stab. Thus for stab types like `N_RSYM' and `N_LSYM', +where the value is an offset or a register number, the low 5 bits are +`N_ABS', which tells the linker not to relocate the value. + + Where the value of a stab contains an assembly language label, it is +transformed by each build step. The assembler turns it into a +relocatable address and the linker turns it into an absolute address. + +* Menu: + +* Transformations On Static Variables:: +* Transformations On Global Variables:: +* Stab Section Transformations:: For some object file formats, + things are a bit different. + + +File: stabs.info, Node: Transformations On Static Variables, Next: Transformations On Global Variables, Up: Transformations On Symbol Tables + +Transformations on Static Variables +----------------------------------- + + This source line defines a static variable at file scope: + + static int s_g_repeat + +The following stab describes the symbol: + + .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat + +The assembler transforms the stab into this symbol table entry in the +`.o' file. The location is expressed as a data segment offset. + + 00000084 - 00 0000 STSYM s_g_repeat:S1 + +In the symbol table entry from the executable, the linker has made the +relocatable address absolute. + + 0000e00c - 00 0000 STSYM s_g_repeat:S1 + + +File: stabs.info, Node: Transformations On Global Variables, Next: Stab Section Transformations, Prev: Transformations On Static Variables, Up: Transformations On Symbol Tables + +Transformations on Global Variables +----------------------------------- + + Stabs for global variables do not contain location information. In +this case, the debugger finds location information in the assembler or +linker symbol table entry describing the variable. The source line: + + char g_foo = 'c'; + +generates the stab: + + .stabs "g_foo:G2",32,0,0,0 + + The variable is represented by two symbol table entries in the object +file (see below). The first one originated as a stab. The second one +is an external symbol. The upper case `D' signifies that the `n_type' +field of the symbol table contains 7, `N_DATA' with local linkage. The +stab's value is zero since the value is not used for `N_GSYM' stabs. +The value of the linker symbol is the relocatable address corresponding +to the variable. + + 00000000 - 00 0000 GSYM g_foo:G2 + 00000080 D _g_foo + +These entries as transformed by the linker. The linker symbol table +entry now holds an absolute address: + + 00000000 - 00 0000 GSYM g_foo:G2 + ... + 0000e008 D _g_foo + + +File: stabs.info, Node: Stab Section Transformations, Prev: Transformations On Global Variables, Up: Transformations On Symbol Tables + +Transformations of Stabs in separate sections +--------------------------------------------- + + For object file formats using stabs in separate sections (*note Stab +Sections::.), use `objdump --stabs' instead of `nm' to show the stabs +in an object or executable file. `objdump' is a GNU utility; Sun does +not provide any equivalent. + + The following example is for a stab whose value is an address is +relative to the compilation unit (*note ELF Linker Relocation::.). For +example, if the source line + + static int ld = 5; + + appears within a function, then the assembly language output from the +compiler contains: + + .Ddata.data: + ... + .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data # 0x26 is N_STSYM + ... + .L18: + .align 4 + .word 0x5 + + Because the value is formed by subtracting one symbol from another, +the value is absolute, not relocatable, and so the object file contains + + Symnum n_type n_othr n_desc n_value n_strx String + 31 STSYM 0 4 00000004 680 ld:V(0,3) + + without any relocations, and the executable file also contains + + Symnum n_type n_othr n_desc n_value n_strx String + 31 STSYM 0 4 00000004 680 ld:V(0,3) + + +File: stabs.info, Node: Cplusplus, Next: Stab Types, Prev: Symbol Tables, Up: Top + +GNU C++ Stabs +************* + +* Menu: + +* Class Names:: C++ class names are both tags and typedefs. +* Nested Symbols:: C++ symbol names can be within other types. +* Basic Cplusplus Types:: +* Simple Classes:: +* Class Instance:: +* Methods:: Method definition +* Method Type Descriptor:: The `#' type descriptor +* Member Type Descriptor:: The `@' type descriptor +* Protections:: +* Method Modifiers:: +* Virtual Methods:: +* Inheritence:: +* Virtual Base Classes:: +* Static Members:: + + +File: stabs.info, Node: Class Names, Next: Nested Symbols, Up: Cplusplus + +C++ Class Names +=============== + + In C++, a class name which is declared with `class', `struct', or +`union', is not only a tag, as in C, but also a type name. Thus there +should be stabs with both `t' and `T' symbol descriptors (*note +Typedefs::.). + + To save space, there is a special abbreviation for this case. If the +`T' symbol descriptor is followed by `t', then the stab defines both a +type name and a tag. + + For example, the C++ code + + struct foo {int x;}; + + can be represented as either + + .stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # 128 is N_LSYM + .stabs "foo:t19",128,0,0,0 + + or + + .stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 + + +File: stabs.info, Node: Nested Symbols, Next: Basic Cplusplus Types, Prev: Class Names, Up: Cplusplus + +Defining a Symbol Within Another Type +===================================== + + In C++, a symbol (such as a type name) can be defined within another +type. + + In stabs, this is sometimes represented by making the name of a +symbol which contains `::'. Such a pair of colons does not end the name +of the symbol, the way a single colon would (*note String Field::.). +I'm not sure how consistently used or well thought out this mechanism +is. So that a pair of colons in this position always has this meaning, +`:' cannot be used as a symbol descriptor. + + For example, if the string for a stab is `foo::bar::baz:t5=*6', then +`foo::bar::baz' is the name of the symbol, `t' is the symbol +descriptor, and `5=*6' is the type information. + + +File: stabs.info, Node: Basic Cplusplus Types, Next: Simple Classes, Prev: Nested Symbols, Up: Cplusplus + +Basic Types For C++ +=================== + + << the examples that follow are based on a01.C >> + + C++ adds two more builtin types to the set defined for C. These are +the unknown type and the vtable record type. The unknown type, type +16, is defined in terms of itself like the void type. + + The vtable record type, type 17, is defined as a structure type and +then as a structure tag. The structure has four fields: delta, index, +pfn, and delta2. pfn is the function pointer. + + << In boilerplate $vtbl_ptr_type, what are the fields delta, index, +and delta2 used for? >> + + This basic type is present in all C++ programs even if there are no +virtual methods defined. + + .stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8) + elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16); + elem_name(index):type_ref(short int),bit_offset(16),field_bits(16); + elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void), + bit_offset(32),field_bits(32); + elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;" + N_LSYM, NIL, NIL + + .stabs "$vtbl_ptr_type:t17=s8 + delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;" + ,128,0,0,0 + + .stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL + + .stabs "$vtbl_ptr_type:T17",128,0,0,0 + + +File: stabs.info, Node: Simple Classes, Next: Class Instance, Prev: Basic Cplusplus Types, Up: Cplusplus + +Simple Class Definition +======================= + + The stabs describing C++ language features are an extension of the +stabs describing C. Stabs representing C++ class types elaborate +extensively on the stab format used to describe structure types in C. +Stabs representing class type variables look just like stabs +representing C language variables. + + Consider the following very simple class definition. + + class baseA { + public: + int Adat; + int Ameth(int in, char other); + }; + + The class `baseA' is represented by two stabs. The first stab +describes the class as a structure type. The second stab describes a +structure tag of the class type. Both stabs are of stab type `N_LSYM'. +Since the stab is not located between an `N_FUN' and an `N_LBRAC' stab +this indicates that the class is defined at file scope. If it were, +then the `N_LSYM' would signify a local variable. + + A stab describing a C++ class type is similar in format to a stab +describing a C struct, with each class member shown as a field in the +structure. The part of the struct format describing fields is expanded +to include extra information relevent to C++ class members. In +addition, if the class has multiple base classes or virtual functions +the struct format outside of the field parts is also augmented. + + In this simple example the field part of the C++ class stab +representing member data looks just like the field part of a C struct +stab. The section on protections describes how its format is sometimes +extended for member data. + + The field part of a C++ class stab representing a member function +differs substantially from the field part of a C struct stab. It still +begins with `name:' but then goes on to define a new type number for +the member function, describe its return type, its argument types, its +protection level, any qualifiers applied to the method definition, and +whether the method is virtual or not. If the method is virtual then +the method description goes on to give the vtable index of the method, +and the type number of the first base class defining the method. + + When the field name is a method name it is followed by two colons +rather than one. This is followed by a new type definition for the +method. This is a number followed by an equal sign and the type of the +method. Normally this will be a type declared using the `#' type +descriptor; see *Note Method Type Descriptor::; static member functions +are declared using the `f' type descriptor instead; see *Note Function +Types::. + + The format of an overloaded operator method name differs from that of +other methods. It is `op$::OPERATOR-NAME.' where OPERATOR-NAME is the +operator name such as `+' or `+='. The name ends with a period, and +any characters except the period can occur in the OPERATOR-NAME string. + + The next part of the method description represents the arguments to +the method, preceeded by a colon and ending with a semi-colon. The +types of the arguments are expressed in the same way argument types are +expressed in C++ name mangling. In this example an `int' and a `char' +map to `ic'. + + This is followed by a number, a letter, and an asterisk or period, +followed by another semicolon. The number indicates the protections +that apply to the member function. Here the 2 means public. The +letter encodes any qualifier applied to the method definition. In this +case, `A' means that it is a normal function definition. The dot shows +that the method is not virtual. The sections that follow elaborate +further on these fields and describe the additional information present +for virtual methods. + + .stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4) + field_name(Adat):type(int),bit_offset(0),field_bits(32); + + method_name(Ameth)::type_def(21)=type_desc(method)return_type(int); + :arg_types(int char); + protection(public)qualifier(normal)virtual(no);;" + N_LSYM,NIL,NIL,NIL + + .stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0 + + .stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL + + .stabs "baseA:T20",128,0,0,0 + |